Table of Contents

Interface IMessageReceiver

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

The MessageReceiver can be used to receive messages from Queues and Subscriptions and acknowledge them.

public interface IMessageReceiver : IReceiverClient, IClientEntity
Inherited Members

Examples

Create a new MessageReceiver to receive a message from a Subscription

IMessageReceiver messageReceiver = new MessageReceiver(
    namespaceConnectionString,
    EntityNameHelper.FormatSubscriptionPath(topicName, subscriptionName),
    ReceiveMode.PeekLock);

Receive a message from the Subscription.

var message = await messageReceiver.ReceiveAsync();
await messageReceiver.CompleteAsync(message.SystemProperties.LockToken);

Remarks

The MessageReceiver provides advanced functionality that is not found in the QueueClient or SubscriptionClient. For instance, ReceiveAsync(), which allows you to receive messages on demand, but also requires you to manually renew locks using RenewLockAsync(Message).

Properties

LastPeekedSequenceNumber

Gets the sequence number of the last peeked message.

long LastPeekedSequenceNumber { get; }

Property Value

long
See Also

Methods

CompleteAsync(IEnumerable<string>)

Completes a series of Message using a list of lock tokens. This will delete the message from the service.

Task CompleteAsync(IEnumerable<string> lockTokens)

Parameters

lockTokens IEnumerable<string>

An IEnumerable<T> containing the lock tokens of the corresponding messages to complete.

Returns

Task

Remarks

A lock token can be found in LockToken, only when ReceiveMode is set to PeekLock.

DeferAsync(string, IDictionary<string, object>)

Indicates that the receiver wants to defer the processing for the message.

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

Parameters

lockToken string

The lock token of the Message.

propertiesToModify IDictionary<string, object>

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

Returns

Task

Remarks

A lock token can be found in LockToken, only when ReceiveMode is set to PeekLock. In order to receive this message again in the future, you will need to save the SequenceNumber and receive it using ReceiveDeferredMessageAsync(long). Deferring messages does not impact message's expiration, meaning that deferred messages can still expire. This operation can only be performed on messages that were received by this receiver.

PeekAsync()

Fetches the next active message without changing the state of the receiver or the message source.

Task<Message> PeekAsync()

Returns

Task<Message>

The Message that represents the next message to be read. Returns null when nothing to peek.

Remarks

The first call to PeekAsync() fetches the first active message for this receiver. Each subsequent call fetches the subsequent message in the entity. Unlike a received messaged, peeked message will not have lock token associated with it, and hence it cannot be Completed/Abandoned/Deferred/Deadlettered/Renewed. Also, unlike ReceiveAsync(), this method will fetch even Deferred messages (but not Deadlettered message)

PeekAsync(int)

Fetches the next batch of active messages without changing the state of the receiver or the message source.

Task<IList<Message>> PeekAsync(int maxMessageCount)

Parameters

maxMessageCount int

Returns

Task<IList<Message>>

List of Message that represents the next message to be read. Returns null when nothing to peek.

Remarks

The first call to PeekAsync() fetches the first active message for this receiver. Each subsequent call fetches the subsequent message in the entity. Unlike a received message, peeked message will not have lock token associated with it, and hence it cannot be Completed/Abandoned/Deferred/Deadlettered/Renewed. Also, unlike ReceiveAsync(), this method will fetch even Deferred messages (but not Deadlettered message)

PeekBySequenceNumberAsync(long)

Asynchronously reads the next message without changing the state of the receiver or the message source.

Task<Message> PeekBySequenceNumberAsync(long fromSequenceNumber)

Parameters

fromSequenceNumber long

The sequence number from where to read the message.

Returns

Task<Message>

The asynchronous operation that returns the Message that represents the next message to be read.

PeekBySequenceNumberAsync(long, int)

Peeks a batch of messages.

Task<IList<Message>> PeekBySequenceNumberAsync(long fromSequenceNumber, int messageCount)

Parameters

fromSequenceNumber long

The starting point from which to browse a batch of messages.

messageCount int

Returns

Task<IList<Message>>

A batch of messages peeked.

ReceiveAsync()

Receive a message from the entity defined by Path using ReceiveMode mode.

Task<Message> ReceiveAsync()

Returns

Task<Message>

The message received. Returns null if no message is found.

Remarks

Operation will time out after duration of OperationTimeout

ReceiveAsync(int)

Receives a maximum of maxMessageCount messages from the entity defined by Path using ReceiveMode mode.

Task<IList<Message>> ReceiveAsync(int maxMessageCount)

Parameters

maxMessageCount int

The maximum number of messages that will be received.

Returns

Task<IList<Message>>

List of messages received. Returns null if no message is found.

Remarks

Receiving less than maxMessageCount messages is not an indication of empty entity.

ReceiveAsync(int, TimeSpan)

Receives a maximum of maxMessageCount messages from the entity defined by Path using ReceiveMode mode.

Task<IList<Message>> ReceiveAsync(int maxMessageCount, TimeSpan operationTimeout)

Parameters

maxMessageCount int

The maximum number of messages that will be received.

operationTimeout TimeSpan

The time span the client waits for receiving a message before it times out.

Returns

Task<IList<Message>>

List of messages received. Returns null if no message is found.

Remarks

Receiving less than maxMessageCount messages is not an indication of empty entity. The parameter operationTimeout includes the time taken by the receiver to establish a connection (either during the first receive or when connection needs to be re-established). If establishing the connection times out, this will throw ServiceBusTimeoutException.

ReceiveAsync(TimeSpan)

Receive a message from the entity defined by Path using ReceiveMode mode.

Task<Message> ReceiveAsync(TimeSpan operationTimeout)

Parameters

operationTimeout TimeSpan

The time span the client waits for receiving a message before it times out.

Returns

Task<Message>

The message received. Returns null if no message is found.

Remarks

The parameter operationTimeout includes the time taken by the receiver to establish a connection (either during the first receive or when connection needs to be re-established). If establishing the connection times out, this will throw ServiceBusTimeoutException.

ReceiveDeferredMessageAsync(IEnumerable<long>)

Receives a IList<T> of deferred messages identified by sequenceNumbers.

Task<IList<Message>> ReceiveDeferredMessageAsync(IEnumerable<long> sequenceNumbers)

Parameters

sequenceNumbers IEnumerable<long>

An IEnumerable<T> containing the sequence numbers to receive.

Returns

Task<IList<Message>>

Messages identified by sequence number are returned. Returns null if no messages are found. Throws if the messages have not been deferred.

See Also

ReceiveDeferredMessageAsync(long)

Receives a specific deferred message identified by sequenceNumber.

Task<Message> ReceiveDeferredMessageAsync(long sequenceNumber)

Parameters

sequenceNumber long

The sequence number of the message that will be received.

Returns

Task<Message>

Message identified by sequence number sequenceNumber. Returns null if no such message is found. Throws if the message has not been deferred.

See Also

RenewLockAsync(Message)

Renews the lock on the message. The lock will be renewed based on the setting specified on the queue.

Task RenewLockAsync(Message message)

Parameters

message Message

Returns

Task

Remarks

When a message is received in PeekLock mode, the message is locked on the server for this receiver instance for a duration as specified during the Queue/Subscription creation (LockDuration). If processing of the message requires longer than this duration, the lock needs to be renewed. For each renewal, it resets the time the message is locked by the LockDuration set on the Entity.

RenewLockAsync(string)

Renews the lock on the message. The lock will be renewed based on the setting specified on the queue. New lock token expiry date and time in UTC format.

Task<DateTime> RenewLockAsync(string lockToken)

Parameters

lockToken string

Lock token associated with the message.

Returns

Task<DateTime>

Remarks

When a message is received in PeekLock mode, the message is locked on the server for this receiver instance for a duration as specified during the Queue/Subscription creation (LockDuration). If processing of the message requires longer than this duration, the lock needs to be renewed. For each renewal, it resets the time the message is locked by the LockDuration set on the Entity.

See Also

MessageReceiver
QueueClient
SubscriptionClient