Table of Contents

Class QueueClient

Namespace
Microsoft.Azure.ServiceBus
Assembly
Microsoft.Azure.ServiceBus.dll

QueueClient can be used for all basic interactions with a Service Bus Queue.

public class QueueClient : ClientEntity, IQueueClient, IReceiverClient, ISenderClient, IClientEntity
Inheritance
QueueClient
Implements
Inherited Members

Examples

Create a new QueueClient

IQueueClient queueClient = new QueueClient(
    namespaceConnectionString,
    queueName,
    ReceiveMode.PeekLock,
    RetryExponential);

Send a message to the queue:

byte[] data = GetData();
await queueClient.SendAsync(data);

Register a message handler which will be invoked every time a message is received.

queueClient.RegisterMessageHandler(
       async (message, token) =>
       {
           // Process the message
           Console.WriteLine($"Received message: SequenceNumber:{message.SystemProperties.SequenceNumber} Body:{Encoding.UTF8.GetString(message.Body)}");

           // Complete the message so that it is not received again.
           // This can be done only if the queueClient is opened in ReceiveMode.PeekLock mode.
           await queueClient.CompleteAsync(message.SystemProperties.LockToken);
       },
       async (exceptionEvent) =>
       {
           // Process the exception
           Console.WriteLine("Exception = " + exceptionEvent.Exception);
           return Task.CompletedTask;
       });

Remarks

Use MessageSender or MessageReceiver for advanced set of functionality. It uses AMQP protocol for communicating with servicebus.

Constructors

QueueClient(ServiceBusConnection, string, ReceiveMode, RetryPolicy)

Creates a new instance of the Queue client on a given ServiceBusConnection

public QueueClient(ServiceBusConnection serviceBusConnection, string entityPath, ReceiveMode receiveMode, RetryPolicy retryPolicy)

Parameters

serviceBusConnection ServiceBusConnection

Connection object to the service bus namespace.

entityPath string

Queue path.

receiveMode ReceiveMode

Mode of receive of messages. Default to ReceiveMode.PeekLock.

retryPolicy RetryPolicy

Retry policy for queue operations. Defaults to Default

QueueClient(ServiceBusConnectionStringBuilder, ReceiveMode, RetryPolicy)

Instantiates a new QueueClient to perform operations on a queue.

public QueueClient(ServiceBusConnectionStringBuilder connectionStringBuilder, ReceiveMode receiveMode = ReceiveMode.PeekLock, RetryPolicy retryPolicy = null)

Parameters

connectionStringBuilder ServiceBusConnectionStringBuilder

ServiceBusConnectionStringBuilder having namespace and queue information.

receiveMode ReceiveMode

Mode of receive of messages. Defaults to ReceiveMode.PeekLock.

retryPolicy RetryPolicy

Retry policy for queue operations. Defaults to Default

Remarks

Creates a new connection to the queue, which is opened during the first send/receive operation.

QueueClient(string, string, ITokenProvider, TransportType, ReceiveMode, RetryPolicy)

Creates a new instance of the Queue client using the specified endpoint, entity path, and token provider.

public QueueClient(string endpoint, string entityPath, ITokenProvider tokenProvider, TransportType transportType = TransportType.Amqp, ReceiveMode receiveMode = ReceiveMode.PeekLock, RetryPolicy retryPolicy = null)

Parameters

endpoint string

Fully qualified domain name for Service Bus. Most likely, {yournamespace}.servicebus.windows.net

entityPath string

Queue path.

tokenProvider ITokenProvider

Token provider which will generate security tokens for authorization.

transportType TransportType

Transport type.

receiveMode ReceiveMode

Mode of receive of messages. Defaults to ReceiveMode.PeekLock.

retryPolicy RetryPolicy

Retry policy for queue operations. Defaults to Default

Remarks

Creates a new connection to the queue, which is opened during the first send/receive operation.

QueueClient(string, string, ReceiveMode, RetryPolicy)

Instantiates a new QueueClient to perform operations on a queue.

public QueueClient(string connectionString, string entityPath, ReceiveMode receiveMode = ReceiveMode.PeekLock, RetryPolicy retryPolicy = null)

Parameters

connectionString string

Namespace connection string. Must not contain queue information.

entityPath string

Name of the queue

receiveMode ReceiveMode

Mode of receive of messages. Defaults to ReceiveMode.PeekLock.

retryPolicy RetryPolicy

Retry policy for queue operations. Defaults to Default

Remarks

Creates a new connection to the queue, which is opened during the first send/receive operation.

Properties

OperationTimeout

Duration after which individual operations will timeout.

public override TimeSpan OperationTimeout { get; set; }

Property Value

TimeSpan

Path

Gets the name of the queue.

public override string Path { get; }

Property Value

string

PrefetchCount

Prefetch speeds up the message flow by aiming to have a message readily available for local retrieval when and before the application asks for one using Receive. Setting a non-zero value prefetches PrefetchCount number of messages. Setting the value to zero turns prefetch off. Defaults to 0.

public int PrefetchCount { get; set; }

Property Value

int

Remarks

When Prefetch is enabled, the client will quietly acquire more messages, up to the PrefetchCount limit, than what the application immediately asks for. The message pump will therefore acquire a message for immediate consumption that will be returned as soon as available, and the client will proceed to acquire further messages to fill the prefetch buffer in the background.

While messages are available in the prefetch buffer, any subsequent ReceiveAsync calls will be immediately satisfied from the buffer, and the buffer is replenished in the background as space becomes available.If there are no messages available for delivery, the receive operation will drain the buffer and then wait or block as expected.

Updates to this value take effect on the next receive call to the service.

QueueName

Gets the name of the queue.

public string QueueName { get; }

Property Value

string

ReceiveMode

Gets the ReceiveMode for the QueueClient.

public ReceiveMode ReceiveMode { get; }

Property Value

ReceiveMode

RegisteredPlugins

Gets a list of currently registered plugins for this QueueClient.

public override IList<ServiceBusPlugin> RegisteredPlugins { get; }

Property Value

IList<ServiceBusPlugin>

ServiceBusConnection

Connection object to the service bus namespace.

public override ServiceBusConnection ServiceBusConnection { get; }

Property Value

ServiceBusConnection

Methods

AbandonAsync(string, IDictionary<string, object>)

Abandons a Message using a lock token. This will make the message available again for processing.

public Task AbandonAsync(string lockToken, IDictionary<string, object> propertiesToModify = null)

Parameters

lockToken string

The lock token of the corresponding message to abandon.

propertiesToModify IDictionary<string, object>

The properties of the message to modify while abandoning the message.

Returns

Task

Remarks

A lock token can be found in LockToken, only when ReceiveMode is set to PeekLock. Abandoning a message will increase the delivery count on the message. This operation can only be performed on messages that were received by this client.

CancelScheduledMessageAsync(long)

Cancels a message that was scheduled.

public Task CancelScheduledMessageAsync(long sequenceNumber)

Parameters

sequenceNumber long

The SequenceNumber of the message to be cancelled.

Returns

Task

CompleteAsync(string)

Completes a Message using its lock token. This will delete the message from the queue.

public Task CompleteAsync(string lockToken)

Parameters

lockToken string

The lock token of the corresponding message to complete.

Returns

Task

Remarks

A lock token can be found in LockToken, only when ReceiveMode is set to PeekLock. This operation can only be performed on messages that were received by this client.

DeadLetterAsync(string, IDictionary<string, object>)

Moves a message to the deadletter sub-queue.

public Task DeadLetterAsync(string lockToken, IDictionary<string, object> propertiesToModify = null)

Parameters

lockToken string

The lock token of the corresponding message to deadletter.

propertiesToModify IDictionary<string, object>

The properties of the message to modify while moving to sub-queue.

Returns

Task

Remarks

A lock token can be found in LockToken, only when ReceiveMode is set to PeekLock. In order to receive a message from the deadletter queue, you will need a new IMessageReceiver, with the corresponding path. You can use FormatDeadLetterPath(string) to help with this. This operation can only be performed on messages that were received by this receiver.

DeadLetterAsync(string, string, string)

Moves a message to the deadletter sub-queue.

public Task DeadLetterAsync(string lockToken, string deadLetterReason, string deadLetterErrorDescription = null)

Parameters

lockToken string

The lock token of the corresponding message to deadletter.

deadLetterReason string

The reason for deadlettering the message.

deadLetterErrorDescription string

The error description for deadlettering the message.

Returns

Task

Remarks

A lock token can be found in LockToken, only when ReceiveMode is set to PeekLock. In order to receive a message from the deadletter queue, you will need a new IMessageReceiver, with the corresponding path. You can use FormatDeadLetterPath(string) to help with this. This operation can only be performed on messages that were received by this receiver.

OnClosingAsync() 

protected override Task OnClosingAsync()

Returns

Task

RegisterMessageHandler(Func<Message, CancellationToken, Task>, MessageHandlerOptions)

Receive messages continuously from the entity. Registers a message handler and begins a new thread to receive messages. This handler(Func<T1, T2, TResult>) is awaited on every time a new message is received by the receiver.

public void RegisterMessageHandler(Func<Message, CancellationToken, Task> handler, MessageHandlerOptions messageHandlerOptions)

Parameters

handler Func<Message, CancellationToken, Task>

A Func<T1, T2, TResult> that processes messages.

messageHandlerOptions MessageHandlerOptions

The MessageHandlerOptions options used to configure the settings of the pump.

Remarks

Enable prefetch to speed up the receive rate.

RegisterMessageHandler(Func<Message, CancellationToken, Task>, Func<ExceptionReceivedEventArgs, Task>)

Receive messages continuously from the entity. Registers a message handler and begins a new thread to receive messages. This handler(Func<T1, T2, TResult>) is awaited on every time a new message is received by the receiver.

public void RegisterMessageHandler(Func<Message, CancellationToken, Task> handler, Func<ExceptionReceivedEventArgs, Task> exceptionReceivedHandler)

Parameters

handler Func<Message, CancellationToken, Task>

A Func<T1, T2, TResult> that processes messages.

exceptionReceivedHandler Func<ExceptionReceivedEventArgs, Task>

A Func<T, TResult> that is invoked during exceptions. ExceptionReceivedEventArgs contains contextual information regarding the exception.

Remarks

Enable prefetch to speed up the receive rate. Use RegisterMessageHandler(Func<Message, CancellationToken, Task>, MessageHandlerOptions) to configure the settings of the pump.

RegisterPlugin(ServiceBusPlugin)

Registers a ServiceBusPlugin to be used with this queue client.

public override void RegisterPlugin(ServiceBusPlugin serviceBusPlugin)

Parameters

serviceBusPlugin ServiceBusPlugin

RegisterSessionHandler(Func<IMessageSession, Message, CancellationToken, Task>, SessionHandlerOptions)

Receive session messages continuously from the queue. Registers a message handler and begins a new thread to receive session-messages. This handler(Func<T1, T2, T3, TResult>) is awaited on every time a new message is received by the queue client.

public void RegisterSessionHandler(Func<IMessageSession, Message, CancellationToken, Task> handler, SessionHandlerOptions sessionHandlerOptions)

Parameters

handler Func<IMessageSession, Message, CancellationToken, Task>

A Func<T1, T2, T3, TResult> that processes messages. IMessageSession contains the session information, and must be used to perform Complete/Abandon/Deadletter or other such operations on the Message

sessionHandlerOptions SessionHandlerOptions

Options used to configure the settings of the session pump.

Remarks

Enable prefetch to speed up the receive rate.

RegisterSessionHandler(Func<IMessageSession, Message, CancellationToken, Task>, Func<ExceptionReceivedEventArgs, Task>)

Receive session messages continuously from the queue. Registers a message handler and begins a new thread to receive session-messages. This handler(Func<T1, T2, T3, TResult>) is awaited on every time a new message is received by the queue client.

public void RegisterSessionHandler(Func<IMessageSession, Message, CancellationToken, Task> handler, Func<ExceptionReceivedEventArgs, Task> exceptionReceivedHandler)

Parameters

handler Func<IMessageSession, Message, CancellationToken, Task>

A Func<T1, T2, T3, TResult> that processes messages. IMessageSession contains the session information, and must be used to perform Complete/Abandon/Deadletter or other such operations on the Message

exceptionReceivedHandler Func<ExceptionReceivedEventArgs, Task>

A Func<T, TResult> that is invoked during exceptions. ExceptionReceivedEventArgs contains contextual information regarding the exception.

Remarks

Enable prefetch to speed up the receive rate. Use RegisterSessionHandler(Func<IMessageSession, Message, CancellationToken, Task>, SessionHandlerOptions) to configure the settings of the pump.

ScheduleMessageAsync(Message, DateTimeOffset)

Schedules a message to appear on Service Bus at a later time.

public Task<long> ScheduleMessageAsync(Message message, DateTimeOffset scheduleEnqueueTimeUtc)

Parameters

message Message
scheduleEnqueueTimeUtc DateTimeOffset

The UTC time at which the message should be available for processing

Returns

Task<long>

The sequence number of the message that was scheduled.

SendAsync(Message)

Sends a message to Service Bus.

public Task SendAsync(Message message)

Parameters

message Message

Returns

Task

SendAsync(IList<Message>)

Sends a list of messages to Service Bus.

public Task SendAsync(IList<Message> messageList)

Parameters

messageList IList<Message>

Returns

Task

UnregisterPlugin(string)

Unregisters a ServiceBusPlugin.

public override void UnregisterPlugin(string serviceBusPluginName)

Parameters

serviceBusPluginName string

The name Name to be unregistered