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. Used only by the legacy Azure Service Bus transport which is no longer supported.

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, text/json, application/json, or application/json; systemjson. In some cases, it may be useful to use the NServiceBus.Version header to determine how to use the value in this header appropriately.

Although this header mimicks the HTTP Content-Type header the values are case-sensitive. The header value does not behave like HTTP headers where everything after ; is used to order and match the best qualified (application/json) serializer. Adding a suffix like ; systemjson requires all endpoints involved to use this full key (for example: application/json; systemjson).

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

The identifier of the conversation that this message is part of. It enables the tracking of message flows that span more than one message exchange. ConversationId, RelatedTo, OriginatingEndpoint, and ProcessingEndpoint fields allow ServiceInsight to reconstruct the entire message flow.

The first message sent in a new flow is automatically assigned a unique ConversationId that gets 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.

The ConversationId must be assigned manually in cases where NServiceBus can't infer when messages belong to the same conversation. For example, when a CancelOrder message must be part of an existing order conversation, then the Order ID can be used for as the Conversation ID. Manually assigning a ConversationId 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

Starting a new conversation

NServiceBus.RelatedTo

NServiceBus.MessageIntent

NServiceBus.ControlMessage

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.DeliverAt

NServiceBus.OriginatingEndpoint

NServiceBus.OriginatingMachine

NServiceBus.Version

OpenTelemetry-related headers

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

ServiceControl

ServiceControl.RetryTo

ServiceControl.TargetEndpointAddress