BrokeredMessage BrokeredMessage Class

Definition

Represents the unit of communication between Service Bus clients.

public sealed class BrokeredMessage : IXmlSerializable, IDisposablePublic NotInheritable Class BrokeredMessage
    Implements IXmlSerializable, IDisposable
Inheritance
BrokeredMessageBrokeredMessage

Inherited Members

System.Object

Constructors

BrokeredMessage() BrokeredMessage()

Initializes a new instance of the BrokeredMessage class.

public BrokeredMessage()Public Sub New

BrokeredMessage(Stream) BrokeredMessage(Stream)

Initializes a new instance of the BrokeredMessage class.

public BrokeredMessage(Stream messageBodyStream)Public Sub New(messageBodyStream As Stream)
Parameters
messageBodyStream
Stream Stream

The message body stream.

BrokeredMessage(Stream, Boolean) BrokeredMessage(Stream, Boolean)

Initializes a new instance of the BrokeredMessage class using the supplied stream as its body.

public BrokeredMessage(Stream messageBodyStream, bool ownsStream)Public Sub New(messageBodyStream As Stream, ownsStream As Boolean)
Parameters
messageBodyStream
Stream Stream

The message body stream.

ownsStream
Boolean Boolean

true to indicate that the stream will be closed when the message is closed; false to indicate that the stream will not be closed when the message is closed.

BrokeredMessage(Object) BrokeredMessage(Object)

Initializes a new instance of the BrokeredMessage class from a given object by using DataContractSerializer with a binary XmlDictionaryWriter.

public BrokeredMessage(object serializableObject)Public Sub New(serializableObject As Object)
Parameters
serializableObject
Object Object

The object to be serialized into the message body.

Remarks

A default Microsoft.ServiceBus.Messaging.DataContractBinarySerializer is used for serializing the object.

BrokeredMessage(Object, XmlObjectSerializer) BrokeredMessage(Object, XmlObjectSerializer)

Constructor that creates a BrokeredMessage from a given object using the provided XmlObjectSerializer

public BrokeredMessage(object serializableObject, XmlObjectSerializer serializer)Public Sub New(serializableObject As Object, serializer As XmlObjectSerializer)
Parameters
serializableObject
Object Object

The serializable object.

serializer
XmlObjectSerializer XmlObjectSerializer

The serializer object.

Exceptions

Thrown when null serializer is passed to the method with a non-null serializableObject

Remarks

You should be aware of the exceptions that their provided Serializer can throw and take appropriate actions. Please refer to for a possible list of exceptions and their cause.

Properties

ContentType ContentType

Gets or sets the type of the content.

public string ContentType { get; set; }Public Property ContentType As String
Value
String String

The type of the content of the message body. This is a content type identifier utilized by the sender and receiver for application specific logic.

Exceptions

Thrown if the message is in disposed state.

CorrelationId CorrelationId

Gets or sets the identifier of the correlation.

public string CorrelationId { get; set; }Public Property CorrelationId As String
Value
String String

The identifier of the correlation.

Exceptions

Thrown if the message is in disposed state.

DeadLetterSource DeadLetterSource

public string DeadLetterSource { get; }Public ReadOnly Property DeadLetterSource As String
Value
String String

DeliveryCount DeliveryCount

Gets the number of deliveries.

public int DeliveryCount { get; }Public ReadOnly Property DeliveryCount As Integer
Value
Int32 Int32

The number of deliveries.

Exceptions

Thrown if the message is in disposed state.

Thrown if the message has not been delivered by ServiceBus.

EnqueuedSequenceNumber EnqueuedSequenceNumber

Gets or sets the enqueued sequence number of the message.

public long EnqueuedSequenceNumber { get; }Public ReadOnly Property EnqueuedSequenceNumber As Long
Value
Int64 Int64

The enqueued sequence number of the message.

EnqueuedTimeUtc EnqueuedTimeUtc

Gets or sets the date and time of the sent time in UTC.

public DateTime EnqueuedTimeUtc { get; }Public ReadOnly Property EnqueuedTimeUtc As Date
Value
DateTime DateTime

The enqueue time in UTC. This value represents the actual time of enqueuing the message.

Exceptions

Thrown if the message is in disposed state.

ExpiresAtUtc ExpiresAtUtc

Gets the date and time in UTC at which the message is set to expire.

public DateTime ExpiresAtUtc { get; }Public ReadOnly Property ExpiresAtUtc As Date
Value
DateTime DateTime

The message expiration time in UTC.

Exceptions

Thrown if the message is in disposed state.

If the message has not been delivered by ServerBus.

ForcePersistence ForcePersistence

Gets or sets a value that indicates whether the message is to be persisted to the database immediately, instead of being held in memory for a short time. This property is ignored if the message is sent to a non-express queue or topic.

public bool ForcePersistence { get; set; }Public Property ForcePersistence As Boolean
Value
Boolean Boolean

true if the message is to be persisted to the database immediately, instead of being held in memory for a short time; otherwise, false.

IsBodyConsumed IsBodyConsumed

Specifies whether the message has been consumed.

public bool IsBodyConsumed { get; }Public ReadOnly Property IsBodyConsumed As Boolean
Value
Boolean Boolean

true if the message has been consumed; otherwise, false.

Label Label

Gets or sets the application specific label.

public string Label { get; set; }Public Property Label As String
Value
String String

The application specific label.

Exceptions

Thrown if the message is in disposed state.

LockedUntilUtc LockedUntilUtc

Gets the date and time in UTC until which the message will be locked in the queue/subscription.

public DateTime LockedUntilUtc { get; }Public ReadOnly Property LockedUntilUtc As Date
Value
DateTime DateTime

The date and time until which the message will be locked in the queue/subscription.

Exceptions

Thrown if the message is in disposed state.

Thrown if the message was not received from the ServiceBus.

LockToken LockToken

Gets the lock token assigned by Service Bus to this message.

public Guid LockToken { get; }Public ReadOnly Property LockToken As Guid
Value
Guid Guid

The lock token assigned by Service Bus to this message.

Exceptions

Thrown if the message is in disposed state.

Thrown if the message was not received from the ServiceBus.

MessageId MessageId

Gets or sets the identifier of the message. This is a user-defined value that Service Bus can use to identify duplicate messages, if enabled.

public string MessageId { get; set; }Public Property MessageId As String
Value
String String

The identifier of the message.

Exceptions

Thrown if the message is in a disposed state.

Thrown if the message identifier is null or exceeds 128 characters in length.

PartitionKey PartitionKey

Gets or sets a partition key for sending a transactional message to a queue or topic that is not session-aware.

public string PartitionKey { get; set; }Public Property PartitionKey As String
Value
String String

The partition key for sending a transactional message.

Properties Properties

Gets the application specific message properties.

public IDictionary<string, object> Properties { get; }Public ReadOnly Property Properties As IDictionary(Of String, Object)
Value
IDictionary<String, Object> IDictionary(Of String, Object)

The application specific message properties.

Exceptions

Thrown if the message is in disposed state.

Remarks

The size of each property object within the Properties bag cannot exceed 32 kilobytes. The collective size of the Properties bag cannot exceed 64 kilobytes.

ReplyTo ReplyTo

Gets or sets the address of the queue to reply to.

public string ReplyTo { get; set; }Public Property ReplyTo As String
Value
String String

The reply to queue address.

Exceptions

Thrown if the message is in disposed state.

ReplyToSessionId ReplyToSessionId

Gets or sets the session identifier to reply to.

public string ReplyToSessionId { get; set; }Public Property ReplyToSessionId As String
Value
String String

The session identifier to reply to.

Exceptions

Thrown if the message is in disposed state.

ScheduledEnqueueTimeUtc ScheduledEnqueueTimeUtc

Gets or sets the date and time in UTC at which the message will be enqueued. This property returns the time in UTC; when setting the property, the supplied DateTime value must also be in UTC.

public DateTime ScheduledEnqueueTimeUtc { get; set; }Public Property ScheduledEnqueueTimeUtc As Date
Value
DateTime DateTime

The scheduled enqueue time in UTC. This value is for delayed message sending. It is utilized to delay messages sending to a specific time in the future.

Exceptions

Thrown if the message is in disposed state.

Thrown if the passed in value is DateTime.MaxValue.

Remarks

Message enquing time does not mean that the message will be sent at the same time. It will get enqueued, but the actual sending time depends on the queue's workload and its state. EnqueuedTimeUtc

SequenceNumber SequenceNumber

Gets the unique number assigned to a message by the Service Bus.

public long SequenceNumber { get; }Public ReadOnly Property SequenceNumber As Long
Value
Int64 Int64

The unique number assigned to a message by the Service Bus.

Exceptions

Thrown if the message is in disposed state.

Thrown if the message was not received from the message server.

SessionId SessionId

Gets or sets the identifier of the session.

public string SessionId { get; set; }Public Property SessionId As String
Value
String String

The identifier of the session.

Exceptions

Thrown if the message is in disposed state.

Size Size

Gets the size of the message in bytes.

public long Size { get; }Public ReadOnly Property Size As Long
Value
Int64 Int64

The message size in bytes.

Exceptions

Thrown if the message is in disposed state.

Remarks

The value of Size is only accurate after the BrokeredMessage instance is sent or received.

State State

Gets or sets the state of the message.

public MessageState State { get; }Public ReadOnly Property State As MessageState
Value
MessageState MessageState

The state of the message.

TimeToLive TimeToLive

Gets or sets the message’s time to live value. This is the duration after which the message expires, starting from when the message is sent to the Service Bus. Messages older than their TimeToLive value will expire and no longer be retained in the message store. Subscribers will be unable to receive expired messages.TimeToLive is the maximum lifetime that a message can receive, but its value cannot exceed the entity specified the DefaultMessageTimeToLive value on the destination queue or subscription. If a lower TimeToLive value is specified, it will be applied to the individual message. However, a larger value specified on the message will be overridden by the entity’s DefaultMessageTimeToLive value.

public TimeSpan TimeToLive { get; set; }Public Property TimeToLive As TimeSpan
Value
TimeSpan TimeSpan

The message’s time to live value.

Exceptions

Thrown if the message is in disposed state.

Thrown if the passed in value is less than or equal to TimeSpan.Zero.

Remarks

If the TTL set on a message by the sender exceeds the destination's TTL, then the message's TTL will be overwritten by the later one. See DefaultMessageTimeToLive, DefaultMessageTimeToLive and DefaultMessageTimeToLive to learn more about how to control message TTL at an entity level.

To To

Gets or sets the send to address.

public string To { get; set; }Public Property To As String
Value
String String

The send to address.

Exceptions

Thrown if the message is in disposed state.

ViaPartitionKey ViaPartitionKey

Gets or sets a partition key value when a transaction is to be used to send messages via a transfer queue.

public string ViaPartitionKey { get; set; }Public Property ViaPartitionKey As String
Value
String String

The partition key value when a transaction is to be used to send messages via a transfer queue.

Methods

Abandon() Abandon()

Abandons the lock on a peek-locked message.

public void Abandon()Public Sub Abandon
Exceptions

Thrown when the message is in the disposed state or the receiver with which the message was received is in disposed state.

Thrown when invoked on a message that has not been received from the message server or invoked on a message that has not been received in peek-lock mode.

Thrown when operation times out. The timeout period is initialized through the MessagingFactorySettings. You may need to increase the value of OperationTimeout to avoid this exception if the timeout value is relatively low.

Thrown when the queue or subscription that receives the message is no longer present in the message server.

When service bus service is busy and is unable process the request.

When messaging entity the message was received from has been deleted.

When the lock associated with this message was lost or the lock token was not found.

When this message was received from a Session and the lock associated with the session was lost.

When the security token provided by the TokenProvider does not contain the claims to perform this operation.

When the number of concurrent connections to an entity exceed the maximum allowed value.

Remarks

This operation should only be exercised on a message received in peek-lock mode.

Abandon(IDictionary<String, Object>) Abandon(IDictionary(Of String, Object))

Abandons the lock on a peek-locked message.

public void Abandon(IDictionary<string, object> propertiesToModify)Public Sub Abandon(propertiesToModify As IDictionary(Of String, Object))
Parameters
propertiesToModify
IDictionary<String, Object> IDictionary(Of String, Object)

The key-value pair collection of properties to modify.

Exceptions

Thrown when operation times out. Timeout period is initialized through the MessagingFactorySettings. You may need to increase the value of OperationTimeout to avoid this exception if timeout value is relatively low. OperationTimeout

Thrown when the queue or subscription that the message was received from is no longer present in the message server.

Remarks

This operation should only be exercised on a message received in peek-lock mode.

AbandonAsync() AbandonAsync()

Asynchronously abandons the lock on a peek-locked message.

public Task AbandonAsync()Public Function AbandonAsync As Task
Returns

The asynchronous result of the operation.

AbandonAsync(IDictionary<String, Object>) AbandonAsync(IDictionary(Of String, Object))

Asynchronously abandons the lock on a peek-locked message.

public Task AbandonAsync(IDictionary<string, object> propertiesToModify)Public Function AbandonAsync(propertiesToModify As IDictionary(Of String, Object)) As Task
Parameters
propertiesToModify
IDictionary<String, Object> IDictionary(Of String, Object)

The key-value pair collection of properties to modify.

Returns

The asynchronous result of the operation.

Clone() Clone()

Clones a message, so that it is possible to send a clone of a message as a new message.

public BrokeredMessage Clone()Public Function Clone As BrokeredMessage
Returns

The BrokeredMessage that contains the cloned message.

Complete() Complete()

Completes the receive operation of a message and indicates that the message should be marked as processed and deleted.

public void Complete()Public Sub Complete
Exceptions

Thrown when the message is in disposed state or the receiver with which the message was received is in disposed state.

Thrown when invoked on a message that has not been received from the message server or invoked on a message that has not been received in peek-lock mode.

Thrown when the queue or subscription that receives the message is no longer present in the message server.

Thrown when the operation times out. The timeout period is initialized through the MessagingFactorySettings. You may need to increase the value of OperationTimeout to avoid this exception if the timeout value is relatively low.

Thrown if the lock on the message has expired. LockDuration is an entity-wide setting and can be initialized through LockDuration and LockDuration for queues and subscriptions respectively.

Thrown if the lock on the session has expired. The session lock duration is the same as the message LockDuration and is an entity-wide setting. It can be initialized through LockDuration and LockDuration for queues and subscriptions respectively.

When service bus service is busy and is unable process the request.

When messaging entity the message was received from has been deleted.

When the security token provided by the TokenProvider does not contain the claims to perform this operation.

When the number of concurrent connections to an entity exceed the maximum allowed value.

Remarks

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

CompleteAsync() CompleteAsync()

Asynchronously completes the receive operation of a message and indicates that the message should be marked as processed and deleted.

public Task CompleteAsync()Public Function CompleteAsync As Task
Returns

The asynchronous result of the operation.

DeadLetter() DeadLetter()

Moves the message to the dead letter queue.

public void DeadLetter()Public Sub DeadLetter
Exceptions

Thrown when the message is in disposed state or the receiver with which the message was received is in disposed state.

Thrown when invoked on a message that has not been received from the message server or invoked on a message that has not been received in peek-lock mode.

DeadLetter(IDictionary<String, Object>) DeadLetter(IDictionary(Of String, Object))

Moves the message to the dead letter queue.

public void DeadLetter(IDictionary<string, object> propertiesToModify)Public Sub DeadLetter(propertiesToModify As IDictionary(Of String, Object))
Parameters
propertiesToModify
IDictionary<String, Object> IDictionary(Of String, Object)

The key-value pair collection of properties to modify.

DeadLetter(String, String) DeadLetter(String, String)

Moves the message to the dead letter queue.

public void DeadLetter(string deadLetterReason, string deadLetterErrorDescription)Public Sub DeadLetter(deadLetterReason As String, deadLetterErrorDescription As String)
Parameters
deadLetterReason
String String

The reason for deadlettering the message.

deadLetterErrorDescription
String String

The description information for deadlettering the message.

Exceptions

Thrown when the message is in disposed state or the receiver with which the message was received is in disposed state.

Thrown when invoked on a message that has not been received from the message server or invoked on a message that has not been received in peek-lock mode.

Thrown when the queue or subscription that receives the message is no longer present in the message server.

Thrown when operation times out. Timeout period is initialized through the MessagingFactorySettings. You may need to increase the value of OperationTimeout to avoid this exception if timeout value is relatively low.

Thrown if the lock on the message has expired. LockDuration is an entity-wide setting and can be initialized through LockDuration and LockDuration for Queues and Subscriptions respectively.

Thrown if the lock on the session has expired. Session lock duration is the same as message LockDuration and is an entity-wide setting. It can be initialized through LockDuration and LockDuration for Queues and Subscriptions respectively.

DeadLetterAsync() DeadLetterAsync()

Asynchronously moves the message to the dead letter queue.

public Task DeadLetterAsync()Public Function DeadLetterAsync As Task
Returns

The asynchronous result of the operation.

DeadLetterAsync(IDictionary<String, Object>) DeadLetterAsync(IDictionary(Of String, Object))

Asynchronously moves the message to the dead letter queue.

public Task DeadLetterAsync(IDictionary<string, object> propertiesToModify)Public Function DeadLetterAsync(propertiesToModify As IDictionary(Of String, Object)) As Task
Parameters
propertiesToModify
IDictionary<String, Object> IDictionary(Of String, Object)

The key-value pair collection of properties to modify.

Returns

The asynchronous result of the operation.

DeadLetterAsync(String, String) DeadLetterAsync(String, String)

Asynchronously moves the message to the dead letter queue.

public Task DeadLetterAsync(string deadLetterReason, string deadLetterErrorDescription)Public Function DeadLetterAsync(deadLetterReason As String, deadLetterErrorDescription As String) As Task
Parameters
deadLetterReason
String String

The reason for deadlettering the message.

deadLetterErrorDescription
String String

The description information for deadlettering the message.

Returns

The asynchronous result of the operation.

Defer() Defer()

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

public void Defer()Public Sub Defer
Exceptions

Thrown when the message is in the disposed state or the receiver with which the message was received is in the disposed state.

Thrown when invoked on a message that has not been received from the message server or invoked on a message that has not been received in peek-lock mode.

Thrown when the queue or subscription that receives the message is no longer present in the message server.

Thrown when the operation times out. The timeout period is initialized through the MessagingFactorySettings. You may need to increase the value of OperationTimeout to avoid this exception if the timeout value is relatively low.

Thrown if the lock on the message has expired. LockDuration is an entity-wide setting and can be initialized through LockDuration and LockDuration for queues and subscriptions respectively.

Thrown if the lock on the session has expired. The session lock duration is the same as the message LockDuration and is an entity-wide setting. It can be initialized through LockDuration and LockDuration for queues and subscriptions respectively.

When service bus service is busy and is unable process the request.

When messaging entity the message was received from has been deleted.

When the security token provided by the TokenProvider does not contain the claims to perform this operation.

When the number of concurrent connections to an entity exceed the maximum allowed value.

Remarks

Before deferring the message, user MUST set aside the message receipt for later retrieval.

Defer(IDictionary<String, Object>) Defer(IDictionary(Of String, Object))

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

public void Defer(IDictionary<string, object> propertiesToModify)Public Sub Defer(propertiesToModify As IDictionary(Of String, Object))
Parameters
propertiesToModify
IDictionary<String, Object> IDictionary(Of String, Object)

The key-value pair collection of properties to modify.

Remarks

Before deferring the message, user MUST set aside the message receipt for later retrieval.

DeferAsync() DeferAsync()

Asynchronously indicates that the receiver wants to defer the processing for this message.

public Task DeferAsync()Public Function DeferAsync As Task
Returns

The asynchronous result of the operation.

DeferAsync(IDictionary<String, Object>) DeferAsync(IDictionary(Of String, Object))

Asynchronously indicates that the receiver wants to defer the processing for this message.

public Task DeferAsync(IDictionary<string, object> propertiesToModify)Public Function DeferAsync(propertiesToModify As IDictionary(Of String, Object)) As Task
Parameters
propertiesToModify
IDictionary<String, Object> IDictionary(Of String, Object)

The key-value pair collection of properties to modify.

Returns

The asynchronous result of the operation.

Dispose() Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()Public Sub Dispose

GetBody<T>() GetBody(Of T)()

Deserializes the brokered message body into an object of the specified type by using the DataContractSerializer with a binary XmlDictionaryReader.

public T GetBody<T>()Public Function GetBody(Of T) As T
Returns
T T

The deserialized object or graph.

Exceptions

If the message is in disposed state or the message body stream is already disposed.

If the message contains a null body stream or the body stream contains no data or the message body has already been consumed.

GetBody<T>(XmlObjectSerializer) GetBody(Of T)(XmlObjectSerializer)

Deserializes the BrokeredMessage body into an object of the specified type using DataContractSerializer with a Binary XmlObjectSerializer.

public T GetBody<T>(XmlObjectSerializer serializer)Public Function GetBody(Of T)(serializer As XmlObjectSerializer) As T
Parameters
serializer
XmlObjectSerializer XmlObjectSerializer

The serializer object.

Returns
T T

The deserialized object/graph

Exceptions

Thrown if the message is in disposed state.

Thrown when invoked with a Null serializer object.

Thrown if the message contains a Null body stream, contains no data, or if the stream has been read once (through any GetBody() calls).

RenewLock() RenewLock()

Renews the lock on a message.

public void RenewLock()Public Sub RenewLock
Exceptions

If IsTransient is true, you can retry the operation immediately.

You can retry the operation immediately.

Thrown if you have called RenewLock() too late. In a session, this is never thrown.

RenewLockAsync() RenewLockAsync()

Asynchronously renews the lock on a message.

public Task RenewLockAsync()Public Function RenewLockAsync As Task
Returns

The asynchronous result of the operation.

ToString() ToString()

Returns a string that represents the current message.

public override string ToString()Public Overrides Function ToString As String
Returns

The string representation of the current message.

Overrides

Explicit Interface Implementations

IXmlSerializable.GetSchema() System.Xml.Serialization.IXmlSerializable.GetSchema()

This method is reserved and should not be used. When implementing the IXmlSerializable interface, you should return null (Nothing in Visual Basic) from this method, and instead, if specifying a custom schema is required, apply the XmlSchemaProviderAttribute to the class.

XmlSchema IXmlSerializable.GetSchema()Function System.Xml.Serialization.IXmlSerializable.GetSchema As XmlSchema Implements IXmlSerializable.GetSchema
Returns

An XmlSchema that describes the XML representation of the object that is produced by the WriteXml method and consumed by the ReadXml method.

IXmlSerializable.ReadXml(XmlReader) System.Xml.Serialization.IXmlSerializable.ReadXml(XmlReader)

Generates an object from its XML representation. This method is reserved for internal use and should not be used directly or indirectly (for example, using a serializer or a formatter).

void IXmlSerializable.ReadXml(XmlReader reader)Sub System.Xml.Serialization.IXmlSerializable.ReadXml(reader As XmlReader) Implements IXmlSerializable.ReadXml
Parameters
reader
XmlReader XmlReader

The XmlReader stream from which the object is deserialized.

IXmlSerializable.WriteXml(XmlWriter) System.Xml.Serialization.IXmlSerializable.WriteXml(XmlWriter)

Converts an object into its XML representation. This method is reserved for internal use and should not be used directly or indirectly (e.g. using a serializer or a formatter).

void IXmlSerializable.WriteXml(XmlWriter writer)Sub System.Xml.Serialization.IXmlSerializable.WriteXml(writer As XmlWriter) Implements IXmlSerializable.WriteXml
Parameters
writer
XmlWriter XmlWriter

The XmlWriter stream to which the object is serialized.