Zum Inhalt

Client-Bibliothek

Das NuGet-Paket MessageQueueNET.Client (.NET Standard 2.1) kapselt die REST-API. Es enthält außerdem die Services für die Patterns Queue Worker und App Topic.

dotnet add package MessageQueueNET.Client

Client- und Server-Version

Einen Client mit derselben Major-Version wie der Server verwenden. Clients älter als 4.0 können die 4.x-API nicht aufrufen, weil sich einige HTTP-Methoden geändert haben.

QueueClient

Ein QueueClient arbeitet auf einem Queue-Namen oder einem Muster.

using MessageQueueNET.Client;
using MessageQueueNET.Client.Models;

var client = new QueueClient(
    new MessageQueueConnection("https://worker:secret@mq.example.com"),
    "orders");
using MessageQueueNET.Client;
using MessageQueueNET.Client.Models;
using MessageQueueNET.Client.Models.Authentication;

var client = new QueueClient(
    new MessageQueueConnection("https://mq.example.com")
    {
        Authentication = new BasicAuthentication("worker", "secret")
    },
    "orders");

Der Konstruktor nimmt optional einen HttpClient. Ohne ihn wird ein gemeinsamer statischer HttpClient verwendet.

Beispiel

var client = new QueueClient(new MessageQueueConnection("http://localhost:9091"), "orders");

await client.RegisterAsync(confirmationPeriodSeconds: 60); // (1)!

await client.EnqueueAsync(["order #1", "order #2"]);

var length = await client.LengthAsync();               // length.Queues["orders"].QueueLength == 2

var result = await client.DequeueAsync(count: 1);
foreach (var message in result.Messages ?? [])
{
    Console.WriteLine(message.Value);                  // "order #1"
    await client.ConfirmDequeueAsync(message.Id);      // (2)!
}
  1. Abgeholte Nachrichten müssen innerhalb von 60 Sekunden bestätigt werden, sonst kommen sie zurück in die Queue.
  2. Erst bestätigen, wenn die Nachricht erfolgreich verarbeitet wurde.

Methoden

Alle Methoden liefern ein von ApiResult abgeleitetes Ergebnis (Success, ErrorMessage, HashCode) und akzeptieren ein optionales CancellationToken. Sie verhalten sich wie die REST-Methoden.

Methode REST
ApiInfoAsync() GET /Info
EnqueueAsync(messages) PUT /Queue/enqueue
DequeueAsync(count, register, cancelationToken, hashCode, maxPollingSeconds) POST /Queue/dequeue
ConfirmDequeueAsync(messageId) POST /Queue/confirmdequeue
AllMessagesAsync(max, unconfirmedOnly) GET /Queue/all
LengthAsync() GET /Queue/length
RegisterAsync(lifetimeSeconds, itemLifetimeSeconds, confirmationPeriodSeconds, maxUnconfirmedItems, maxUnconfirmedItemsStrategy, suspendEnqueue, suspendDequeue) PUT /Queue/register
PropertiesAsync(cancelationToken, hashCode, maxPollingSeconds, silentAccess) GET /Queue/properties
QueueNamesAsync() GET /Queue/queuenames
RemoveAsync(removeType) DELETE /Queue/remove
DeleteMessage(messageId) DELETE /Queue/deletemessage

HTTP-Antworten ohne Erfolgsstatus lösen eine MessageQueueClientException mit dem StatusCode aus.

Dependency Injection und Long Polling

In ASP.NET Core und Worker Services den MessageQueueClientService registrieren. Er verwendet IHttpClientFactory, prüft, ob die Major-Versionen von Client und Server übereinstimmen, und stellt Long-Polling-Streams bereit:

Program.cs
using MessageQueueNET.Client.Extensions.DependencyInjetion;

builder.Services.AddMessageQueueClientService();
OrderConsumer.cs
using MessageQueueNET.Client.Models;
using MessageQueueNET.Client.Services;

public class OrderConsumer(MessageQueueClientService mq) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var connection = new MessageQueueConnection("https://worker:secret@mq.example.com");

        await foreach (var result in mq.GetNextMessages(connection, "orders", stoppingToken)) // (1)!
        {
            foreach (var message in result.Messages ?? [])
            {
                // message.Value verarbeiten
            }
        }
    }
}
  1. Jede Iteration wartet am Server, bis neue Nachrichten eintreffen (Long Polling), statt in einer Schleife abzufragen.

GetNextQueueProperties(...) funktioniert genauso für Queue-Eigenschaften (wird vom Dashboard verwendet).

Für vollständige Consumer mit Workern, Ergebnissen und Bestätigungen das Queue-Worker-Pattern verwenden.