Skip to content

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.