| title | summary | reviewed | component | versions | redirects | related | ||||
|---|---|---|---|---|---|---|---|---|---|---|
Message Headers |
List of built-in NServiceBus message headers. |
2023-03-18 |
Core |
[5.0,) |
|
|
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.
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();
}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.
The TimeToBeReceived header controls when a message becomes obsolete and can be discarded. The behavior is transport-dependent.
States what type of body serialization is used. Used only by the legacy Azure Service Bus transport which is no longer supported.
The following headers include information for the receiving endpoint on the message serialization option that was used.
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.
Warning
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).
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.
The following headers are used to enable different messaging interaction patterns, such as Request-Response.
A unique ID for the current message.
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 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.
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:
snippet: override-conversation-id
partial: conversationid
Warning
Attempting to override an existing Conversation ID is not supported and will produce the following error:
Cannot set the NServiceBus.ConversationId header to 'XXXXX' as it cannot override the incoming header value ('2f4076a0-d8de-4297-9d18-a830015dd42a').
Note
Conversation Id is very similar to Correlation Id. Both headers are copied to each new message that an endpoint produces. Whereas Conversation Id is always copied from the incoming message being handled, Correlation Id can come from another source (such as when replying from a saga using ReplyToOriginator(...)).
partial: newconversationid
The MessageId that caused the current message to be sent. Whenever a message is sent or published from inside a message handler, its RelatedTo header is set to the MessageId of the incoming message that was being handled.
Note
For a single request-response interaction Correlation Id and RelatedTo are very similar. Both headers are able to correlate the response message back to the request message. Once a conversation is longer than a single request-response interaction, Correlation Id can be used to correlate a response to the original request. RelatedTo can only correlate a message back to the previous message in the same conversation.
Message intent can have one of the following values:
| 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. |
Indicates that the message is a control message, ie has no body and the intent of the message and any data is transmitted in the message headers.
Downstream message handlers or sagas use this value as the reply queue address when replying or returning a message.
When a message is sent, the headers will be as follows:
snippet: HeaderWriterSend
In the above example, headers are for a Send and hence the MessageIntent header is Send. If the message were published instead, the MessageIntent header would be Publish.
When replying to a message:
- The
MessageIntentisReply. - The
RelatedTowill be the same as the initiatingMessageID. - The
ConversationIdwill be the same as the initiatingConversationId. - The
CorrelationIdwill be the same as the initiatingCorrelationId.
Given an initiating message with the following headers:
snippet: HeaderWriterReplySending
the headers of the reply message will be:
snippet: HeaderWriterReplyReplying
When a message is published the headers will be as follows:
snippet: HeaderWriterPublish
When returning a message instead of replying:
- The Return has the same points as the Reply example above with some additions.
- The
ReturnMessage.ErrorCodecontains the value that was supplied to theBus.Returnmethod.
Given an initiating message with the following headers:
snippet: HeaderWriterReturnSending
the headers of reply message will be:
snippet: HeaderWriterReturnReturning
A header to indicate that the contained control message is requesting that timeouts be cleared for a given saga.
A timestamp that indicates when a timeout should be fired.
The queue name a timeout should be routed back to when it fires.
A header to indicate that this message resulted from a Defer.
When a message is dispatched from within a saga the message will contain the following:
- An
OriginatingSagaIdheader which matches the ID used as the index for the saga data stored in persistence. - An
OriginatingSagaTypewhich is the fully qualified type name of the saga that sent the message.
snippet: HeaderWriterSagaSending
A message reply is performed from a saga will have the following headers:
- The send headers are the same as a normal reply headers with a few additions.
- Since this reply is from a secondary saga then
OriginatingSagaIdandOriginatingSagaTypewill match the second saga. - Since this is a reply to the initial saga then the headers will contain
SagaIdandSagaTypeheaders that match the initial saga.
snippet: HeaderWriterSagaReplying
snippet: HeaderWriterSagaReplyingToOriginator
When requesting a timeout from a saga:
- The
OriginatingSagaId,OriginatingSagaType,SagaIdandSagaTypewill all match the Saga that requested the Timeout. - The
Timeout.RouteExpiredTimeoutToheader contains the queue name for where the callback for the timeout should be sent. - The
Timeout.Expireheader contains the timestamp for when the timeout should fire.
snippet: HeaderWriterSagaTimeout
partial: defer
snippet: HeaderWriterDefer
Headers used to give visibility into "where", "when" and "by whom" of a message. They are used by ServiceControl, ServiceInsight and ServicePulse.
The host details of the endpoint where the message was being processed. This header contains three parts:
$.diagnostics.hostdisplayname$.diagnostics.hostid$.diagnostics.originating.hostid
The timestamp when the message was sent. Used by the Performance Counters.
The timestamp when the message should be delivered. Used for more accurate calculation of critical time.
The endpoint name the message was sent from.
Note
Used for linking messages in ServiceInsight. See NServiceBus.ConversationId
The machine name the message was sent from.
The NServiceBus version number.
These headers are added when OpenTelemetry is enabled for an endpoint, in accordance with the W3C Trace Context specification:
Headers added when a message is audited
The timestamp when the processing of a message ended.
Name of the endpoint where the message was processed.
Note
Used for linking messages in ServiceInsight. See NServiceBus.ConversationId
The machine name of the endpoint where the message was processed.
The timestamp when the processing of this message started.
Given an initiating message with the following headers:
snippet: HeaderWriterAuditSend
when that message fails to be processed, it will be sent to the error queue with the following headers:
snippet: HeaderWriterAuditAudit
Headers used to facilitate retries.
Note
These headers only exist after the first round of immediate reties has finished and are removed before sending a message to the error queue after all allowed retry attempts are exhausted.
The number of delayed retries that have been performed for a message.
A timestamp used by delayed retries to determine if the maximum time for retrying has been reached.
When a message exhausts the configured number of retry attempts and is moved to the error queue by the recoverability component, it will have the following extra headers added to the existing headers.
The queue at which the message processing failed.
The Type.FullName of the Exception. It is obtained by calling Exception.GetType().FullName.
The full type name of the InnerException if it exists. It is obtained by calling Exception.InnerException.GetType().FullName.
The exception help link.
The exception message.
The exception source.
Given an initiating message with the following headers:
snippet: HeaderWriterErrorSending
when that message fails to be processed, it will be sent to the error queue with the following headers:
snippet: HeaderWriterErrorError
Headers when using message property encryption.
Identifies the encryption key used for encryption of the message property fragments.
snippet: HeaderWriterEncryption
snippet: HeaderWriterEncryptionBody
When using the file share data bus, extra headers and serialized message information are necessary to correlate between the information on the queue and the data on the file system.
When using the DataBusProperty, NServiceBus uses that property as a placeholder at serialization time. The serialized value of that property will contain a key. This key maps to a named header. That header then provides the path suffix of where that binary data is stored on disk on the file system.
partial: databuscontenttype
snippet: HeaderWriterDataBusProperty
snippet: HeaderWriterDataBusPropertyBody
When using conventions there is no way to store a correlation value inside the serialized property. Instead, each property has a matching header with the property name used as the header suffix. That header then provides the path suffix of where that binary data is stored on disk on the file system.
snippet: HeaderWriterDataBusConvention
snippet: HeaderWriterDataBusConventionBody
Value: Queue name
When present in a failed message to ServiceControl, ServiceControl will send the message to this queue instead of the queue name value from NServiceBus.FailedQ
This is used by the ServiceControl transport adapter to bridge failed messages between different transports.
Value: Queue name Used by messageging bridge to return the message back to the correct queue if the failed message reach
Value: Queue name
The queue to send an acknowledgement system message back to a specific ServiceControl queue to mark a retried message as processed.
Contains a timestamp in the format yyyy-MM-dd HH:mm:ss:ffffff Z to indicate when a message was succesfully processed.
Part of the control message send back to ServiceControl to signal that a message that was manually retried in ServicePulse/Control and flag as processed succesful.
Contains the NServiceBus.MessageId value of the message that was succesfully processed.
Part of the control message send back to
The presence of any header key that starts with ServiceControl. would indicate its a message that is manually retried.