Skip to content

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.
  • tenant is an extension and Tenant is foreign. Only a name of lower-case letters and digits is an extension. The producer set both, and the format kept both.
  • traceparent is 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