Table of Contents

Class Message

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

The message object used to communicate and transfer data with Service Bus.

public class Message
Inheritance
Message
Inherited Members
Extension Methods

Remarks

The message structure is discussed in detail in the product documentation.

Constructors

Message()

Creates a new Message

public Message()

Message(byte[])

Creates a new message from the specified payload.

public Message(byte[] body)

Parameters

body byte[]

The payload of the message in bytes

Fields

DeadLetterErrorDescriptionHeader

User property key representing detailed error description, when a message is received from a deadletter subqueue of an entity.

public static string DeadLetterErrorDescriptionHeader

Field Value

string

DeadLetterReasonHeader

User property key representing deadletter reason, when a message is received from a deadletter subqueue of an entity.

public static string DeadLetterReasonHeader

Field Value

string

Properties

Body

Gets or sets the body of the message.

public byte[] Body { get; set; }

Property Value

byte[]

Remarks

The easiest way to create a new message from a string is the following:

message.Body = System.Text.Encoding.UTF8.GetBytes("Message1");

ContentType

Gets or sets the content tpye descriptor.

public string ContentType { get; set; }

Property Value

string

RFC2045 Content-Type descriptor.

Remarks

Optionally describes the payload of the message, with a descriptor following the format of RFC2045, Section 5, for example "application/json".

CorrelationId

Gets or sets the a correlation identifier.

public string CorrelationId { get; set; }

Property Value

string

Correlation identifier.

Remarks

Allows an application to specify a context for the message for the purposes of correlation, for example reflecting the MessageId of a message that is being replied to. See Message Routing and Correlation.

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. This property is read-only.

Remarks

The UTC instant at which the message is marked for removal and no longer available for retrieval from the entity due to expiration. Expiry is controlled by the TimeToLive property and this property is computed from EnqueuedTimeUtc+TimeToLive

Exceptions

InvalidOperationException

If the message has not been received. For example if a new message was created but not yet sent and received.

Label

Gets or sets an application specific label.

public string Label { get; set; }

Property Value

string

The application specific label

Remarks

This property enables the application to indicate the purpose of the message to the receiver in a standardized fashion, similar to an email subject line. The mapped AMQP property is "subject".

MessageId

Gets or sets the MessageId to identify the message.

public string MessageId { get; set; }

Property Value

string

Remarks

The message identifier is an application-defined value that uniquely identifies the message and its payload. The identifier is a free-form string and can reflect a GUID or an identifier derived from the application context. If enabled, the duplicate detection feature identifies and removes second and further submissions of messages with the same MessageId.

PartitionKey

Gets or sets a partition key for sending a message to a partitioned entity.

public string PartitionKey { get; set; }

Property Value

string

The partition key. Maximum length is 128 characters.

Remarks

For partitioned entities, setting this value enables assigning related messages to the same internal partition, so that submission sequence order is correctly recorded. The partition is chosen by a hash function over this value and cannot be chosen directly. For session-aware entities, the SessionId property overrides this value.

ReplyTo

Gets or sets the address of an entity to send replies to.

public string ReplyTo { get; set; }

Property Value

string

The reply entity address.

Remarks

This optional and application-defined value is a standard way to express a reply path to the receiver of the message. When a sender expects a reply, it sets the value to the absolute or relative path of the queue or topic it expects the reply to be sent to. See Message Routing and Correlation.

ReplyToSessionId

Gets or sets a session identifier augmenting the ReplyTo address.

public string ReplyToSessionId { get; set; }

Property Value

string

Session identifier. Maximum length is 128 characters.

Remarks

This value augments the ReplyTo information and specifies which SessionId should be set for the reply when sent to the reply entity. See Message Routing and Correlation

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.

Remarks

Message enqueuing 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.

SessionId

Gets or sets the session identifier for a session-aware entity.

public string SessionId { get; set; }

Property Value

string

The session identifier. Maximum length is 128 characters.

Remarks

For session-aware entities, this application-defined value specifies the session affiliation of the message. Messages with the same session identifier are subject to summary locking and enable exact in-order processing and demultiplexing. For session-unaware entities, this value is ignored. See Message Sessions.

Size

Gets the total size of the message body in bytes.

public long Size { get; }

Property Value

long

SystemProperties

Gets the Message.SystemPropertiesCollection, which is used to store properties that are set by the system.

public Message.SystemPropertiesCollection SystemProperties { get; }

Property Value

Message.SystemPropertiesCollection

TimeToLive

Gets or sets the message’s "time to live" value.

public TimeSpan TimeToLive { get; set; }

Property Value

TimeSpan

The message’s time to live value.

Remarks

This value is the relative duration after which the message expires, starting from the instant the message has been accepted and stored by the broker, as captured in EnqueuedTimeUtc. When not set explicitly, the assumed value is the DefaultTimeToLive for the respective queue or topic. A message-level TimeToLive value cannot be longer than the entity's DefaultTimeToLive setting and it is silently adjusted if it does. See Expiration

To

Gets or sets the "to" address.

public string To { get; set; }

Property Value

string

The "to" address.

Remarks

This property is reserved for future use in routing scenarios and presently ignored by the broker itself. Applications can use this value in rule-driven auto-forward chaining scenarios to indicate the intended logical destination of the message.

UserProperties

Gets the "user properties" bag, which can be used for custom message metadata.

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

Property Value

IDictionary<string, object>

Remarks

Only following value types are supported: byte, sbyte, char, short, ushort, int, uint, long, ulong, float, double, decimal, bool, Guid, string, Uri, DateTime, DateTimeOffset, TimeSpan, Stream, byte[], and IList / IDictionary of supported types

ViaPartitionKey

Gets or sets a partition key for sending a message into an entity via a partitioned transfer queue.

public string ViaPartitionKey { get; set; }

Property Value

string

The partition key. Maximum length is 128 characters.

Remarks

If a message is sent via a transfer queue in the scope of a transaction, this value selects the transfer queue partition: This is functionally equivalent to PartitionKey and ensures that messages are kept together and in order as they are transferred. See Transfers and Send Via.

Methods

Clone()

Clones a message, so that it is possible to send a clone of an already received message as a new message. The system properties of original message are not copied.

public Message Clone()

Returns

Message

A cloned Message.

ToString()

Returns a string that represents the current message.

public override string ToString()

Returns

string

The string representation of the current message.