SALES: 1-800-867-1380

BrokeredMessage

Updated: March 13, 2014

The BrokeredMessage class models the messages exchanged by applications that communicate through queues and topics. The class provides four different public constructors:

  1. The BrokeredMessage() constructor initializes a new instance of the BrokeredMessage class with an empty payload. A BrokeredMessage object exposes a collection of key-value pairs in the Properties, which allows you to define a set of custom properties. It is common for a message to have an empty body because user-defined properties can carry the message payload.

  2. The BrokeredMessage(Object) constructor initializes a new instance of the BrokeredMessage class from a given object by using a DataContractSerializer object with a binary XmlDictionaryWriter object.

  3. BrokeredMessage(Stream, Boolean) constructor initializes a new instance of the BrokeredMessage class using the supplied stream as its body.

  4. Finally, the BrokeredMessage(Object, XmlObjectSerializer) constructor initializes an instance of the BrokeredMessage class from a given object using the provided XmlObjectSerializer object.

The class exposes an interesting set of methods that allow execution of a wide range of actions at the message level:

  1. In the PeekLock receive mode, the Abandon method can release the lock on a peek-locked message. The Complete method commits the receive operation of a message and indicates that the message should be marked as processed and then either deleted or archived. The Defer method indicates that the receiver wants to defer processing for a message. As mentioned before, deferring messages is a convenient way to handle situations where messages are received out of the expected sequence and need to be safely parked while the applications waits for a particular message before proceeding with message processing.

  2. The DeadLetter and DeadLetter(String, String) methods allows an application to explicitly move a message to the dead-letter queue of a queue or a subscription. Take into account that when you create a queue entity using the managing API or the Windows Azure Management Portal, you can configure it to automatically move expired messages to the dead-letter queue. In the same way, you can configure a subscription to move expired messages and messages to its dead-letter queue if they fail filter evaluation.

The BrokeredMessage class exposes a wide range of properties:

 

Property

Description

ContentType

Specifies the type of the content.

MessageId

Indicates the identifier of the message.

CorrelationId

Implement a request-reply message exchange pattern in which the client application uses the MessageId property of an outgoing request message and the CorrelationId property of an incoming response message to correlate the two messages. We will see an implementation of this technique later in this article.

SessionId

Sets or gets the session identifier for a message. A competing consumer scenario where multiple worker processes receive messages from the same session-enabled queue or subscription guarantees that messages sharing the same SessionId are received by the same consumer. In this context, when a client application sends a flow of request messages to a server application using a session-enabled queue or topic and waits for the correlated response messages on a separate session-enabled queue or a subscription, the client application can assign the receive session’s ID to the ReplyToSessionId property of outgoing messages. This property value gives the server application the value to assign to the SessionId property of response messages.

ReplyTo

Gets or sets the address of the queue to reply to. In an asynchronous request-reply scenario a client application can send a request message to a server application through a Service Bus queue or topic and wait for a response message. In this scenario, by convention the client application can use the ReplyTo property of the request message to indicate to the server application the address of the queue or topic to send the response to. We will see an application of this technique when I introduce the second test case where an orchestration reads the ReplyTo address from a context property of the request message and assign its value to the Address property of a dynamic send port to return the response message to the expected queue or topic.

Label

Gets or sets an application specific label.

SequenceNumber

Returns the unique number that the Service Bus assigns to a message. Use this property to retrieve a deferred message from a queue or a subscription.

TimeToLive

Allows you to set or get the message’s time-to-live value. The Service Bus does not enforce a maximum lifetime for messages waiting to be processed in a queue or a subscription. Nevertheless, you can define a default time to live for messages when you create a queue, topic, or subscription, or you can explicitly define an expiration timeout at the message level using the TimeToLive property.

DeliveryCount

Returns the number of message deliveries.

Properties

A collection that allows you to define application specific message properties. This collection is probably the most important feature of a BrokeredMessage entity because user-defined properties can be used for the following:

  1. Carry the payload of a message. In this context, the body of the message could be empty.

  2. Define application specific properties that can be used by a worker process to decide how to process the current message.

  3. Specify filter and action expressions that can be used to define routing and data enrichment rules at a subscription level

If you are familiar with context properties for a BizTalk message, it is helpful to think of the user-defined properties contained in the BrokeredMessageProperties collection as the context properties of a BizTalk message. In fact, these properties can carry a piece of information or even the entire message payload. If you are using topics and subscriptions, these properties can route the message to the proper destination. Hence, in a scenario where a third party system exchanges messages with a BizTalk application through the Service Bus, it’s very important to translate the application specific properties carried by a BrokeredMessage object to and from the context properties of a BizTalk message. In the article and in the companion code I’ll show you how to achieve this result.

WarningWarning
As indicated in Windows Azure AppFabric Service Bus Quotas, the maximum size for each property is 32K. Cumulative size of all properties cannot exceed 64K. This applies to the entire header of the BrokeredMessage, which has both user properties as well as system properties (such as SequenceNumber, Label, MessageId, and so on). The space occupied by properties counts towards the overall size of the message and its maximum size of 256K. If an application exceeds any of the limits mentioned above, a SerializationException exception is generated, so you should expect to handle this error condition.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft