Message Headers

The headers of a message are similar to HTTP headers and contain metadata about the message being sent over the queueing system. This document describes the headers used by NServiceBus. To learn more about how to use custom headers, see the documentation on manipulating message headers.

Timestamp format

For all timestamp message headers, the format is yyyy-MM-dd HH:mm:ss:ffffff Z where the time is UTC. The helper class DateTimeExtensions supports converting from UTC to wire format and vice versa by using the ToWireFormattedString() and ToUtcDateTime() methods.

const string Format = "yyyy-MM-dd HH:mm:ss:ffffff Z";

public static string ToWireFormattedString(DateTime dateTime)
{
    return dateTime.ToUniversalTime()
        .ToString(Format, CultureInfo.InvariantCulture);
}

public static DateTime ToUtcDateTime(string wireFormattedString)
{
    return DateTime.ParseExact(wireFormattedString, Format, CultureInfo.InvariantCulture)
       .ToUniversalTime();
}

Transport headers

NServiceBus.NonDurableMessage

The NonDurableMessage header controls non-durable messaging persistence behavior of in-flight messages. The behavior is transport specific but the intent is to not store the message durably on disk and only keep it in memory.

NServiceBus.TimeToBeReceived

The TimeToBeReceived header controls when a message becomes obsolete and can be discarded. The behavior is transport-dependent.

NServiceBus.Transport.Encoding

States what type of body serialization is used. Currently only set by Azure Service Bus based the configured value for BrokeredMessageBodyType.

Serialization headers

The following headers include information for the receiving endpoint on the message serialization option that was used.

NServiceBus.ContentType

The type of serialization used for the message, for example text/xml or text/json. In some cases, it may be useful to use the NServiceBus.Version header to determine how to use the value in this header appropriately.

NServiceBus.EnclosedMessageTypes

The fully qualified .NET type name of the enclosed message(s). The receiving endpoint will use this type when deserializing an incoming message. Depending on the versioning strategy the type can be specified in the following ways:

Full type name: Namespace.ClassName.
Assembly qualified name: Namespace.ClassName, AssemblyName, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.

See the message type detection documentation for more details.

Messaging interaction headers

The following headers are used to enable different messaging interaction patterns, such as Request-Response.

NServiceBus.MessageId

A unique ID for the current message.

NServiceBus.CorrelationId

NServiceBus implements the Correlation Identifier pattern by using a Correlation Id header.

Message correlation connects request messages with their corresponding response messages. The Correlation Id of the response message is the Correlation Id of its corresponding request message. Each outgoing message which is sent outside of a message handler will have its Correlation Id set to its Message Id.

An example of Correlation Identifier usage within NServiceBus can be found in callbacks.

Messages sent from a saga using the ReplyToOriginator method will have their Correlation Id set based on the message which caused the saga to be created. See Notifying callers of status for more information about the ReplyToOriginator method.

CorrId

CorrId is an MSMQ specific header semantically identical to NServiceBus.CorrelationId. It is included only for backward compatibility with endpoints running version 3 or older of NServiceBus.

NServiceBus.ConversationId

Identifier of the conversation that this message is part of. It enables the tracking of message flows that span more than one message exchange. Conversation Id and RelatedTo fields allow ServiceInsight to reconstruct the entire message flow.

The first message sent in a new flow is automatically assigned a unique Conversation Id that is then propagated to all the messages that are sent afterward, forming a conversation. Each message sent within a conversation has a RelatedTo value that identifies the message that caused it to be sent.

In certain scenarios, the Conversation Id must be assigned manually in cases where NServiceBus can't infer when messages belong to the same conversation. For example, when a CancelOrder message needs to be part of an existing order conversation, then the Order Id can be used for as the Conversation Id. Manually assigning a Conversation Id can be achieved by overriding the header with a custom value:

Value	Description
Send	Regular point-to-point send. Note that messages sent to the error queue will also have a `Send` intent
Publish	The message is an event that has been published and will be sent to all subscribers.
Subscribe	A control message indicating that the source endpoint would like to subscribe to a specific message.
Unsubscribe	A control message indicating that the source endpoint would like to unsubscribe to a specific message.
Reply	The message has been initiated by doing a Reply or a Return from within a Handler or a Saga.

Timestamp format

Transport headers

NServiceBus.NonDurableMessage

NServiceBus.TimeToBeReceived

NServiceBus.Transport.Encoding

Serialization headers

NServiceBus.ContentType

NServiceBus.EnclosedMessageTypes

Messaging interaction headers

NServiceBus.MessageId

NServiceBus.CorrelationId

CorrId

NServiceBus.ConversationId

NServiceBus.RelatedTo

NServiceBus.MessageIntent

NServiceBus.ReplyToAddress

Send headers

Reply headers

Example reply headers

Publish headers

Return from a handler

Example return headers

Timeout headers

NServiceBus.ClearTimeouts

NServiceBus.Timeout.Expire

NServiceBus.Timeout.RouteExpiredTimeoutTo

NServiceBus.IsDeferredMessage

Saga-related headers

Example "send from saga" headers

Replying to a saga

Example "replying to a saga" headers

Via calling Bus.Reply

Via calling Saga.ReplyToOriginator

Requesting a timeout from a saga

Example timeout headers

Defer a message

Example defer headers

Diagnostic and informational headers

$.diagnostics

NServiceBus.TimeSent

NServiceBus.OriginatingEndpoint

NServiceBus.OriginatingMachine

NServiceBus.Version

Audit headers

NServiceBus.ProcessingEnded

NServiceBus.ProcessingEndpoint

NServiceBus.ProcessingMachine

NServiceBus.ProcessingStarted

Example audit headers

Retries handling headers

NServiceBus.Retries

NServiceBus.Retries.Timestamp

Error forwarding headers

NServiceBus.FailedQ

NServiceBus.ExceptionInfo.ExceptionType

NServiceBus.ExceptionInfo.InnerExceptionType

NServiceBus.ExceptionInfo.HelpLink

NServiceBus.ExceptionInfo.Message

NServiceBus.ExceptionInfo.Source

NServiceBus.ExceptionInfo.StackTrace

Example error headers

Encryption headers

NServiceBus.RijndaelKeyIdentifier

Example headers

Example body

File share data bus headers

Using DataBusProperty

Example headers

Example body

Using conventions

Example headers

Example body

Samples

Related Articles