Table of Contents

Class BrokeredMessage

Namespace
Microsoft.ServiceBus.Messaging
Assembly
Microsoft.ServiceBus.dll

Represents the unit of communication between AppFabric ServiceBus clients.

public sealed class BrokeredMessage : IXmlSerializable, IDisposable
Inheritance
BrokeredMessage
Implements
IXmlSerializable
Inherited Members

Constructors

BrokeredMessage()

Initializes a new instance of the BrokeredMessage class.

public BrokeredMessage()

BrokeredMessage(Stream)

Initializes a new instance of the BrokeredMessage class.

public BrokeredMessage(Stream messageBodyStream)

Parameters

messageBodyStream Stream

The message body stream.

BrokeredMessage(Stream, bool)

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

public BrokeredMessage(Stream messageBodyStream, bool ownsStream)

Parameters

messageBodyStream Stream

The message body stream.

ownsStream bool

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)

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

public BrokeredMessage(object serializableObject)

Parameters

serializableObject object

The serializable object.

BrokeredMessage(object, XmlObjectSerializer)

Initializes a new instance of the BrokeredMessage class from a given object using the provided XmlObjectSerializer.

public BrokeredMessage(object serializableObject, XmlObjectSerializer serializer)

Parameters

serializableObject object

The serializable object.

serializer XmlObjectSerializer

The serializer object.

Properties

ContentType

Gets or sets the type of the content.

public string ContentType { get; set; }

Property Value

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

ObjectDisposedException

Thrown if the message is in disposed state.

CorrelationId

Gets or sets the identifier of the correlation.

public string CorrelationId { get; set; }

Property Value

string

The identifier of the correlation.

Exceptions

ObjectDisposedException

Thrown if the message is in disposed state.

DeliveryCount

Gets the number of deliveries.

public int DeliveryCount { get; }

Property Value

int

The number of deliveries.

Exceptions

ObjectDisposedException

Thrown if the message is in disposed state.

InvalidOperationException

Thrown if the message has not been delivered by ServiceBus.

EnqueuedSequenceNumber

Gets or sets the enqueued sequence number of the message.

public long EnqueuedSequenceNumber { get; }

Property Value

long

The enqueued sequence number of the message.

EnqueuedTimeUtc

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

public DateTime EnqueuedTimeUtc { get; }

Property Value

DateTime

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

Exceptions

ObjectDisposedException

Thrown if the message is in disposed state.

ExpiresAtUtc

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

public DateTime ExpiresAtUtc { get; }

Property Value

DateTime

The message expiration time in UTC.

Exceptions

ObjectDisposedException

Thrown if the message is in disposed state.

InvalidOperationException

If the message has not been delivered by ServerBus.

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; }

Property Value

bool

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

Specifies whether the message has been consumed.

public bool IsBodyConsumed { get; }

Property Value

bool

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

Label

Gets or sets the application specific label.

public string Label { get; set; }

Property Value

string

The application specific label.

Exceptions

ObjectDisposedException

Thrown if the message is in disposed state.

LockToken

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

public Guid LockToken { get; }

Property Value

Guid

The lock token assigned by Service Bus to this message.

Exceptions

ObjectDisposedException

Thrown if the message is in disposed state.

InvalidOperationException

Thrown if the message was not received from the ServiceBus.

LockedUntilUtc

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

public DateTime LockedUntilUtc { get; }

Property Value

DateTime

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

Exceptions

ObjectDisposedException

Thrown if the message is in disposed state.

InvalidOperationException

Thrown if the message was not received from the ServiceBus.

MessageId

Gets or sets the identifier of the message.

public string MessageId { get; set; }

Property Value

string

The identifier of the message.

Exceptions

ObjectDisposedException

Thrown if the message is in disposed state.

ArgumentException

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

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; }

Property Value

string

The partition key for sending a transactional message.

Properties

Gets the application specific message properties.

public IDictionary<string, object> Properties { get; }

Property Value

IDictionary<string, object>

The application specific message properties.

Exceptions

ObjectDisposedException

Thrown if the message is in disposed state.

ReplyTo

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

public string ReplyTo { get; set; }

Property Value

string

The reply to queue address.

Exceptions

ObjectDisposedException

Thrown if the message is in disposed state.

ReplyToSessionId

Gets or sets the session identifier to reply to.

public string ReplyToSessionId { get; set; }

Property Value

string

The session identifier to reply to.

Exceptions

ObjectDisposedException

Thrown if the message is in disposed state.

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; }

Property Value

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

ObjectDisposedException

Thrown if the message is in disposed state.

ArgumentOutOfRangeException

Thrown if the passed in value is DateTime.MaxValue.

SequenceNumber

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

public long SequenceNumber { get; }

Property Value

long

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

Exceptions

ObjectDisposedException

Thrown if the message is in disposed state.

InvalidOperationException

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

SessionId

Gets or sets the identifier of the session.

public string SessionId { get; set; }

Property Value

string

The identifier of the session.

Exceptions

ObjectDisposedException

Thrown if the message is in disposed state.

Size

Gets the size of the message in bytes.

public long Size { get; }

Property Value

long

The message size in bytes.

Exceptions

ObjectDisposedException

Thrown if the message is in disposed state.

State

Gets or sets the state of the message.

public MessageState State { get; }

Property Value

MessageState

The state of the message.

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; }

Property Value

TimeSpan

The message’s time to live value.

Exceptions

ObjectDisposedException

Thrown if the message is in disposed state.

ArgumentOutOfRangeException

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

To

Gets or sets the send to address.

public string To { get; set; }

Property Value

string

The send to address.

Exceptions

ObjectDisposedException

Thrown if the message is in disposed state.

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; }

Property Value

string

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

Methods

Abandon()

Abandons the lock on a peek-locked message.

public void Abandon()

Exceptions

ObjectDisposedException

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

InvalidOperationException

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.

TimeoutException

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.

System.ServiceModel.MessagingCommunicationException

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

ServerBusyException

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

MessagingEntityNotFoundException

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

MessageLockLostException

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

SessionLockLostException

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

UnauthorizedAccessException

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

System.ServiceModel.QuotaExceededException

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

Abandon(IDictionary<string, object>)

Abandons the lock on a peek-locked message.

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

Parameters

propertiesToModify IDictionary<string, object>

The key-value pair collection of properties to modify.

AbandonAsync()

Asynchronously abandons the lock on a peek-locked message.

public Task AbandonAsync()

Returns

Task

The asynchronous result of the operation.

AbandonAsync(IDictionary<string, object>)

Asynchronously abandons the lock on a peek-locked message.

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

Parameters

propertiesToModify IDictionary<string, object>

The key-value pair collection of properties to modify.

Returns

Task

The asynchronous result of the operation.

Clone()

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

public BrokeredMessage Clone()

Returns

BrokeredMessage

The BrokeredMessage that contains the cloned message.

Complete()

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

public void Complete()

Exceptions

ObjectDisposedException

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

InvalidOperationException

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.

System.ServiceModel.MessagingCommunicationException

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

TimeoutException

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.

MessageLockLostException

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.

SessionLockLostException

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.

ServerBusyException

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

MessagingEntityNotFoundException

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

UnauthorizedAccessException

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

System.ServiceModel.QuotaExceededException

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

CompleteAsync()

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

public Task CompleteAsync()

Returns

Task

The asynchronous result of the operation.

DeadLetter()

Moves the message to the dead letter queue.

public void DeadLetter()

Exceptions

ObjectDisposedException

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

InvalidOperationException

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

Moves the message to the dead letter queue.

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

Parameters

propertiesToModify IDictionary<string, object>

The key-value pair collection of properties to modify.

DeadLetter(string, string)

Moves the message to the dead letter queue.

public void DeadLetter(string deadLetterReason, string deadLetterErrorDescription)

Parameters

deadLetterReason string

The reason for deadlettering the message.

deadLetterErrorDescription string

The description information for deadlettering the message.

Exceptions

ObjectDisposedException

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

InvalidOperationException

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.

System.ServiceModel.CommunicationException

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

TimeoutException

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.

MessageLockLostException

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.

SessionLockLostException

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()

Asynchronously moves the message to the dead letter queue.

public Task DeadLetterAsync()

Returns

Task

The asynchronous result of the operation.

DeadLetterAsync(IDictionary<string, object>)

Asynchronously moves the message to the dead letter queue.

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

Parameters

propertiesToModify IDictionary<string, object>

The key-value pair collection of properties to modify.

Returns

Task

The asynchronous result of the operation.

DeadLetterAsync(string, string)

Asynchronously moves the message to the dead letter queue.

public Task DeadLetterAsync(string deadLetterReason, string deadLetterErrorDescription)

Parameters

deadLetterReason string

The reason for deadlettering the message.

deadLetterErrorDescription string

The description information for deadlettering the message.

Returns

Task

The asynchronous result of the operation.

Defer()

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

public void Defer()

Exceptions

ObjectDisposedException

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

InvalidOperationException

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.

System.ServiceModel.MessagingCommunicationException

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

TimeoutException

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.

MessageLockLostException

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.

SessionLockLostException

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.

ServerBusyException

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

MessagingEntityNotFoundException

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

UnauthorizedAccessException

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

System.ServiceModel.QuotaExceededException

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

Defer(IDictionary<string, object>)

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

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

Parameters

propertiesToModify IDictionary<string, object>

The key-value pair collection of properties to modify.

DeferAsync()

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

public Task DeferAsync()

Returns

Task

The asynchronous result of the operation.

DeferAsync(IDictionary<string, object>)

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

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

Parameters

propertiesToModify IDictionary<string, object>

The key-value pair collection of properties to modify.

Returns

Task

The asynchronous result of the operation.

Dispose()

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

public void Dispose()

GetBody<T>()

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

public T GetBody<T>()

Returns

T

The deserialized object or graph.

Type Parameters

T

The type to which the message body will be deserialized.

Exceptions

ObjectDisposedException

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

InvalidOperationException

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)

Deserializes the brokered message body into an object of the specified type by using the supplied System.Runtime.Serialization.XmlObjectSerializer.

public T GetBody<T>(XmlObjectSerializer serializer)

Parameters

serializer XmlObjectSerializer

The serializer object.

Returns

T

The deserialized object or graph.

Type Parameters

T

The generic type parameter.

Exceptions

ObjectDisposedException

Thrown if the message is in disposed state or the message body has already been consumed.

ArgumentNullException

Thrown when invoked with a null serializer object.

InvalidOperationException

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

RenewLock()

Renews the lock on a message.

public void RenewLock()

Exceptions

MessagingException

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

MessagingCommunicationException

You can retry the operation immediately.

MessageLockLostException

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

SessionLockLostException

Thrown instead of MessageLockLostException if the message is from a MessageSession.

RenewLockAsync()

Asynchronously renews the lock on a message.

public Task RenewLockAsync()

Returns

Task

The asynchronous result of the operation.

ToString()

Returns a string that represents the current message.

public override string ToString()

Returns

string

The string representation of the current message.