NServiceBus wire mapping¶
Note
NServiceBus licensing. NServiceBus is dual-licensed: the Reciprocal Public License 1.5, or Particular Software's commercial agreement (particular.net/LicenseAgreement). This format was captured from NServiceBus 10.2.9, and only the module's own .NET test programs use it. The Go module itself does not depend on NServiceBus.
NServiceBus has no envelope besides its headers, so NServiceBus() writes the event as headers and
the payload as the body. Wire.ContentType is the event's DataContentType.
What it writes¶
An event with every attribute, as Encode renders it:
envelope.Event{
ID: "7f2c1a9e-0000-4000-8000-000000000001", Source: "Shop.Sales",
Type: "Shop.Messages.PlaceOrder", Subject: "order-4172",
Time: time.Date(2026, 10, 24, 8, 27, 24, 123456789, time.UTC), DataContentType: "application/json",
Extensions: map[string]string{"tenant": "continuity"}, Data: []byte(`{"Order":"4172"}`),
}
NServiceBus.ContentType: application/json
NServiceBus.EnclosedMessageTypes: Shop.Messages.PlaceOrder
NServiceBus.MessageId: 7f2c1a9e-0000-4000-8000-000000000001
NServiceBus.OriginatingEndpoint: Shop.Sales
NServiceBus.TimeSent: 2026-10-24 08:27:24:123456 Z
ce-subject: order-4172
tenant: continuity
with Wire.ContentType application/json and the body {"Order":"4172"}.
| Event | Header | Notes |
|---|---|---|
ID |
NServiceBus.MessageId |
Any string. NServiceBus's IDs are strings, so nothing is refused. |
Type |
NServiceBus.EnclosedMessageTypes |
One entry. For a handler of Shop.Messages.PlaceOrder, the type is Shop.Messages.PlaceOrder, its full name, or its assembly-qualified name. |
Source |
NServiceBus.OriginatingEndpoint |
An endpoint's name. |
DataContentType |
NServiceBus.ContentType, and Wire.ContentType |
Omitted from the headers when empty. |
Time |
NServiceBus.TimeSent |
In UTC, as yyyy-MM-dd HH:mm:ss:ffffff Z: six digits of microseconds after a colon. Truncated to a microsecond. Omitted when Time is zero. |
Subject |
ce-subject |
Omitted when empty. |
DataSchema |
ce-dataschema |
Omitted when empty. |
each Extensions entry |
a header of the extension's name | One value, in lower case, such as tenant. |
Data |
the body | Unconstrained. NServiceBus picks its deserializer by the content type. |
SpecVersion |
none | Filled in as 1.0 when read. |
An empty value writes no header. Header values are single-valued: each is a one-element slice.
What it reads¶
Headers are matched in any case, since a header map may fold it. Two spellings of one header with
different values, or two different values under one key, are
ErrAmbiguousHeader; the same value twice is not.
| Header | Event | Notes |
|---|---|---|
NServiceBus.MessageId |
ID |
Any string. Absent leaves it empty, which Validate refuses. |
NServiceBus.EnclosedMessageTypes |
Type |
The text before the first ;. When there is more, the whole header value is also foreign. |
NServiceBus.OriginatingEndpoint |
Source |
Absent leaves it empty, which Validate refuses. |
NServiceBus.ContentType |
DataContentType |
The transport's content type is not used instead; see conflicts. |
NServiceBus.TimeSent |
Time |
Exactly yyyy-MM-dd HH:mm:ss:ffffff Z. Anything else is ErrInvalidTime. Absent leaves Time zero. |
ce-subject |
Subject |
|
ce-dataschema |
DataSchema |
|
| any header whose name is a valid extension name | Extensions[name] |
The first value. See below. |
| the body | Data |
Empty leaves Data nil. |
SpecVersion is always set to 1.0. Decode then runs Validate, so the usual refusals apply to
what was read. The first problem found is returned, with the event and Foreign it read.
Which headers are extensions¶
A header whose name is an extension name, lower-case letters and digits that are not one of the eight
attribute names or data, is read as an extension. This is because headers are where the format
writes extensions, so the reverse has to hold. It means a broker's or a producer's lower-case header,
such as priority or tenant, arrives as an extension and not as foreign. traceparent is
promoted the same way, and Traceparent is not, because the name has a capital.
A header with a hyphen, a dot or a capital in its name cannot be an extension name. All of NServiceBus's own are like that.
What becomes Foreign¶
Every other header is Foreign.Headers, under the name it arrived with and with all its values:
| Header | Why |
|---|---|
NServiceBus.ConversationId, NServiceBus.CorrelationId, NServiceBus.MessageIntent, NServiceBus.OriginatingMachine, NServiceBus.Version, NServiceBus.OpenTelemetry.StartNewTrace and the rest of NServiceBus's own |
The event has no place for them |
$.diagnostics.originating.hostid |
As above |
Tenant, a producer's header with a capital |
Not a valid extension name |
NServiceBus.EnclosedMessageTypes |
When it lists more than one type, the whole value, under that name |
Headers that are the event's own, in any case, are not listed again, and neither is content-type.
Conflicts¶
Foreign.Conflicts is ["content-type"] when the transport's content type (Wire.ContentType, or on
a transport without one a content-type header) is set, NServiceBus.ContentType is set, and the
two differ. The event keeps NServiceBus.ContentType. The transport's value is in
Foreign.Headers["content-type"]. When they agree there is no conflict.
From a real producer¶
testdata/send.txt and testdata/full.txt are messages NServiceBus 10.2.9 sent itself, as its
Learning transport stored them. full.txt sets a message ID, a Tenant and a tenant header, and
sends inside an activity, so NServiceBus adds traceparent. It reads as:
| Event or Foreign | Value |
|---|---|
ID |
7f2c1a9e-0000-4000-8000-000000000002 |
Source |
Shop.Sales |
Type |
Shop.Messages.PlaceOrder, producer, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null |
DataContentType |
application/json |
Time |
2026-10-24T08:27:24.321242Z |
Extensions |
tenant (continuity-lower) and traceparent |
Foreign.Headers["Tenant"] |
continuity |
Foreign.Conflicts |
none |
send.txt is a bare Send. Its foreign keys are $.diagnostics.originating.hostid,
NServiceBus.ConversationId, NServiceBus.CorrelationId, NServiceBus.MessageIntent,
NServiceBus.OpenTelemetry.StartNewTrace, NServiceBus.OriginatingMachine and NServiceBus.Version.
Both are checked in the module's tests.