Client library¶
The NuGet package MessageQueueNET.Client
(.NET Standard 2.1) wraps the REST API. It also contains the services for the
queue worker and app topic patterns.
Client and server version
Use a client with the same major version as the server. Clients older than 4.0 cannot call the 4.x API because some HTTP methods changed.
QueueClient¶
A QueueClient works on one queue name or pattern.
The constructor optionally takes an HttpClient. Without it, a shared static HttpClient is used.
Example¶
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)!
}
- Dequeued messages must be confirmed within 60 seconds, otherwise they go back into the queue.
- Confirm only after the message was processed successfully.
Methods¶
All methods return a result derived from ApiResult (Success, ErrorMessage, HashCode) and accept an
optional CancellationToken. They behave like the REST methods.
| Method | 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 |
Non-success HTTP responses throw a MessageQueueClientException with the StatusCode.
Dependency injection and long polling¶
In ASP.NET Core and worker services, register the MessageQueueClientService. It uses IHttpClientFactory,
checks that client and server major versions match and provides long polling streams:
using MessageQueueNET.Client.Extensions.DependencyInjetion;
builder.Services.AddMessageQueueClientService();
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 ?? [])
{
// process message.Value
}
}
}
}
- Each iteration waits on the server until new messages arrive (long polling), instead of polling in a loop.
GetNextQueueProperties(...) works the same way for queue properties (used by the dashboard).
For complete consumers with workers, results and confirmations, use the queue worker pattern.