Class QueueClient

Namespace: Microsoft.ServiceBus.Messaging

Assembly: Microsoft.ServiceBus.dll

Represents the queue client object.

public abstract class QueueClient : ClientEntity

Inheritance: object

ClientEntity

QueueClient

Inherited Members: ClientEntity.Abort()

ClientEntity.Close()

ClientEntity.CloseAsync()

ClientEntity.Fault()

ClientEntity.OnOpen(TimeSpan)

ClientEntity.ThrowIfClosed()

ClientEntity.ThrowIfDisposed()

ClientEntity.ThrowIfDisposedOrNotOpen()

ClientEntity.ThrowIfFaulted()

ClientEntity.ThrowIfDisposedOrImmutable()

ClientEntity.OnOpened()

ClientEntity.OnClosed()

ClientEntity.OnFaulted()

ClientEntity.OnBeginOpen(TimeSpan, AsyncCallback, object)

ClientEntity.OnEndOpen(IAsyncResult)

ClientEntity.RetryPolicy

ClientEntity.IsClosed

ClientEntity.ThisLock

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Properties

MessagingFactory

Gets or sets the messaging factory.

public MessagingFactory MessagingFactory { get; }

Property Value

MessagingFactory: The messaging factory.

Mode

Gets the message receive mode when processing the received message.

public ReceiveMode Mode { get; }

Property Value

ReceiveMode: The message ReceiveMode when processing the received message.

Path

Gets or sets the full path name of the queue.

public string Path { get; }

Property Value

string: The queue path relative to the MessagingFactory base address.

PrefetchCount

Gets or sets the number of messages that the queue receiver can simultaneously request.

public int PrefetchCount { get; set; }

Property Value

int: The number of messages that the queue receiver can simultaneously request.

Remarks

Takes effect on the next receive call to the server.

Methods

Abandon(Guid)

Discards the message and relinquishes the message lock ownership.

public void Abandon(Guid lockToken)

Parameters

lockToken Guid: The lock token bound to the locked message instance to abandon.

Remarks

When the client fails to get the message from the queue/topic, this method should be called. The Service Bus will increment the delivery count of the message. The client now can either attempt to receive the message again or move it to the dead-letter queue.

Exceptions

TimeoutException: Thrown if the operation exceeded the timeout value set by OperationTimeout.
OperationCanceledException: Thrown if the client entity has been closed or aborted.

Abandon(Guid, IDictionary<string, object>)

Discards the message and relinquishes the message lock ownership.

public void Abandon(Guid lockToken, IDictionary<string, object> propertiesToModify)

Parameters

lockToken Guid: The lock token bound to the locked message instance to abandon.
propertiesToModify IDictionary<string, object>: The properties of the message to modify.

Remarks

AbandonAsync(Guid)

Asynchronously discards the message and relinquishes the message lock ownership.

public Task AbandonAsync(Guid lockToken)

Parameters

lockToken Guid: The lock token bound to the locked message instance to abandon.

Returns

Task: The discarded message.

AbandonAsync(Guid, IDictionary<string, object>)

Asynchronously discards the message and relinquishes the message lock ownership.

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

Parameters

lockToken Guid: The lock token bound to the locked message instance to abandon.
propertiesToModify IDictionary<string, object>: The properties of the message to modify.

Returns

Task: The discarded message.

AcceptMessageSession()

Accepts a message session that allows grouping of related messages for processing in a single transaction.

public MessageSession AcceptMessageSession()

Returns

MessageSession: A MessageSession that allows grouping of related messages for processing in a single transaction.

Exceptions

TimeoutException: Thrown if the operation exceeded the timeout value set by OperationTimeout.
OperationCanceledException: Thrown if the client is already closed, aborted, or disposed.

AcceptMessageSession(bool)

Accepts a message session that allows grouping of related messages for processing in a single transaction ith whether in exclusive mode.

public MessageSession AcceptMessageSession(bool isExclusiveMode)

Parameters

isExclusiveMode bool: Ture if exclusive mode, or false is not.

Returns

MessageSession

AcceptMessageSession(bool, TimeSpan)

Accepts a message session that allows grouping of related messages for processing in a single transaction ith whether in exclusive mode.

public MessageSession AcceptMessageSession(bool isExclusiveMode, TimeSpan serverWaitTime)

Parameters

isExclusiveMode bool: Ture if exclusive mode, or false is not.
serverWaitTime TimeSpan: The server wait timeout

Returns

MessageSession

AcceptMessageSession(string)

Accepts a message session that allows grouping of related messages for processing in a single transaction using the given session identifier.

public MessageSession AcceptMessageSession(string sessionId)

Parameters

sessionId string: The session identifier of the message session.

Returns

MessageSession: A MessageSession that allows grouping of related messages for processing in a single transaction.

Exceptions

ArgumentException: Thrown if sessionId is null, empty, or white spaces.
TimeoutException: Thrown if the operation exceeded the timeout value set by OperationTimeout.
OperationCanceledException: Thrown if the client is already closed, aborted, or disposed.

AcceptMessageSession(string, bool)

Accepts a message session that allows grouping of related messages for processing in a single transaction with whether in exclusive mode.

public MessageSession AcceptMessageSession(string sessionId, bool isExclusiveMode)

Parameters

sessionId string: The session identifier of the message session.
isExclusiveMode bool: Ture if exclusive mode, or false is not.

Returns

MessageSession: A MessageSession that allows grouping of related messages for processing in a single transaction.

AcceptMessageSession(string, bool, TimeSpan)

Accepts a message session that allows grouping of related messages for processing in a single transaction using the given session identifier with whether in exclusive mode.

public MessageSession AcceptMessageSession(string sessionId, bool isExclusiveMode, TimeSpan serverWaitTime)

Parameters

sessionId string: The session identifier of the message session.
isExclusiveMode bool: Ture if exclusive mode, or false is not.
serverWaitTime TimeSpan: The server wait timeout

Returns

MessageSession: A MessageSession that allows grouping of related messages for processing in a single transaction.

AcceptMessageSession(string, Guid)

Accepts a message non-exclusive locked session that allows grouping of related messages for processing in a single transaction using the given session identifier and session lock token.

public MessageSession AcceptMessageSession(string sessionId, Guid lockToken)

Parameters

sessionId string: The session identifier of the message session.
lockToken Guid: The session lock token.

Returns

MessageSession: A MessageSession that allows grouping of related messages for processing in a single transaction.

AcceptMessageSession(string, Guid, TimeSpan)

Accepts a message non-exclusive locked session that allows grouping of related messages for processing in a single transaction using the given session identifier and session lock token.

public MessageSession AcceptMessageSession(string sessionId, Guid lockToken, TimeSpan serverWaitTime)

Parameters

sessionId string: The session identifier of the message session.
lockToken Guid: The session locktoken
serverWaitTime TimeSpan: The server wait timeout

Returns

MessageSession

AcceptMessageSession(string, TimeSpan)

Accepts a message session that allows grouping of related messages for processing in a single transaction using the given session identifier and wait time.

public MessageSession AcceptMessageSession(string sessionId, TimeSpan serverWaitTime)

Parameters

sessionId string: The session identifier of the message session.
serverWaitTime TimeSpan: The time span the server waits for processing messages before it times out.

Returns

MessageSession: A MessageSession that allows grouping of related messages for processing in a single transaction.

Exceptions

ArgumentException: Thrown if sessionId is null, empty, or white spaces.
ArgumentOutOfRangeException: Thrown if serverWaitTime is not a positive TimeSpan value.
TimeoutException: Thrown if the operation exceeded the timeout value set by OperationTimeout.
OperationCanceledException: Thrown if the client is already closed, aborted, or disposed.

AcceptMessageSession(TimeSpan)

Accepts a message session that allows grouping of related messages for processing in a single transaction using the specified server wait time.

public MessageSession AcceptMessageSession(TimeSpan serverWaitTime)

Parameters

serverWaitTime TimeSpan: The time span the server waits for processing messages before it times out.

Returns

MessageSession: A MessageSession that allows grouping of related messages for processing in a single transaction.

Exceptions

ArgumentOutOfRangeException: Thrown if serverWaitTime is not a positive TimeSpan value.
TimeoutException: Thrown if the operation exceeded the timeout value set by serverWaitTime.
OperationCanceledException: Thrown if the client is already closed, aborted, or disposed.

AcceptMessageSessionAsync()

Asynchronously accepts a message session that allows grouping of related messages for processing in a single transaction.

public Task<MessageSession> AcceptMessageSessionAsync()

Returns

Task<MessageSession>: The result of an asynchronous operation.

AcceptMessageSessionAsync(bool)

Asynchronously accepts a message session that allows grouping of related messages for processing in a single transaction with whether in exclusive mode and wait time.

public Task<MessageSession> AcceptMessageSessionAsync(bool isExclusiveMode)

Parameters

isExclusiveMode bool: Ture if exclusive mode, or false is not.

Returns

Task<MessageSession>: The result of an asynchronous operation.

AcceptMessageSessionAsync(bool, TimeSpan)

Asynchronously accepts a message session that allows grouping of related messages for processing in a single transaction with whether in exclusive mode and wait time.

public Task<MessageSession> AcceptMessageSessionAsync(bool isExclusiveMode, TimeSpan serverWaitTime)

Parameters

isExclusiveMode bool: Ture if exclusive mode, or false is not.
serverWaitTime TimeSpan: The time span the server waits for processing messages before it times out.

Returns

Task<MessageSession>: The result of an asynchronous operation.

AcceptMessageSessionAsync(string)

Asynchronously accepts a message session that allows grouping of related messages for processing in a single transaction using the given session identifier.

public Task<MessageSession> AcceptMessageSessionAsync(string sessionId)

Parameters

sessionId string: The session identifier of the message session.

Returns

Task<MessageSession>: The result of an asynchronous operation.

AcceptMessageSessionAsync(string, bool)

Accepts a message session that allows grouping of related messages for processing in a single transaction using the given session identifier with whether in exclusive mode.

public Task<MessageSession> AcceptMessageSessionAsync(string sessionId, bool isExclusiveMode)

Parameters

sessionId string: The session identifier of the message session.
isExclusiveMode bool: Ture if exclusive mode, or false is not.

Returns

Task<MessageSession>: The result of an asynchronous operation.

AcceptMessageSessionAsync(string, bool, TimeSpan)

Accepts a message session that allows grouping of related messages for processing in a single transaction using the given session identifier with whether in exclusive mode.

public Task<MessageSession> AcceptMessageSessionAsync(string sessionId, bool isExclusiveMode, TimeSpan serverWaitTime)

Parameters

sessionId string: The session identifier of the message session.
isExclusiveMode bool: Ture if exclusive mode, or false is not.
serverWaitTime TimeSpan: The server wait timeout

Returns

Task<MessageSession>

AcceptMessageSessionAsync(string, Guid)

Accepts a message non-exclusive locked session that allows grouping of related messages for processing in a single transaction using the given session identifier and session lock token.

public Task<MessageSession> AcceptMessageSessionAsync(string sessionId, Guid lockToken)

Parameters

sessionId string: The session identifier of the message session.
lockToken Guid: The session lock token.

Returns

Task<MessageSession>: The result of an asynchronous operation.

AcceptMessageSessionAsync(string, Guid, TimeSpan)

Accepts a message non-exclusive locked session that allows grouping of related messages for processing in a single transaction using the given session identifier and session lock token.

public Task<MessageSession> AcceptMessageSessionAsync(string sessionId, Guid lockToken, TimeSpan serverWaitTime)

Parameters

sessionId string: The session identifier of the message session.
lockToken Guid: The session locktoken
serverWaitTime TimeSpan: The server wait timeout

Returns

Task<MessageSession>

AcceptMessageSessionAsync(string, TimeSpan)

Asynchronously accepts a message session that allows grouping of related messages for processing in a single transaction using the given session identifier and wait time.

public Task<MessageSession> AcceptMessageSessionAsync(string sessionId, TimeSpan serverWaitTime)

Parameters

sessionId string: The session identifier of the message session.
serverWaitTime TimeSpan: The time span the server waits for processing messages before it times out.

Returns

Task<MessageSession>: The result of an asynchronous operation.

AcceptMessageSessionAsync(TimeSpan)

Asynchronously accepts a message session that allows grouping of related messages for processing in a single transaction using the specified server wait time.

public Task<MessageSession> AcceptMessageSessionAsync(TimeSpan serverWaitTime)

Parameters

serverWaitTime TimeSpan: The time span the server waits for processing messages before it times out.

Returns

Task<MessageSession>: The result of an asynchronous operation.

CancelScheduledMessageAsync(long)

Cancels a scheduled message

public Task CancelScheduledMessageAsync(long sequenceNumber)

Parameters

sequenceNumber long: Returned on scheduling a message.

Returns

Task

Complete(Guid)

Completes processing of a message.

public void Complete(Guid lockToken)

Parameters

lockToken Guid: The lock token bound to the locked message instance.

Remarks

This method is used as a handshake between the client and Service Bus for a guaranteed delivery of the message. If the client failed before calling this method, the message will be kept in the queue.

Exceptions

TimeoutException: Thrown if the operation exceeded the timeout value set by OperationTimeout
OperationCanceledException: Thrown if the client entity has been closed or aborted.
MessageLockLostException: Thrown if the message represented by the lockToken has lost the message lock.

CompleteAsync(Guid)

Asynchronously completes processing of a message.

public Task CompleteAsync(Guid lockToken)

Parameters

lockToken Guid: The lock token bound to the locked message instance.

Returns

Task: The asynchronous operation.

CompleteBatch(IEnumerable<Guid>)

Completes processing of a message batch.

public void CompleteBatch(IEnumerable<Guid> lockTokens)

Parameters

lockTokens IEnumerable<Guid>: The lock tokens associated with locked messages in the batch.

Remarks

This method is used as a handshake between the client and Service Bus for a guaranteed delivery of the message. If the client failed before calling this method, the message will be kept in the queue.

CompleteBatchAsync(IEnumerable<Guid>)

Asynchronously completes processing of a message batch.

public Task CompleteBatchAsync(IEnumerable<Guid> lockTokens)

Parameters

lockTokens IEnumerable<Guid>: The lock tokens associated with locked messages in the batch.

Returns

Task: The asynchronous operation.

Create(string)

Creates a new copy of QueueClient with specified path.

public static QueueClient Create(string path)

Parameters

path string: The path.

Returns

QueueClient: The created QueueClient.

Remarks

This method will attempt to retrieve the connection string information from either app.config, or web.config files. User must supply the connection string using the "AppSettings" section of the configuration. The format of the section is as follows:

        <pre><code class="lang-csharp"></code></pre>

Create(string, ReceiveMode)

Creates a new copy of QueueClient with specified path and mode.

public static QueueClient Create(string path, ReceiveMode mode)

Parameters

path string: The path.
mode ReceiveMode: The mode.

Returns

QueueClient: The created QueueClient.

Remarks

        <pre><code class="lang-csharp"></code></pre>

CreateFromConnectionString(string)

Creates a new instance of QueueClient using the specified connection string.

public static QueueClient CreateFromConnectionString(string connectionString)

Parameters

connectionString string: The connection string to use.

Returns

QueueClient: The newly created QueueClient instance.

Remarks

This method expects the connection string supplied has entity level information such as the entity path and authentication information supplied.

Exceptions

ArgumentException: Thrown when the format of the connectionString parameter is incorrect.

CreateFromConnectionString(string, ReceiveMode)

Creates a new instance of QueueClient using the specified connection string and receiving mode.

public static QueueClient CreateFromConnectionString(string connectionString, ReceiveMode mode)

Parameters

connectionString string: The connection string to use.
mode ReceiveMode: The ReceiveMode.

Returns

QueueClient: The newly created QueueClient instance.

Remarks

This method expects the connection string supplied has entity level information such as the entity path and authentication information supplied.

Exceptions

ArgumentException: Thrown when the format of the connectionString parameter is incorrect.

CreateFromConnectionString(string, string)

Creates a new copy of QueueClient from a connection string with the specified queue path. Use this overload only when the connection string does not use the EntityPath property.

public static QueueClient CreateFromConnectionString(string connectionString, string path)

Parameters

connectionString string: The connection string used.
path string: The path to the queue.

Returns

QueueClient: The created QueueClient.

Remarks

This method should only be used with a connection string that has namespace level authentication because the connection string supplied should not have entity level information associated with it.

Exceptions

ArgumentException: Thrown when the format of the connectionString parameter is incorrect.

CreateFromConnectionString(string, string, ReceiveMode)

Creates a new instance of QueueClient from a connection string with the specified path and mode. Use this overload only when the connection string does not use the EntityPath property.

public static QueueClient CreateFromConnectionString(string connectionString, string path, ReceiveMode mode)

Parameters

connectionString string: The connection string.
path string: The path to the queue.
mode ReceiveMode: The ReceiveMode.

Returns

QueueClient: The created QueueClient.

Remarks

This method should only be used with a connection string that has namespace level authentication because the connection string supplied should not have entity level information associated with it.

Exceptions

ArgumentException: Thrown when the format of the connectionString parameter is incorrect.

DeadLetter(Guid)

Moves the undelivered message to the dead letter queue.

public void DeadLetter(Guid lockToken)

Parameters

lockToken Guid: The lock token bound to the locked message instance.

Exceptions

TimeoutException: Thrown if the operation exceeded the timeout value set by OperationTimeout
OperationCanceledException: Thrown if the client entity has been closed or aborted.
MessageLockLostException: Thrown if the message represented by the lockToken has lost the message lock.

DeadLetter(Guid, IDictionary<string, object>)

Moves the undelivered message to the dead letter queue.

public void DeadLetter(Guid lockToken, IDictionary<string, object> propertiesToModify)

Parameters

lockToken Guid: The lock token bound to the locked message instance.
propertiesToModify IDictionary<string, object>: The properties of the message to modify.

DeadLetter(Guid, string, string)

Moves the undelivered message to the dead letter queue.

public void DeadLetter(Guid lockToken, string deadLetterReason, string deadLetterErrorDescription)

Parameters

lockToken Guid: The lock token bound to the locked message instance.
deadLetterReason string: The reason for deadlettering the message.
deadLetterErrorDescription string: The error description for deadlettering the message.

Exceptions

TimeoutException: Thrown if the operation exceeded the timeout value set by OperationTimeout
OperationCanceledException: Thrown if the client entity has been closed or aborted.
MessageLockLostException: Thrown if the message represented by the lockToken has lost the message lock.

DeadLetterAsync(Guid)

Asynchronously moves the undelivered message to the dead letter queue.

public Task DeadLetterAsync(Guid lockToken)

Parameters

lockToken Guid: The lock token bound to the locked message instance.

Returns

Task: The asynchronous operation.

DeadLetterAsync(Guid, IDictionary<string, object>)

Asynchronously moves the undelivered message to the dead letter queue.

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

Parameters

lockToken Guid: The lock token bound to the locked message instance.
propertiesToModify IDictionary<string, object>: The properties of the message to modify.

Returns

Task: The asynchronous operation.

DeadLetterAsync(Guid, string, string)

Asynchronously moves the undelivered message to the dead letter queue.

public Task DeadLetterAsync(Guid lockToken, string deadLetterReason, string deadLetterErrorDescription)

Parameters

lockToken Guid: The lock token bound to the locked message instance.
deadLetterReason string: The reason for deadlettering the message.
deadLetterErrorDescription string: The error description for deadlettering the message.

Returns

Task: The asynchronous operation.

Defer(Guid)

Suspends the processing of a message.

public void Defer(Guid lockToken)

Parameters

lockToken Guid: The lock token bound to the locked message instance.

Remarks

Before deferring, you should set aside the message receipt for later retrieval.

Exceptions

TimeoutException: Thrown if the operation exceeded the timeout value set by OperationTimeout
OperationCanceledException: Thrown if the client entity has been closed or aborted.
MessageLockLostException: Thrown if the message represented by the lockToken has lost the message lock.

Defer(Guid, IDictionary<string, object>)

Suspends the processing of a message.

public void Defer(Guid lockToken, IDictionary<string, object> propertiesToModify)

Parameters

lockToken Guid: The lock token bound to the locked message instance.
propertiesToModify IDictionary<string, object>: The properties of the message to modify.

Remarks

Before deferring, you should set aside the message receipt for later retrieval.

DeferAsync(Guid)

Asynchronously suspends the processing of a message.

public Task DeferAsync(Guid lockToken)

Parameters

lockToken Guid: The lock token bound to the locked message instance.

Returns

Task: The asynchronous operation.

DeferAsync(Guid, IDictionary<string, object>)

Asynchronously suspends the processing of a message.

public Task DeferAsync(Guid lockToken, IDictionary<string, object> propertiesToModify)

Parameters

lockToken Guid: The lock token bound to the locked message instance.
propertiesToModify IDictionary<string, object>: The properties of the message to modify.

Returns

Task: The asynchronous operation.

FormatDeadLetterPath(string)

Builds a format name from the specified dead letter queue path.

public static string FormatDeadLetterPath(string queuePath)

Parameters

queuePath string: The path to the dead letter queue.

Returns

string: The string resulted from building the format name for the specified dead letter queue path.

FormatTransferDeadLetterPath(string)

public static string FormatTransferDeadLetterPath(string queuePath)

Parameters

queuePath string

Returns

string

GetMessageSessions()

Gets the message sessions, enabling you to browse sessions on queues.

public IEnumerable<MessageSession> GetMessageSessions()

Returns

IEnumerable<MessageSession>: The message session.

GetMessageSessions(DateTime)

Retrieves all message sessions whose session state was updated since lastUpdatedTime.

public IEnumerable<MessageSession> GetMessageSessions(DateTime lastUpdatedTime)

Parameters

lastUpdatedTime DateTime: The time the session was last updated.

Returns

IEnumerable<MessageSession>: The message sessions.

GetMessageSessionsAsync()

Asynchronously gets the message sessions, enabling you to browse sessions on queues.

public Task<IEnumerable<MessageSession>> GetMessageSessionsAsync()

Returns

Task<IEnumerable<MessageSession>>: The asynchronous operation.

GetMessageSessionsAsync(DateTime)

Asynchronously retrieves all message sessions whose session state was updated since lastUpdatedTime.

public Task<IEnumerable<MessageSession>> GetMessageSessionsAsync(DateTime lastUpdatedTime)

Parameters

lastUpdatedTime DateTime: The time the session was last updated.

Returns

Task<IEnumerable<MessageSession>>: The asynchronous operation.

OnAbort()

Executes upon calling the Abort event.

protected override void OnAbort()

OnBeginAcceptMessageSession(string, ReceiveMode, int, bool, Guid?, TimeSpan, TimeSpan, AsyncCallback, object)

protected abstract IAsyncResult OnBeginAcceptMessageSession(string sessionId, ReceiveMode receiveMode, int prefetchCount, bool isExclusiveMode, Guid? lockToken, TimeSpan serverWaitTime, TimeSpan timeout, AsyncCallback callback, object state)

Parameters

sessionId string
receiveMode ReceiveMode
prefetchCount int
isExclusiveMode bool
lockToken Guid?
serverWaitTime TimeSpan
timeout TimeSpan
callback AsyncCallback
state object

Returns

IAsyncResult

OnBeginClose(TimeSpan, AsyncCallback, object)

Executes when the Close operation is called.

protected override IAsyncResult OnBeginClose(TimeSpan timeout, AsyncCallback callback, object state)

Parameters

timeout TimeSpan: The maximum time before the close operation times out.
callback AsyncCallback: An AsyncCallback delegate that references the method to invoke when the operation is complete.
state object: A user-defined object that contains information about the receive operation. This object is passed to the EndClose delegate when the operation is complete.

Returns

IAsyncResult: An IAsyncResult object that references the asynchronous parent method.

OnBeginCreateReceiver(ReceiveMode, TimeSpan, AsyncCallback, object)

Executes the begin create receiver action.

protected abstract IAsyncResult OnBeginCreateReceiver(ReceiveMode receiveMode, TimeSpan timeout, AsyncCallback callback, object state)

Parameters

receiveMode ReceiveMode: The message ReceiveMode receive mode.
timeout TimeSpan: The maximum time before this operation times out.
callback AsyncCallback: An AsyncCallback delegate that references the method to invoke when the operation is complete.
state object: A user-defined object that contains information about the receive operation. This object is passed to the Microsoft.ServiceBus.Messaging.QueueClient.EndCreateReceiver(System.IAsyncResult) delegate when the operation is complete.

Returns

IAsyncResult: An IAsyncResult object that references the asynchronous parent method.

OnBeginCreateReceiver(string, ReceiveMode, TimeSpan, AsyncCallback, object)

Executes the begin create receiver action.

protected abstract IAsyncResult OnBeginCreateReceiver(string subQueueName, ReceiveMode receiveMode, TimeSpan timeout, AsyncCallback callback, object state)

Parameters

subQueueName string: Name of the sub-queue.
receiveMode ReceiveMode: The message ReceiveMode receive mode.
timeout TimeSpan: The maximum time before this operation times out.
callback AsyncCallback: An AsyncCallback delegate that references the method to invoke when the operation is complete.
state object: A user-defined object that contains information about the receive operation. This object is passed to the Microsoft.ServiceBus.Messaging.QueueClient.EndCreateReceiver(System.IAsyncResult) delegate when the operation is complete.

Returns

IAsyncResult: An IAsyncResult object that references the asynchronous parent method.

OnBeginCreateSender(TimeSpan, AsyncCallback, object)

Executes the begin create sender action.

protected abstract IAsyncResult OnBeginCreateSender(TimeSpan timeout, AsyncCallback callback, object state)

Parameters

timeout TimeSpan: The maximum time before this operation times out.
callback AsyncCallback: An AsyncCallback delegate that references the method to invoke when the operation is complete.
state object: A user-defined object that contains information about the receive operation. This object is passed to the Microsoft.ServiceBus.Messaging.QueueClient.EndCreateSender(System.IAsyncResult) delegate when the operation is complete.

Returns

IAsyncResult: An IAsyncResult object that references the asynchronous parent method

OnBeginGetMessageSessions(DateTime, AsyncCallback, object)

Executes the BeginGetMessageSessions action.

protected abstract IAsyncResult OnBeginGetMessageSessions(DateTime lastUpdatedTime, AsyncCallback callback, object state)

Parameters

lastUpdatedTime DateTime: The date and time of the last update.
callback AsyncCallback: An AsyncCallback delegate that references the method to invoke when the operation is complete.
state object: A user-defined object that contains state information about the asynchronous operation.

Returns

IAsyncResult: An IAsyncResult that references the asynchronous operation to get the message sessions.

OnClose(TimeSpan)

Executes upon calling the Close action.

protected override void OnClose(TimeSpan timeout)

Parameters

timeout TimeSpan: The maximum time before the close operation times out.

OnEndAcceptMessageSession(IAsyncResult)

Executes upon calling the EndAcceptMessageSession operation.

protected abstract MessageSession OnEndAcceptMessageSession(IAsyncResult result)

Parameters

result IAsyncResult: An IAsyncResult that represents the status of the asynchronous accept message session operation.

Returns

MessageSession: The MessageSession that allows grouping of related messages for processing in a single transaction.

OnEndClose(IAsyncResult)

Executes the end close action.

protected override void OnEndClose(IAsyncResult result)

Parameters

result IAsyncResult: The result of the asynchronous parent method.

OnEndCreateReceiver(IAsyncResult)

Executes the end create receiver action.

protected abstract MessageReceiver OnEndCreateReceiver(IAsyncResult result)

Parameters

result IAsyncResult: The result of the asynchronous Microsoft.ServiceBus.Messaging.QueueClient.EndCreateReceiver(System.IAsyncResult) operation.

Returns

MessageReceiver: A MessageReceiver object.

OnEndCreateSender(IAsyncResult)

Executes the end create sender action.

protected abstract MessageSender OnEndCreateSender(IAsyncResult result)

Parameters

result IAsyncResult: An IAsyncResult object that references the asynchronous parent method.

Returns

MessageSender: A MessageSender object.

OnEndGetMessageSessions(IAsyncResult)

Executes the end get message action.

protected abstract IEnumerable<MessageSession> OnEndGetMessageSessions(IAsyncResult result)

Parameters

result IAsyncResult: The result of the session.

Returns

IEnumerable<MessageSession>: The MessageSession that allows grouping of related messages for processing in a single transaction.

OnMessage(Action<BrokeredMessage>)

Processes a message in an event-driven message pump.

public void OnMessage(Action<BrokeredMessage> callback)

Parameters

callback Action<BrokeredMessage>: The method to invoke when the operation is complete.

OnMessage(Action<BrokeredMessage>, OnMessageOptions)

Processes a message in an event-driven message pump, with the given set of OnMessageOptions options.

public void OnMessage(Action<BrokeredMessage> callback, OnMessageOptions onMessageOptions)

Parameters

callback Action<BrokeredMessage>: The method to invoke when the operation is complete.
onMessageOptions OnMessageOptions: Specifies the OnMessageOptions options with which to instantiate the message pump.

OnMessageAsync(Func<BrokeredMessage, Task>)

Asynchronously processes a message.

public void OnMessageAsync(Func<BrokeredMessage, Task> callback)

Parameters

callback Func<BrokeredMessage, Task>: The method to invoke when the operation is complete.

OnMessageAsync(Func<BrokeredMessage, Task>, OnMessageOptions)

Asynchronously processes a message.

public void OnMessageAsync(Func<BrokeredMessage, Task> callback, OnMessageOptions onMessageOptions)

Parameters

callback Func<BrokeredMessage, Task>: The method to invoke when the operation is complete.
onMessageOptions OnMessageOptions: Calls a message option.

Peek()

Returns without removing the first message in the queue.

public BrokeredMessage Peek()

Returns

BrokeredMessage: A brokered message. Returns all properties and the message body.

Remarks

A Null can be return by this API if operation exceeded the timeout specified, or the operations succeeded but there are no more messages to be received.

Peek(long)

Returns without removing the first message in the queue.

public BrokeredMessage Peek(long fromSequenceNumber)

Parameters

fromSequenceNumber long: The starting point from which to browse a message.

Returns

BrokeredMessage: The brokered message.

Remarks

A Null can be return by this API if operation exceeded the timeout specified, or the operations succeeded but there are no more messages to be received.

PeekAsync()

Asynchronously returns without removing the first message in the queue.

public Task<BrokeredMessage> PeekAsync()

Returns

Task<BrokeredMessage>: The asynchronous operation.

PeekAsync(long)

Asynchronously returns without removing the first message in the queue.

public Task<BrokeredMessage> PeekAsync(long fromSequenceNumber)

Parameters

fromSequenceNumber long: The sequence number from where to peek a message.

Returns

Task<BrokeredMessage>: The asynchronous operation.

PeekBatch(int)

Peeks a batch of messages.

public IEnumerable<BrokeredMessage> PeekBatch(int messageCount)

Parameters

messageCount int: The number of messages.

Returns

IEnumerable<BrokeredMessage>: A batch of messages peeked. Returns all properties and the message body.

Remarks

A Null can be return by this API if operation exceeded the timeout specified, or the operations succeeded but there are no more messages to be received.

PeekBatch(long, int)

Peeks a batch of messages.

public IEnumerable<BrokeredMessage> PeekBatch(long fromSequenceNumber, int messageCount)

Parameters

fromSequenceNumber long: The starting point from which to browse a batch of messages.
messageCount int: The number of messages.

Returns

IEnumerable<BrokeredMessage>: A batch of messages peeked.

PeekBatchAsync(int)

Asynchronously peeks a batch of message.

public Task<IEnumerable<BrokeredMessage>> PeekBatchAsync(int messageCount)

Parameters

messageCount int: The number of message.

Returns

Task<IEnumerable<BrokeredMessage>>: The asynchronous operation.

PeekBatchAsync(long, int)

Asynchronously peeks a batch of message.

public Task<IEnumerable<BrokeredMessage>> PeekBatchAsync(long fromSequenceNumber, int messageCount)

Parameters

fromSequenceNumber long: The sequence number from where to peek a batch of message.
messageCount int: The number of message.

Returns

Task<IEnumerable<BrokeredMessage>>: The asynchronous operation.

Receive()

Receives a message using the Microsoft.ServiceBus.Messaging.QueueClient.InternalReceiver.

public BrokeredMessage Receive()

Returns

BrokeredMessage: The BrokeredMessage that represents the received message. If no message is available to be received, the method returns NULL, and you can retry the operation at a later time.

Remarks

A Null can be return by this API if operation exceeded the timeout specified, or the operations succeeded but there are no more messages to be received.

Exceptions

OperationCanceledException: Thrown if the client entity has been closed or aborted.
TimeoutException: Thrown if the message receive operation times out.
UnauthorizedAccessException: Thrown if an I/O or security error occurs.
MessagingEntityNotFoundException: Thrown if the messaging entity associated with the operation does not exist or it has been deleted.
MessagingException: Thrown if the user code has performed some unexpected operations, or the Service Bus gateway is down. Check the exception message for the actual error.

Receive(long)

Receives a message using the Microsoft.ServiceBus.Messaging.QueueClient.InternalReceiver.

public BrokeredMessage Receive(long sequenceNumber)

Parameters

sequenceNumber long: The sequence number of the deferred message to receive.

Returns

BrokeredMessage: The BrokeredMessage that represents the received message. If no message is available to be received, the method returns NULL, and you can retry the operation at a later time.

Remarks

A Null can be return by this API if operation exceeded the timeout specified, or the operations succeeded but the message with the requested sequenceNumber cannot be located.

Exceptions

OperationCanceledException: Thrown if the client entity has been closed or aborted.

Receive(TimeSpan)

Receives a message using the Microsoft.ServiceBus.Messaging.QueueClient.InternalReceiver.

public BrokeredMessage Receive(TimeSpan serverWaitTime)

Parameters

serverWaitTime TimeSpan: The time span the server waits for receiving a message before it times out.

Returns

BrokeredMessage: The BrokeredMessage that represents the received message. If no message is available to be received, the method returns NULL, and you can retry the operation at a later time.

Remarks

A Null can be return by this API if operation exceeded the timeout specified, or the operations succeeded but there are no more messages to be received.

Exceptions

ArgumentOutOfRangeException: Thrown if the serverWaitTime is negative.
TimeoutException: Thrown if the message receive operation times out.
OperationCanceledException: Thrown if the client entity has been closed or aborted.
UnauthorizedAccessException: Thrown if an I/O or security error occurs.
MessagingEntityNotFoundException: Thrown if the messaging entity associated with the operation does not exist or it has been deleted.
MessagingException: Thrown if the user code has performed some unexpected operations, or the Service Bus gateway is down. Check the exception message for the actual error.

ReceiveAsync()

Asynchronously receives a message using the Microsoft.ServiceBus.Messaging.QueueClient.InternalReceiver.

public Task<BrokeredMessage> ReceiveAsync()

Returns

Task<BrokeredMessage>: The asynchronous operation.

ReceiveAsync(long)

Asynchronously receives a message using the Microsoft.ServiceBus.Messaging.QueueClient.InternalReceiver.

public Task<BrokeredMessage> ReceiveAsync(long sequenceNumber)

Parameters

sequenceNumber long: The sequence number of the deferred message to receive.

Returns

Task<BrokeredMessage>: The asynchronous operation.

ReceiveAsync(TimeSpan)

Asynchronously receives a message using the Microsoft.ServiceBus.Messaging.QueueClient.InternalReceiver.

public Task<BrokeredMessage> ReceiveAsync(TimeSpan serverWaitTime)

Parameters

serverWaitTime TimeSpan: The time span the server waits for receiving a message before it times out.

Returns

Task<BrokeredMessage>: The asynchronous operation.

ReceiveBatch(IEnumerable<long>)

Receives a message batch.

public IEnumerable<BrokeredMessage> ReceiveBatch(IEnumerable<long> sequenceNumbers)

Parameters

sequenceNumbers IEnumerable<long>: The sequence numbers associated with the messages in the batch.

Returns

IEnumerable<BrokeredMessage>: A message batch.

Remarks

A Null can be return by this API if operation exceeded the timeout specified, or the operations succeeded but the message with the requested sequenceNumber cannot be located.

ReceiveBatch(int)

Receives a message batch.

public IEnumerable<BrokeredMessage> ReceiveBatch(int messageCount)

Parameters

messageCount int: The number of messages to return in the batch. As this is an approximation, fewer or more messages than messageCount may be returned.

Returns

IEnumerable<BrokeredMessage>: A message batch.

Remarks

A Null can be return by this API if operation exceeded the timeout specified, or the operations succeeded but there are no more messages to be received.

ReceiveBatch(int, TimeSpan)

Receives a message batch.

public IEnumerable<BrokeredMessage> ReceiveBatch(int messageCount, TimeSpan serverWaitTime)

Parameters

messageCount int: The number of messages to receive in a batch.As this is an approximation, fewer or more messages than messageCount may be returned.
serverWaitTime TimeSpan: The time span that the server will wait for the message batch to arrive before it times out.

Returns

IEnumerable<BrokeredMessage>: A message batch.

Remarks

A Null can be return by this API if operation exceeded the timeout specified, or the operations succeeded but there are no more messages to be received.

ReceiveBatchAsync(IEnumerable<long>)

Asynchronously receives a message batch.

public Task<IEnumerable<BrokeredMessage>> ReceiveBatchAsync(IEnumerable<long> sequenceNumbers)

Parameters

sequenceNumbers IEnumerable<long>: The sequence numbers associated with the messages in the batch.

Returns

Task<IEnumerable<BrokeredMessage>>: The asynchronous operation.

ReceiveBatchAsync(int)

Asynchronously receives a message batch.

public Task<IEnumerable<BrokeredMessage>> ReceiveBatchAsync(int messageCount)

Parameters

messageCount int: The number of messages to return in the batch. As this is an approximation, fewer or more messages than messageCount may be returned.

Returns

Task<IEnumerable<BrokeredMessage>>: The asynchronous operation.

ReceiveBatchAsync(int, TimeSpan)

Asynchronously receives a message batch.

public Task<IEnumerable<BrokeredMessage>> ReceiveBatchAsync(int messageCount, TimeSpan serverWaitTime)

Parameters

messageCount int: The number of messages to return in the batch. As this is an approximation, fewer or more messages than messageCount may be returned.
serverWaitTime TimeSpan: The time span that the server will wait for the message batch to arrive before it times out.

Returns

Task<IEnumerable<BrokeredMessage>>: The asynchronous operation.

RegisterSessionHandler(Type)

Registers the session handler with specific type.

public void RegisterSessionHandler(Type handlerType)

Parameters

handlerType Type: The handler type.

RegisterSessionHandler(Type, SessionHandlerOptions)

Registers the session handler with specific type and handler options.

public void RegisterSessionHandler(Type handlerType, SessionHandlerOptions options)

Parameters

handlerType Type: The handler type.
options SessionHandlerOptions: The session handler options.

RegisterSessionHandlerAsync(Type)

Asynchronously registers the session handler with specific type.

public Task RegisterSessionHandlerAsync(Type handlerType)

Parameters

handlerType Type: The handler type.

Returns

Task: The task object representing the asynchronous operation.

RegisterSessionHandlerAsync(Type, SessionHandlerOptions)

Asynchronously registers the session handler with specific type and handler options.

public Task RegisterSessionHandlerAsync(Type handlerType, SessionHandlerOptions options)

Parameters

handlerType Type: The handler type.
options SessionHandlerOptions: The session handler options.

Returns

Task: The task object representing the asynchronous operation.

RegisterSessionHandlerFactory(IMessageSessionAsyncHandlerFactory, SessionHandlerOptions)

Registers a message session handler factory with specified options.

public void RegisterSessionHandlerFactory(IMessageSessionAsyncHandlerFactory factory, SessionHandlerOptions options)

Parameters

factory IMessageSessionAsyncHandlerFactory: The handler factory to be registered.
options SessionHandlerOptions: The handler options.

RegisterSessionHandlerFactory(IMessageSessionHandlerFactory, SessionHandlerOptions)

Registers a message session handler factory with specified options.

public void RegisterSessionHandlerFactory(IMessageSessionHandlerFactory factory, SessionHandlerOptions options)

Parameters

factory IMessageSessionHandlerFactory: The handler factory to be registered.
options SessionHandlerOptions: The handler options.

RegisterSessionHandlerFactoryAsync(IMessageSessionAsyncHandlerFactory, SessionHandlerOptions)

Asynchronously registers a message session handler factory.

public Task RegisterSessionHandlerFactoryAsync(IMessageSessionAsyncHandlerFactory factory, SessionHandlerOptions options)

Parameters

factory IMessageSessionAsyncHandlerFactory: The handler factory to be registered.
options SessionHandlerOptions: The handler options.

Returns

Task: The task object representing the asynchronous operation.

RegisterSessionHandlerFactoryAsync(IMessageSessionHandlerFactory, SessionHandlerOptions)

Asynchronously registers a message session handler factory.

public Task RegisterSessionHandlerFactoryAsync(IMessageSessionHandlerFactory factory, SessionHandlerOptions options)

Parameters

factory IMessageSessionHandlerFactory: The handler factory to be registered.
options SessionHandlerOptions: The handler options.

Returns

Task: The task object representing the asynchronous operation.

RenewMessageLock(Guid)

public DateTime RenewMessageLock(Guid lockToken)

Parameters

lockToken Guid

Returns

DateTime

RenewMessageLockAsync(Guid)

public Task<DateTime> RenewMessageLockAsync(Guid lockToken)

Parameters

lockToken Guid

Returns

Task<DateTime>

ScheduleMessageAsync(BrokeredMessage, DateTimeOffset)

Sends a scheduled message

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

Parameters

message BrokeredMessage: Message to be scheduled
scheduleEnqueueTimeUtc DateTimeOffset: Time of enqueue

Returns

Task<long>: Sequence number that is needed for cancelling.

Send(BrokeredMessage)

Sends a message using the Microsoft.ServiceBus.Messaging.QueueClient.InternalSender.

public void Send(BrokeredMessage message)

Parameters

message BrokeredMessage: The message to send.

Exceptions

TimeoutException: Thrown when operation times out. Timeout period is initialized through the MessagingFactorySettings may need to increase the value of OperationTimeout to avoid this exception if timeout value is relatively low.
ArgumentException: Thrown when the message is null.
InvalidOperationException: Thrown if the message has already been sent by a QueueClient or MessageSender once already.
InvalidOperationException: Thrown if the topic/subscription pointed to does not support the send operation. That is, Deadletter queue does not support send operations.
OperationCanceledException: Thrown if the client entity has been closed or aborted.
UnauthorizedAccessException: Thrown if there is an I/O or security error.
SerializationException: Thrown when an error occurs during serialization or deserialization.
MessagingEntityNotFoundException: Thrown if the queue does not exist.
MessagingException: Thrown if there is a messaging error.

SendAsync(BrokeredMessage)

Asynchronously sends a message using the Microsoft.ServiceBus.Messaging.QueueClient.InternalSender.

public Task SendAsync(BrokeredMessage message)

Parameters

message BrokeredMessage: The message to send.

Returns

Task: The asynchronous operation.

SendBatch(IEnumerable<BrokeredMessage>)

Sends a set of brokered messages (for batch processing).

public void SendBatch(IEnumerable<BrokeredMessage> messages)

Parameters

messages IEnumerable<BrokeredMessage>: The collection of brokered messages to send.

SendBatchAsync(IEnumerable<BrokeredMessage>)

Asynchronously sends a set of brokered messages (for batch processing).

public Task SendBatchAsync(IEnumerable<BrokeredMessage> messages)

Parameters

messages IEnumerable<BrokeredMessage>: The collection of brokered messages to send.

Returns

Task: The asynchronous operation.

Table of Contents

Class QueueClient

Properties

MessagingFactory

Property Value

Mode

Property Value

Path

Property Value

PrefetchCount

Property Value

Remarks

Methods

Abandon(Guid)

Parameters

Remarks

Exceptions

Abandon(Guid, IDictionary<string, object>)

Parameters

Remarks

AbandonAsync(Guid)

Parameters

Returns

AbandonAsync(Guid, IDictionary<string, object>)

Parameters

Returns

AcceptMessageSession()

Returns

Exceptions

AcceptMessageSession(bool)

Parameters

Returns

AcceptMessageSession(bool, TimeSpan)

Parameters

Returns

AcceptMessageSession(string)

Parameters

Returns

Exceptions

AcceptMessageSession(string, bool)

Parameters

Returns

AcceptMessageSession(string, bool, TimeSpan)

Parameters

Returns

AcceptMessageSession(string, Guid)

Parameters

Returns

AcceptMessageSession(string, Guid, TimeSpan)

Parameters

Returns

AcceptMessageSession(string, TimeSpan)

Parameters

Returns

Exceptions

AcceptMessageSession(TimeSpan)

Parameters

Returns

Exceptions

AcceptMessageSessionAsync()

Returns

AcceptMessageSessionAsync(bool)

Parameters

Returns

AcceptMessageSessionAsync(bool, TimeSpan)

Parameters

Returns

AcceptMessageSessionAsync(string)

Parameters

Returns

AcceptMessageSessionAsync(string, bool)

Parameters

Returns

AcceptMessageSessionAsync(string, bool, TimeSpan)

Parameters

Returns

AcceptMessageSessionAsync(string, Guid)

Parameters

Returns

AcceptMessageSessionAsync(string, Guid, TimeSpan)