Manipulating message headers

Component: NServiceBus | Nuget: NServiceBus (Version: 5.x)

The mechanism for header communication is either native headers, if the transport supports that feature, or via a serialized collection of key value pairs. This article covers the various ways of manipulating the message headers.

Reading incoming Headers

Headers can be read for an incoming message.

From a Behavior

Edit
public class IncomingBehavior :
    IBehavior<IncomingContext>
{
    public void Invoke(IncomingContext context, Action next)
    {
        var headers = context.PhysicalMessage.Headers;
        var nsbVersion = headers[Headers.NServiceBusVersion];
        var customHeader = headers["MyCustomHeader"];
        next();
    }
}

From a Mutator

Edit
public class MutateIncomingTransportMessages :
    IMutateIncomingTransportMessages
{
    public void MutateIncoming(TransportMessage transportMessage)
    {
        var headers = transportMessage.Headers;
        var nsbVersion = headers[Headers.NServiceBusVersion];
        var customHeader = headers["MyCustomHeader"];
    }
}

From a Handler

Edit
public class ReadHandler :
    IHandleMessages<MyMessage>
{
    IBus bus;

    public ReadHandler(IBus bus)
    {
        this.bus = bus;
    }

    public void Handle(MyMessage message)
    {
        var headers = bus.CurrentMessageContext.Headers;
        var nsbVersion = headers[Headers.NServiceBusVersion];
        var customHeader = headers["MyCustomHeader"];
    }
}

From a Saga

Edit
public class ReadSaga :
    Saga<ReadSagaData>,
    IHandleMessages<MyMessage>
{
    public void Handle(MyMessage message)
    {
        var headers = Bus.CurrentMessageContext.Headers;
        var nsbVersion = headers[Headers.NServiceBusVersion];
        var customHeader = headers["MyCustomHeader"];
    }

Writing outgoing Headers

Headers can be written for an outgoing message.

From a Behavior

Edit
public class OutgoingBehavior :
    IBehavior<OutgoingContext>
{
    public void Invoke(OutgoingContext context, Action next)
    {
        var headers = context.OutgoingMessage.Headers;
        headers["MyCustomHeader"] = "My custom value";
        next();
    }
}

From a Mutator

Edit
public class MutateOutgoingTransportMessages :
    IMutateOutgoingTransportMessages
{
    public void MutateOutgoing(LogicalMessage logicalMessage, TransportMessage transportMessage)
    {
        var headers = transportMessage.Headers;
        headers["MyCustomHeader"] = "My custom value";
    }
}

From a Handler

Edit
public class WriteHandler :
    IHandleMessages<MyMessage>
{
    IBus bus;

    public WriteHandler(IBus bus)
    {
        this.bus = bus;
    }

    public void Handle(MyMessage message)
    {
        var someOtherMessage = new SomeOtherMessage();
        bus.SetMessageHeader(
            msg: someOtherMessage,
            key: "MyCustomHeader",
            value: "My custom value");
        bus.Send(someOtherMessage);
    }
}

From a Saga

Edit
public class WriteSaga :
    Saga<WriteSagaData>,
    IHandleMessages<MyMessage>
{
    public void Handle(MyMessage message)
    {
        var someOtherMessage = new SomeOtherMessage();
        Bus.SetMessageHeader(
            msg: someOtherMessage,
            key: "MyCustomHeader",
            value: "My custom value");
        Bus.Send(someOtherMessage);
    }

For all outgoing messages

NServiceBus supports registering headers at configuration time that are then added to all outgoing messages for the endpoint.

Edit
var startableBus = Bus.Create(busConfiguration);
startableBus.OutgoingHeaders.Add("AllOutgoing", "ValueAllOutgoing");
using (var bus = startableBus.Start())
{
The global outgoing headers are not thread safe. It is recommended that they are manipulated at startup.

Samples

Related Articles

  • Handlers
    Write a class to handle messages in NServiceBus.
  • Message Handling Pipeline
    Overview of the message handling pipeline.
  • Message Headers
    List of built-in NServiceBus message headers.
  • Message Mutators
    Message Mutators allow mutation of messages in the pipeline.
  • Sagas
    NServiceBus uses event-driven architecture to include fault-tolerance and scalability in long-term business processes.

Last modified