Message Headers and Properties

This section describes message headers and properties.

Message headers

When sending a message, you can specify the following message properties. If a single message is sent or received, then these properties are contained in the BrokerProperties HTTP header in a JSON-encoded format. If a batch of messages is sent, these properties are part of the JSON-encoded HTTP body. For more information, see Send Message and Send Message Batch.

The following table lists the Microsoft.ServiceBus.Messaging.BrokeredMessage properties. The properties can appear in any order. If a property isn't specified, Service Bus uses the default value for that property. Broker properties other than the ones listed are ignored. The accepted properties are independent of the value of the specified api-version. The api-version specifier isn't required in the HTTP request.

If the SessionId and PartitionKey properties are both set, they must be set to the same value.

One HTTP header named BrokerProperties contains all the BrokeredMessage headers. The properties are JSON-formatted. This makes it easy to extend the BrokeredMessage properties. Also, it aligns to the web programming model by leveraging the web-friendly JSON format. This makes it easy to produce and consume message properties with less string parsing. The following is an example of BrokeredMessage headers:

BrokerProperties:  { “SessionId”: “{27729E1-B37B-4D29-AA0A-E367906C206E}”, “MessageId”: “{701332E1-B37B-4D29-AA0A-E367906C206E}”, “TimeToLive” : 90, “CorrelationId”: “{701332F3-B37B-4D29-AA0A-E367906C206E}”, “SequenceNumber“ : 12345, “DeliveryCount“ : 2, “To“ : "http://contoso.com“, “ReplyTo“ : "http://fabrikam.com“,  "EnqueuedTimeUtc“ : " Sun, 06 Nov 1994 08:49:37 GMT“, "ScheduledEnqueueTimeUtc“ : " Sun, 06 Nov 1994 08:49:37 GMT“}  

The following table illustrates how BrokeredMessage properties are mapped to HTTP headers.

In addition to these properties, you can specify custom properties. If a single message is sent or received, each custom property is placed in its own HTTP header. If a batch of messages is sent, custom properties are part of the JSON-encoded HTTP body. For more information, see Send Message and Send Message Batch.

Notes

• DateTime headers are formatted as defined by RFC2616: https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.3. For example, “Sun, 06 Nov 1994 08:49:37 GMT”.

• BrokerProperties {TimeToLive} is the number of seconds of the TimeSpan (double).

• ExpiresAtUtc doesn't have a corresponding HTTP header because it can be derived from Date and BrokerProperties {TimeToLive}.

• Message headers with a get accessor can only appear in the HTTP response (for example, received message). When these headers are present in the HTTP request (that is, sent message), they're silently ignored. Unrecognized HTTP headers are also silently ignored.

• If the value is malformed, an appropriate HTTP status code is returned to the client.

Message properties

Message properties are user-defined key-value pairs contained in message.Properties. For the SBMP thick client, the values are restricted to byte, sbyte, char, short, ushort, int, uint, long, ulong, float, double, decimal, bool, Guid, string, Uri, DateTime, DateTimeOffset, and TimeSpan.

For REST/HTTP, Uri and DateTimeOffset aren't supported (if they are in the BrokeredMessage, they aren't included in the HTTP headers). GUID types are converted to strings and TimeSpan types are converted to “total seconds.” Due to these conversions, the type fidelity will be lost. Any property name that corresponds to the restricted HTTP header (for example, Connection, Expect, and so on), is also excluded.

Each key-value pair in message.Properties will be mapped to an HTTP header in the following format. prop is the key name, and value is the string representation of the value:

prop_name: value  

The type of value is inferred. If it's surrounded with double quotes, then:

• If the content has the form of an RFC2616 date time, then the broker treats it as a System.DateTime.

• Otherwise, the broker removes the quotes and treats the content as a System.String.

If it isn't surrounded with double quotes, then:

1. If the content is true or false (case-sensitive!), then the broker treats it as a System.Boolean with the corresponding value.

2. If the content can be parsed as an integer, then the broker treats it as a System.Int64.

3. If the content can be parsed as a floating-point number, then the broker treats it as a System.Double.

4. Otherwise, the broker rejects the message.

For example:

product: Windows 7 Ultimate  
price: 299.98  
order-time: Fri, 04 Mar 2011 08:49:37 GMT  

Message body

No conversions are performed between the HTTP request/response body stream and the BrokerMessage.BodyStream. Also, the Content-Type header from the HTTP request is preserved and returned to the message receiver to allow the application to correctly interpret the bytes in the body.

If the message is created with the SBMP thick client without a custom xml object serializer, the content type will default to “application/msbin1”, which is the DataContractBinarySerializer, unless the application explicitly changes it (for example, message.ContectType=”application/mytype”) after the message is created. This content type value is returned to the HTTP consumer. It's the responsibility of the application to decide how to deserialize the bytes in the body.

The WCF Service Bus binding sets the ContentType to the message encoder’s ContentType. For example, if a text message encoder is used, the Content-Type is expected to be “application/soap+xml”.

Message conversion

Conversion between an HTTP request/response and a message is performed at the HTTP messaging runtime provider. The conversion methods are augmented to include the header/properties mapping in the table earlier in this section, and to preserve the content-type of the message.