Message Headers

Component: NServiceBus
NuGet Package NServiceBus (5.x)

The headers in a message contain information that is used by the messaging infrastructure to help with the message delivery. Message headers are very similar, in both implementation and usage, to HTTP headers. To learn more about how to use custom headers, see 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();
}

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.
In integration scenarios, this header can be safely omitted if the endpoint uses XmlSerialization and the root node happens to be the message type.

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 that is sent in a new flow is automatically assigned a unique Conversation Id that is then propagated to all the messages that are subsequently sent, thus forming a conversation. Each message that is sent within a conversation also has a RelatedTo value that identifies the originating message that caused it to be sent.

In certain scenarios Conversation Id has to be assigned manually, because NServiceBus can't infer that messages are correlated. For example, when a CancelOrder message needs to become part of an existing order conversation, then the Order Id can be used for correlating messages. This can be achieved by overriding the header with a custom value:

Bus.OutgoingHeaders[Headers.ConversationId] = "MyCustomConversationId/" + System.Guid.NewGuid();

Note that attempting to override an existing Conversation Id 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').
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(...)).

NServiceBus.RelatedTo

The MessageId that caused the current message to be sent. Whenever a message is sent or published from inside a message handler, it's RelatedTo header is set to the MessageId of the incoming message that was being handled.

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.

NServiceBus.MessageIntent

Message intent can have one of the following values:

ValueDescription
SendRegular point-to-point send. Note that messages sent to the error queue will also have a Send intent
PublishThe message is an event that has been published and will be sent to all subscribers.
SubscribeA control message indicating that the source endpoint would like to subscribe to a specific message.
UnsubscribeA control message indicating that the source endpoint would like to unsubscribe to a specific message.
ReplyThe message has been initiated by doing a Reply or a Return from within a Handler or a Saga.

NServiceBus.ReplyToAddress

Downstream message handlers or sagas use this value as the reply queue address when replying or returning a message.

Send headers

When a message is sent, the headers will be as follows:

$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = 554380dd342ba9aa0ca1926e4510b1be
$.diagnostics.originating.hostid = 554380dd342ba9aa0ca1926e4510b1be
CorrId = 67b0b9cd-60fc-4da9-8b7c-a65e00fa0afd\0
NServiceBus.ContentType = text/xml
NServiceBus.ConversationId = 19b00469-c665-494a-8ef5-a65e00fa0afd
NServiceBus.CorrelationId = 67b0b9cd-60fc-4da9-8b7c-a65e00fa0afd
NServiceBus.EnclosedMessageTypes = Core5.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 67b0b9cd-60fc-4da9-8b7c-a65e00fa0afd
NServiceBus.MessageIntent = Send
NServiceBus.OriginatingEndpoint = HeaderWriterSendV5
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterSendV5@MACHINENAME
NServiceBus.TimeSent = 2016-08-10 05:10:22:706849 Z
NServiceBus.Version = 5.2.14
WinIdName = MACHINENAME\simon

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.

Reply headers

When replying to a message:

  • The MessageIntent is Reply.
  • The RelatedTo will be the same as the initiating MessageID.
  • The ConversationId will be the same as the initiating ConversationId.
  • The CorrelationId will be same as the initiating CorrelationId.

Example reply headers

Given an initiating message with the following headers:

$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = 554380dd342ba9aa0ca1926e4510b1be
$.diagnostics.originating.hostid = 554380dd342ba9aa0ca1926e4510b1be
CorrId = ff4814c0-f563-49bd-802c-a65e00fa03bf\0
NServiceBus.ContentType = text/xml
NServiceBus.ConversationId = 6f4031de-f99b-4cbf-86d9-a65e00fa03bf
NServiceBus.CorrelationId = ff4814c0-f563-49bd-802c-a65e00fa03bf
NServiceBus.EnclosedMessageTypes = Core5.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = ff4814c0-f563-49bd-802c-a65e00fa03bf
NServiceBus.MessageIntent = Send
NServiceBus.OriginatingEndpoint = HeaderWriterReplyV5
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterReplyV5@MACHINENAME
NServiceBus.TimeSent = 2016-08-10 05:10:16:526996 Z
NServiceBus.Version = 5.2.14
WinIdName = MACHINENAME\simon

the headers of the reply message will be:

$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = 554380dd342ba9aa0ca1926e4510b1be
$.diagnostics.originating.hostid = 554380dd342ba9aa0ca1926e4510b1be
CorrId = ff4814c0-f563-49bd-802c-a65e00fa03bf\0
NServiceBus.ContentType = text/xml
NServiceBus.ConversationId = 6f4031de-f99b-4cbf-86d9-a65e00fa03bf
NServiceBus.CorrelationId = ff4814c0-f563-49bd-802c-a65e00fa03bf
NServiceBus.EnclosedMessageTypes = Core5.Headers.Writers.MyNamespace.MessageToReply, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 975d0b0b-5e67-45ec-84c9-a65e00fa03c3
NServiceBus.MessageIntent = Reply
NServiceBus.OriginatingEndpoint = HeaderWriterReplyV5
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.RelatedTo = ff4814c0-f563-49bd-802c-a65e00fa03bf
NServiceBus.ReplyToAddress = HeaderWriterReplyV5@MACHINENAME
NServiceBus.TimeSent = 2016-08-10 05:10:16:539651 Z
NServiceBus.Version = 5.2.14
WinIdName = MACHINENAME\simon

Publish headers

When a message is published the headers will be as follows:

$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = 554380dd342ba9aa0ca1926e4510b1be
$.diagnostics.originating.hostid = 554380dd342ba9aa0ca1926e4510b1be
CorrId = a7c8386f-ae7c-4083-b8e7-a65e00fa0174\0
NServiceBus.ContentType = text/xml
NServiceBus.ConversationId = a7047f88-8cf3-403a-8234-a65e00fa0174
NServiceBus.CorrelationId = 95602932-72a2-41ed-8a38-a65e00fa0176
NServiceBus.EnclosedMessageTypes = Core5.Headers.Writers.MyNamespace.MessageToPublish, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = a7c8386f-ae7c-4083-b8e7-a65e00fa0174
NServiceBus.MessageIntent = Publish
NServiceBus.OriginatingEndpoint = HeaderWriterPublishV5
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterPublishV5@MACHINENAME
NServiceBus.TimeSent = 2016-08-10 05:10:14:568555 Z
NServiceBus.Version = 5.2.14
WinIdName = MACHINENAME\simon

Return from a handler

When returning a message instead of replying:

  • The Return has the same points as the Reply example above with some additions.
  • The ReturnMessage.ErrorCode contains the value that was supplied to the Bus.Return method.

Example return headers

Given an initiating message with the following headers:

$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = 554380dd342ba9aa0ca1926e4510b1be
$.diagnostics.originating.hostid = 554380dd342ba9aa0ca1926e4510b1be
CorrId = 4b55f0ad-2411-40fb-a437-a65e00fa062d\0
NServiceBus.ContentType = text/xml
NServiceBus.ConversationId = 0a588ff1-150c-4772-977e-a65e00fa062d
NServiceBus.CorrelationId = 4b55f0ad-2411-40fb-a437-a65e00fa062d
NServiceBus.EnclosedMessageTypes = Core5.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 4b55f0ad-2411-40fb-a437-a65e00fa062d
NServiceBus.MessageIntent = Send
NServiceBus.OriginatingEndpoint = HeaderWriterReturnV5
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterReturnV5@MACHINENAME
NServiceBus.TimeSent = 2016-08-10 05:10:18:598690 Z
NServiceBus.Version = 5.2.14
WinIdName = MACHINENAME\simon

the headers of reply message will be:

$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = 554380dd342ba9aa0ca1926e4510b1be
$.diagnostics.originating.hostid = 554380dd342ba9aa0ca1926e4510b1be
CorrId = 4b55f0ad-2411-40fb-a437-a65e00fa062d\0
NServiceBus.ControlMessage = True
NServiceBus.ConversationId = 0a588ff1-150c-4772-977e-a65e00fa062d
NServiceBus.CorrelationId = 4b55f0ad-2411-40fb-a437-a65e00fa062d
NServiceBus.MessageId = 03491d44-0e98-4aba-8875-a65e00fa0631
NServiceBus.MessageIntent = Reply
NServiceBus.OriginatingEndpoint = HeaderWriterReturnV5
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.RelatedTo = 4b55f0ad-2411-40fb-a437-a65e00fa062d
NServiceBus.ReplyToAddress = HeaderWriterReturnV5@MACHINENAME
NServiceBus.ReturnMessage.ErrorCode = 100
NServiceBus.TimeSent = 2016-08-10 05:10:18:613728 Z
NServiceBus.Version = 5.2.14
WinIdName = MACHINENAME\simon

Timeout headers

NServiceBus.ClearTimeouts

A marker header to indicate that the contained control message is requesting that timeouts be cleared for a given saga.

NServiceBus.Timeout.Expire

A timestamp that indicates when a timeout should be fired.

NServiceBus.Timeout.RouteExpiredTimeoutTo

The queue name a timeout should be routed back to when it fires.

NServiceBus.IsDeferredMessage

A marker header to indicate that this message resulted from a Defer.

Saga-related headers

When a message is dispatched from within a saga the message will contain the following:

  • An OriginatingSagaId header which matches the ID used as the index for the saga data stored in persistence.
  • An OriginatingSagaType which is the fully qualified type name of the saga that sent the message.

Example "send from saga" headers

$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = 554380dd342ba9aa0ca1926e4510b1be
$.diagnostics.originating.hostid = 554380dd342ba9aa0ca1926e4510b1be
CorrId = ffe827bd-b832-4a57-a829-a65e00fa0894\0
NServiceBus.ContentType = text/xml
NServiceBus.ConversationId = b2f47f0c-bca1-4d37-9bc0-a65e00fa0890
NServiceBus.CorrelationId = ffe827bd-b832-4a57-a829-a65e00fa0894
NServiceBus.EnclosedMessageTypes = Core5.Headers.Writers.MyNamespace.SendFromSagaMessage, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = ffe827bd-b832-4a57-a829-a65e00fa0894
NServiceBus.MessageIntent = Send
NServiceBus.OriginatingEndpoint = HeaderWriterSagaV5
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.OriginatingSagaId = 74736c19-213d-4f20-bcb3-a65e00fa0894
NServiceBus.OriginatingSagaType = Core5.Headers.Writers.MyNamespace.Saga1, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.RelatedTo = f057a57b-146c-4f6f-92de-a65e00fa0890
NServiceBus.ReplyToAddress = HeaderWriterSagaV5@MACHINENAME
NServiceBus.TimeSent = 2016-08-10 05:10:20:650705 Z
NServiceBus.Version = 5.2.14
WinIdName = MACHINENAME\simon

Replying to a saga

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 OriginatingSagaId and OriginatingSagaType will match the second saga.
  • Since this is a reply to a the initial saga then the headers will contain SagaId and SagaType headers that match the initial saga.

Example "replying to a saga" headers

Via calling Bus.Reply

$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = 554380dd342ba9aa0ca1926e4510b1be
$.diagnostics.originating.hostid = 554380dd342ba9aa0ca1926e4510b1be
CorrId = ffe827bd-b832-4a57-a829-a65e00fa0894\0
NServiceBus.ContentType = text/xml
NServiceBus.ConversationId = b2f47f0c-bca1-4d37-9bc0-a65e00fa0890
NServiceBus.CorrelationId = ffe827bd-b832-4a57-a829-a65e00fa0894
NServiceBus.EnclosedMessageTypes = Core5.Headers.Writers.MyNamespace.ReplyFromSagaMessage, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = fed448e9-db7d-4f34-a0c7-a65e00fa08cc
NServiceBus.MessageIntent = Reply
NServiceBus.OriginatingEndpoint = HeaderWriterSagaV5
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.OriginatingSagaId = a68d0bef-5a6e-483e-8ef6-a65e00fa08cc
NServiceBus.OriginatingSagaType = Core5.Headers.Writers.MyNamespace.Saga2, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.RelatedTo = ffe827bd-b832-4a57-a829-a65e00fa0894
NServiceBus.ReplyToAddress = HeaderWriterSagaV5@MACHINENAME
NServiceBus.SagaId = 74736c19-213d-4f20-bcb3-a65e00fa0894
NServiceBus.SagaType = Core5.Headers.Writers.MyNamespace.Saga1, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.TimeSent = 2016-08-10 05:10:20:837856 Z
NServiceBus.Version = 5.2.14
WinIdName = MACHINENAME\simon

Via calling Saga.ReplyToOriginator

$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = 554380dd342ba9aa0ca1926e4510b1be
$.diagnostics.originating.hostid = 554380dd342ba9aa0ca1926e4510b1be
CorrId = ffe827bd-b832-4a57-a829-a65e00fa0894\0
NServiceBus.ContentType = text/xml
NServiceBus.ConversationId = b2f47f0c-bca1-4d37-9bc0-a65e00fa0890
NServiceBus.CorrelationId = ffe827bd-b832-4a57-a829-a65e00fa0894
NServiceBus.EnclosedMessageTypes = Core5.Headers.Writers.MyNamespace.ReplyToOriginatorFromSagaMessage, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 38202cfa-8db4-4a78-b4a4-a65e00fa08cd
NServiceBus.MessageIntent = Reply
NServiceBus.OriginatingEndpoint = HeaderWriterSagaV5
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.OriginatingSagaId = a68d0bef-5a6e-483e-8ef6-a65e00fa08cc
NServiceBus.OriginatingSagaType = Core5.Headers.Writers.MyNamespace.Saga2, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.RelatedTo = ffe827bd-b832-4a57-a829-a65e00fa0894
NServiceBus.ReplyToAddress = HeaderWriterSagaV5@MACHINENAME
NServiceBus.TimeSent = 2016-08-10 05:10:20:839861 Z
NServiceBus.Version = 5.2.14
WinIdName = MACHINENAME\simon

Requesting a timeout from a saga

When requesting a timeout from a saga:

  • The OriginatingSagaId, OriginatingSagaType, SagaId and SagaType will all match the Saga that requested the Timeout.
  • The Timeout.RouteExpiredTimeoutTo header contains the queue name for where the callback for the timeout should be sent.
  • The Timeout.Expire header contains the timestamp for when the timeout should fire.

Example timeout headers

$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = 554380dd342ba9aa0ca1926e4510b1be
$.diagnostics.originating.hostid = 554380dd342ba9aa0ca1926e4510b1be
CorrId = ea03dd21-0f8a-45ba-97fe-a65e00fa08ce\0
NServiceBus.ContentType = text/xml
NServiceBus.ConversationId = b2f47f0c-bca1-4d37-9bc0-a65e00fa0890
NServiceBus.CorrelationId = ea03dd21-0f8a-45ba-97fe-a65e00fa08ce
NServiceBus.EnclosedMessageTypes = Core5.Headers.Writers.MyNamespace.TimeoutFromSaga, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.IsDeferredMessage = True
NServiceBus.IsSagaTimeoutMessage = True
NServiceBus.MessageId = ea03dd21-0f8a-45ba-97fe-a65e00fa08ce
NServiceBus.MessageIntent = Send
NServiceBus.OriginatingEndpoint = HeaderWriterSagaV5
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.OriginatingSagaId = a68d0bef-5a6e-483e-8ef6-a65e00fa08cc
NServiceBus.OriginatingSagaType = Core5.Headers.Writers.MyNamespace.Saga2, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.RelatedTo = ffe827bd-b832-4a57-a829-a65e00fa0894
NServiceBus.RelatedToTimeoutId = 
NServiceBus.ReplyToAddress = HeaderWriterSagaV5@MACHINENAME
NServiceBus.SagaId = a68d0bef-5a6e-483e-8ef6-a65e00fa08cc
NServiceBus.SagaType = Core5.Headers.Writers.MyNamespace.Saga2, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.Timeout.Expire = 2016-08-10 05:10:20:842366 Z
NServiceBus.Timeout.RouteExpiredTimeoutTo = HeaderWriterSagaV5@MACHINENAME
NServiceBus.TimeSent = 2016-08-10 05:10:20:881751 Z
NServiceBus.Version = 5.2.14
WinIdName = MACHINENAME\simon

Defer a message

When deferring, the message will have similar header to a Send with a few differences:

  • The message will have IsDeferredMessage with the value of true.
  • Since the defer feature uses the timeouts feature the timeout headers will exist.
  • The Timeout.RouteExpiredTimeoutTo header contains the queue name for where the callback for the timeout should be sent.
  • The Timeout.Expire header contains the timestamp for when the timeout should fire.

Example defer headers

$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = 554380dd342ba9aa0ca1926e4510b1be
$.diagnostics.originating.hostid = 554380dd342ba9aa0ca1926e4510b1be
CorrId = f9cdf6e6-9e12-4cd0-9f7a-a65e00f9f717\0
NServiceBus.ContentType = text/xml
NServiceBus.ConversationId = b9799ce0-07f7-49fb-97bf-a65e00f9f717
NServiceBus.CorrelationId = f9cdf6e6-9e12-4cd0-9f7a-a65e00f9f717
NServiceBus.EnclosedMessageTypes = Core5.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.IsDeferredMessage = True
NServiceBus.MessageId = f9cdf6e6-9e12-4cd0-9f7a-a65e00f9f717
NServiceBus.MessageIntent = Send
NServiceBus.OriginatingEndpoint = HeaderWriterDeferV5
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.RelatedToTimeoutId = 
NServiceBus.ReplyToAddress = HeaderWriterDeferV5@MACHINENAME
NServiceBus.Timeout.Expire = 2016-08-10 05:10:05:738966 Z
NServiceBus.Timeout.RouteExpiredTimeoutTo = HeaderWriterDeferV5@MACHINENAME
NServiceBus.TimeSent = 2016-08-10 05:10:05:737990 Z
NServiceBus.Version = 5.2.14
WinIdName = MACHINENAME\simon

Diagnostic and informational headers

Headers used to give visibility into "where", "when" and "by whom" of a message. They are used by ServiceControl, ServiceInsight and ServicePulse.

$.diagnostics

The host details of the endpoint where the message was being processed. This header contains three parts:

  • $.diagnostics.hostdisplayname
  • $.diagnostics.hostid
  • $.diagnostics.originating.hostid

NServiceBus.TimeSent

The timestamp when the message was sent. Used by the Performance Counters.

NServiceBus.OriginatingEndpoint

The endpoint name the message was sent from.

NServiceBus.OriginatingMachine

The machine name the message was sent from.

NServiceBus.Version

The NServiceBus version number.

Audit headers

Headers added when a message is audited

NServiceBus.ProcessingEnded

The timestamp when processing of a message ended.

NServiceBus.ProcessingEndpoint

Name of the endpoint where the message was processed.

NServiceBus.ProcessingMachine

The machine name of the endpoint where the message was processed.

NServiceBus.ProcessingStarted

The timestamp when the processing of this message started.

Example audit headers

Given an initiating message with the following headers:

$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = 554380dd342ba9aa0ca1926e4510b1be
$.diagnostics.originating.hostid = 554380dd342ba9aa0ca1926e4510b1be
CorrId = 43a2adc2-af44-44b5-8603-a65e00f9ee8c\0
NServiceBus.ContentType = text/xml
NServiceBus.ConversationId = 7453d436-3a2c-4514-81e1-a65e00f9ee8f
NServiceBus.CorrelationId = 43a2adc2-af44-44b5-8603-a65e00f9ee8c
NServiceBus.EnclosedMessageTypes = Core5.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 43a2adc2-af44-44b5-8603-a65e00f9ee8c
NServiceBus.MessageIntent = Send
NServiceBus.OriginatingEndpoint = HeaderWriterAuditV5
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterAuditV5@MACHINENAME
NServiceBus.TimeSent = 2016-08-10 05:09:58:436532 Z
NServiceBus.Version = 5.2.14
WinIdName = MACHINENAME\simon

when that message fails to be processed, it will be sent to the error queue with the following headers:

$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = 554380dd342ba9aa0ca1926e4510b1be
$.diagnostics.license.expired = false
$.diagnostics.originating.hostid = 554380dd342ba9aa0ca1926e4510b1be
CorrId = 43a2adc2-af44-44b5-8603-a65e00f9ee8c\0
NServiceBus.ContentType = text/xml
NServiceBus.ConversationId = 7453d436-3a2c-4514-81e1-a65e00f9ee8f
NServiceBus.CorrelationId = 43a2adc2-af44-44b5-8603-a65e00f9ee8c
NServiceBus.EnclosedMessageTypes = Core5.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 43a2adc2-af44-44b5-8603-a65e00f9ee8c
NServiceBus.MessageIntent = Send
NServiceBus.OriginatingAddress = HeaderWriterAuditV5@MACHINENAME
NServiceBus.OriginatingEndpoint = HeaderWriterAuditV5
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ProcessingEnded = 2016-08-10 05:10:00:188696 Z
NServiceBus.ProcessingEndpoint = HeaderWriterAuditV5
NServiceBus.ProcessingMachine = MACHINENAME
NServiceBus.ProcessingStarted = 2016-08-10 05:09:59:809656 Z
NServiceBus.ReplyToAddress = HeaderWriterAuditV5@MACHINENAME
NServiceBus.TimeSent = 2016-08-10 05:09:58:436532 Z
NServiceBus.Version = 5.2.14
WinIdName = MACHINENAME\simon

Retries handling headers

Headers used to facilitate retries.

These headers will only exist after the initial retry has occurred.

NServiceBus.FailedQ

The queue at which the message processing failed.

NServiceBus.FLRetries

The number of immediate retries that have been performed for a message.

NServiceBus.Retries

The number of delayed retries that have been performed for a message.

NServiceBus.Retries.Timestamp

A timestamp used by delayed retries to determine if the maximum time for retrying has been reached.

Error forwarding headers

When a message is handled by recoverability, it will have the following extra headers added to the existing headers. If retries occurred, then those messages will be included with the exception of NServiceBus.Retries, which is removed.

NServiceBus.ExceptionInfo.ExceptionType

The Type.FullName of the Exception. It is obtained by calling Exception.GetType().FullName.

NServiceBus.ExceptionInfo.InnerExceptionType

The full type name of the InnerException if it exists. It is obtained by calling Exception.InnerException.GetType().FullName.

NServiceBus.ExceptionInfo.HelpLink

The exception help link.

NServiceBus.ExceptionInfo.Message

The exception message.

NServiceBus.ExceptionInfo.Source

The exception source.

NServiceBus.ExceptionInfo.StackTrace

The exception stack trace.

Example error headers

Given an initiating message with the following headers:

$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = 554380dd342ba9aa0ca1926e4510b1be
$.diagnostics.originating.hostid = 554380dd342ba9aa0ca1926e4510b1be
CorrId = 10cd8026-e282-42e6-b6c8-a65e00f9fba7\0
NServiceBus.ContentType = text/xml
NServiceBus.ConversationId = 322b989f-33ec-4b45-ba79-a65e00f9fba7
NServiceBus.CorrelationId = 10cd8026-e282-42e6-b6c8-a65e00f9fba7
NServiceBus.EnclosedMessageTypes = Core5.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 10cd8026-e282-42e6-b6c8-a65e00f9fba7
NServiceBus.MessageIntent = Send
NServiceBus.OriginatingEndpoint = HeaderWriterErrorV5
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterErrorV5@MACHINENAME
NServiceBus.TimeSent = 2016-08-10 05:10:09:619923 Z
NServiceBus.Version = 5.2.14
WinIdName = MACHINENAME\simon

when that message fails to be processed, it will be sent to the error queue with the following headers:

$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = 554380dd342ba9aa0ca1926e4510b1be
$.diagnostics.originating.hostid = 554380dd342ba9aa0ca1926e4510b1be
CorrId = 10cd8026-e282-42e6-b6c8-a65e00f9fba7\0
NServiceBus.ContentType = text/xml
NServiceBus.ConversationId = 322b989f-33ec-4b45-ba79-a65e00f9fba7
NServiceBus.CorrelationId = 10cd8026-e282-42e6-b6c8-a65e00f9fba7
NServiceBus.EnclosedMessageTypes = Core5.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.ExceptionInfo.ExceptionType = System.Exception
NServiceBus.ExceptionInfo.HelpLink = 
NServiceBus.ExceptionInfo.Message = The exception message from the handler.
NServiceBus.ExceptionInfo.Source = Core5
NServiceBus.ExceptionInfo.StackTrace = System.Exception: The exception message from the handler.
      at Core5.Headers.Writers.HeaderWriterError.MessageHandler.Handle(MessageToSend message)
      at NServiceBus.Unicast.MessageHandlerRegistry.Invoke(Object handler, Object message, Dictionary2 dictionary)
      at NServiceBus.InvokeHandlersBehavior.Invoke(IncomingContext context, Action next)
      at NServiceBus.SetCurrentMessageBeingHandledBehavior.Invoke(IncomingContext context, Action next)
      at NServiceBus.LoadHandlersBehavior.Invoke(IncomingContext context, Action next)
      at NServiceBus.ExecuteLogicalMessagesBehavior.Invoke(IncomingContext context, Action next)
      at NServiceBus.UnitOfWorkBehavior.Invoke(IncomingContext context, Action next)
      at NServiceBus.ChildContainerBehavior.Invoke(IncomingContext context, Action next)
      at NServiceBus.ProcessingStatisticsBehavior.Invoke(IncomingContext context, Action next)
      at NServiceBus.BehaviorChain1.Invoke()
      at NServiceBus.Pipeline.PipelineExecutor.Execute[T](BehaviorChain1 pipelineAction, T context)
      at NServiceBus.Unicast.Transport.TransportReceiver.OnTransportMessageReceived(TransportMessage msg)
      at NServiceBus.Unicast.Transport.TransportReceiver.ProcessMessage(TransportMessage message)
      at NServiceBus.Unicast.Transport.TransportReceiver.TryProcess(TransportMessage message)
      at NServiceBus.Transports.Msmq.MsmqDequeueStrategy.Action()
NServiceBus.FailedQ = HeaderWriterErrorV5@MACHINENAME
NServiceBus.MessageId = 10cd8026-e282-42e6-b6c8-a65e00f9fba7
NServiceBus.MessageIntent = Send
NServiceBus.OriginatingEndpoint = HeaderWriterErrorV5
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterErrorV5@MACHINENAME
NServiceBus.TimeOfFailure = 2016-08-10 05:10:09:657468 Z
NServiceBus.TimeSent = 2016-08-10 05:10:09:619923 Z
NServiceBus.Version = 5.2.14
WinIdName = MACHINENAME\simon

Encryption headers

Headers when using message property encryption.

NServiceBus.RijndaelKeyIdentifier

Identifies the encryption key used for encryption of the message property fragments.

Example headers

$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = 554380dd342ba9aa0ca1926e4510b1be
$.diagnostics.originating.hostid = 554380dd342ba9aa0ca1926e4510b1be
CorrId = 04d0c2ea-8319-47e6-819d-a65e00f9f985\0
NServiceBus.ContentType = text/xml
NServiceBus.ConversationId = ce78791c-0847-481a-898b-a65e00f9f985
NServiceBus.CorrelationId = 04d0c2ea-8319-47e6-819d-a65e00f9f985
NServiceBus.EnclosedMessageTypes = Core5.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 04d0c2ea-8319-47e6-819d-a65e00f9f985
NServiceBus.MessageIntent = Send
NServiceBus.OriginatingEndpoint = HeaderWriterEncryptionV5
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterEncryptionV5@MACHINENAME
NServiceBus.RijndaelKeyIdentifier = key1
NServiceBus.TimeSent = 2016-08-10 05:10:07:799391 Z
NServiceBus.Version = 5.2.14
WinIdName = MACHINENAME\simon

Example body

<?xml version="1.0" ?>
<MessageToSend xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://tempuri.net/Core5.Headers.Writers">
<EncryptedProperty1>Q3yVC7MRgxSdB0pzXYGUxQ==@fH1+XGJRR0fV53OcFGb9AA==</EncryptedProperty1>
<EncryptedProperty2>8P/vdnIl9SBuKdpiAKKlcA==@oABjVvQ0eMj7v9mpU8L7pg==</EncryptedProperty2>
</MessageToSend>

FileShare DataBus headers

When using the FileShare DataBus, extra headers and serialized message information are necessary to correlate between the information on the queue and the data on the file system.

Using DataBusProperty

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.

Example headers

$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = 554380dd342ba9aa0ca1926e4510b1be
$.diagnostics.originating.hostid = 554380dd342ba9aa0ca1926e4510b1be
CorrId = f34b279b-e7bb-48ff-a638-a65e00f9f4a0\0
NServiceBus.ContentType = text/xml
NServiceBus.ConversationId = 3bac1ae2-4c30-4a55-9085-a65e00f9f4a1
NServiceBus.CorrelationId = f34b279b-e7bb-48ff-a638-a65e00f9f4a0
NServiceBus.DataBus.2016-08-10_15\d25ddb24-f0ea-40ae-bf1a-54cf6874bea4 = 2016-08-10_15\d25ddb24-f0ea-40ae-bf1a-54cf6874bea4
NServiceBus.DataBus.2016-08-10_15\d97c5639-09cf-4f78-8869-c5b184d09dcf = 2016-08-10_15\d97c5639-09cf-4f78-8869-c5b184d09dcf
NServiceBus.EnclosedMessageTypes = Core5.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = f34b279b-e7bb-48ff-a638-a65e00f9f4a0
NServiceBus.MessageIntent = Send
NServiceBus.OriginatingEndpoint = HeaderWriterDataBusPropertyV5
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterDataBusPropertyV5@MACHINENAME
NServiceBus.TimeSent = 2016-08-10 05:10:03:621685 Z
NServiceBus.Version = 5.2.14
WinIdName = MACHINENAME\simon

Example body

<?xml version="1.0" ?>
<MessageToSend xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://tempuri.net/Core5.Headers.Writers">
<LargeProperty1>
<Key>2016-08-10_15\d25ddb24-f0ea-40ae-bf1a-54cf6874bea4</Key>
<HasValue>true</HasValue>
</LargeProperty1>
<LargeProperty2>
<Key>2016-08-10_15\d97c5639-09cf-4f78-8869-c5b184d09dcf</Key>
<HasValue>true</HasValue>
</LargeProperty2>
</MessageToSend>

Using conventions

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.

Example headers

$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = 554380dd342ba9aa0ca1926e4510b1be
$.diagnostics.originating.hostid = 554380dd342ba9aa0ca1926e4510b1be
CorrId = 87345d16-8bb0-488a-b93e-a65e00f9f231\0
NServiceBus.ContentType = text/xml
NServiceBus.ConversationId = a53f22dd-b424-46fd-8303-a65e00f9f231
NServiceBus.CorrelationId = 87345d16-8bb0-488a-b93e-a65e00f9f231
NServiceBus.DataBus.Core5.Headers.Writers.MyNamespace.MessageToSend.LargeProperty1 = 2016-08-10_15\27c6b43f-ee4d-45b6-a506-4cce0d3675b9
NServiceBus.DataBus.Core5.Headers.Writers.MyNamespace.MessageToSend.LargeProperty2 = 2016-08-10_15\f42037c4-1662-431b-8360-1270ae41429e
NServiceBus.EnclosedMessageTypes = Core5.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 87345d16-8bb0-488a-b93e-a65e00f9f231
NServiceBus.MessageIntent = Send
NServiceBus.OriginatingEndpoint = HeaderWriterDataBusConventionV5
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterDataBusConventionV5@MACHINENAME
NServiceBus.TimeSent = 2016-08-10 05:10:01:544585 Z
NServiceBus.Version = 5.2.14
WinIdName = MACHINENAME\simon

Example body

<?xml version="1.0" ?>
<MessageToSend xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://tempuri.net/Core5.Headers.Writers">
</MessageToSend>

Samples

Related Articles


Last modified