Skip to content

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.

dotnet add package MessageQueueNET.Client

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.

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");

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)!
}
  1. Dequeued messages must be confirmed within 60 seconds, otherwise they go back into the queue.
  2. 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:

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 ?? [])
            {
                // process message.Value
            }
        }
    }
}
  1. 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.