Exchange a message with an NServiceBus endpoint¶
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.
By the end of this you will have written the headers and body of an event as an NServiceBus message, seen the shape a .NET endpoint reads it in, and read a message NServiceBus sent as a Go event. The .NET half uses a program from the module's repository and runs in a container, so it needs Docker and network, to restore NServiceBus from NuGet.
1. Get the module and its test programs¶
$ go get gitlab.com/phpboyscout/go/envelope
$ go get gitlab.com/phpboyscout/go/envelope-nservicebus
$ git clone https://gitlab.com/phpboyscout/go/envelope-nservicebus
The clone holds testdata/consumer, an NServiceBus endpoint called Shop.Billing with a handler for
PlaceOrder that prints what .NET sees. It is not part of the Go module.
2. Encode an event¶
The handler is for Shop.Messages.PlaceOrder, so that is the event's type. NServiceBus names the
sender of a message by its endpoint, so the source is the producing endpoint's name.
package main
import (
"encoding/json"
"fmt"
"log"
"time"
"gitlab.com/phpboyscout/go/envelope"
nservicebus "gitlab.com/phpboyscout/go/envelope-nservicebus"
)
func main() {
w, err := nservicebus.NServiceBus().Encode(envelope.Event{
ID: "7f2c1a9e-0000-4000-8000-000000000001",
Source: "Shop.Sales",
Type: "Shop.Messages.PlaceOrder",
DataContentType: "application/json",
Time: time.Date(2026, 10, 24, 8, 27, 24, 0, time.UTC),
Data: []byte(`{"Order":"4172","Lines":3}`),
})
if err != nil {
log.Fatal(err)
}
headers := map[string]string{}
for name, values := range w.Headers {
headers[name] = values[0]
}
meta, _ := json.MarshalIndent(headers, "", " ")
fmt.Println(string(meta))
}
The program prints the headers a transport would carry:
{
"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:000000 Z"
}
Unlike MassTransit's, the body is the payload untouched: w.Body is {"Order":"4172","Lines":3}.
Everything else is in headers. NServiceBus.TimeSent has six digits of microseconds after a colon,
and a trailing Z.
3. Have an endpoint handle it¶
testdata/README.md describes how to feed the endpoint: write the headers as a JSON object in
<id>.metadata.txt and the body in .bodies/<id>.body.txt, under the endpoint's
.learningtransport/Shop.Billing/ directory, then run the consumer:
$ docker run --rm -v "$PWD/testdata/consumer:/src" -w /src mcr.microsoft.com/dotnet/sdk:10.0 dotnet run
The endpoint's handler prints === handled and the message ID, then the deserialized PlaceOrder
as message:, then each header NServiceBus holds as a header: line. The program waits for three
messages and gives up after twenty seconds, and prints handled and a count when it stops.
Output not reproduced
This page does not quote the endpoint's output, because it was written without running the .NET
side. Check that handled reports your message, and that the message: line carries order 4172
with three lines.
4. Read a message NServiceBus sent¶
testdata/full.txt is a message NServiceBus 10.2.9 sent itself through its Learning transport: each
header as header Name: value, then a blank line, then the body. It sets a message ID, a Tenant and
a tenant header, and sends inside an activity. Read it with envelope.Read:
raw, err := os.ReadFile("testdata/full.txt")
if err != nil {
log.Fatal(err)
}
head, body, _ := strings.Cut(string(raw), "\n\n")
wire := envelope.Wire{Headers: map[string][]string{}, Body: []byte(body)}
for line := range strings.SplitSeq(head, "\n") {
if rest, ok := strings.CutPrefix(line, "header "); ok {
name, value, _ := strings.Cut(rest, ": ")
wire.Headers[name] = append(wire.Headers[name], value)
}
}
e, foreign, format, err := envelope.Read(wire, nservicebus.NServiceBus())
Printing the results gives:
format: nservicebus
id: 7f2c1a9e-0000-4000-8000-000000000002
type: Shop.Messages.PlaceOrder, producer, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
source: Shop.Sales
content type: application/json
time: 2026-10-24T08:27:24.321242Z
extensions: map[tenant:continuity-lower traceparent:00-31ce2a8b75318f4fbf4653e225346ce1-d0a1b6506df0c237-01]
Tenant: [continuity]
conversation: [1015b1b1-ce24-428e-9eb2-b4ed008b5cf1]
conflicts: []
where the last three of those come from foreign.Headers["Tenant"],
foreign.Headers["NServiceBus.ConversationId"] and foreign.Conflicts.
- The type is the assembly-qualified name, because that is what NServiceBus sent. A .NET handler matches on the full name, the short name or this form.
tenantis an extension andTenantis foreign. Only a name of lower-case letters and digits is an extension. The producer set both, and the format kept both.traceparentis an extension, for the same reason: it is a lower-case header.- The correlation and conversation IDs are foreign. The event has no place for them.
Where next¶
- Send to NServiceBus and Read from NServiceBus, inside a service.
- Wire mapping: every header, and where it goes.
- What does not round-trip.