Skip to content

Carry headers and foreign fields

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.

Send an extension

An extension is a header of its own name, one value:

e.Extensions = map[string]string{"tenant": "continuity"}
tenant: continuity

Names follow envelope.ValidExtensionName: lower-case ASCII letters and digits. Subject and DataSchema travel as ce-subject and ce-dataschema. Every extension value must be safe to log; see the event model.

Send a trace

Set the traceparent extension:

e.Extensions = map[string]string{"traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"}

Read a trace

traceparent is not a special case in this format. NServiceBus has no envelope besides its headers, so the format reads any lower-case header with an extension name as an extension, and traceparent is one. A case variant such as Traceparent has a capital, so it is not, and is foreign:

trace := e.Extensions["traceparent"]

In the captured full.txt, NServiceBus added traceparent because the producer sent inside an activity, and it reads as an extension.

Expect other lower-case headers as extensions

A broker's or a producer's lower-case header, such as priority or tenant, arrives in e.Extensions, not in Foreign. In full.txt the producer set Tenant and tenant: tenant is an extension with its value, and Tenant is foreign.Headers["Tenant"].

An extension's value is the header's first value. A lower-case header with an empty value, or a control character in one, fails validation and the message is refused.

Read NServiceBus's own headers

Correlation, conversation and the rest are not part of the event. They are foreign headers under their full names:

if ids := foreign.Headers["NServiceBus.CorrelationId"]; len(ids) > 0 {
    logger.Info("correlated", "correlation", ids[0])
}

The full list read from a real send is in Wire mapping.

Check for a conflict

The one conflict is the content type. If the transport carries a content type that differs from NServiceBus.ContentType, the event keeps NServiceBus's and the key content-type is in foreign.Conflicts, with the transport's value in foreign.Headers["content-type"]:

for _, key := range foreign.Conflicts {
    logger.Warn("transport disagrees with the envelope", "key", key, "transport", foreign.Headers[key])
}

What you cannot send

Foreign is read-only. The format writes only the headers listed in Wire mapping, so a correlation ID received from NServiceBus does not go back out on a reply. To correlate, put an identifier in an extension.