Manipulating message headers

Component: NServiceBus
NuGet NServiceBus (3.x)
Standard support for version 3.x of NServiceBus has expired. For more information see our Support Policy.

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 Mutator

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

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

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 Mutator

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

From a Handler

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

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

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

From a Saga

public class WriteSaga :
    Saga<WriteSagaData>,
    IHandleMessages<MyMessage>
{
    public void Handle(MyMessage message)
    {
        var someOtherMessage = new SomeOtherMessage();
        someOtherMessage.SetHeader("MyCustomHeader", "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.

using (var startableBus = configure.UnicastBus().CreateBus())
{
    var outgoingHeaders = ((IBus)startableBus).OutgoingHeaders;
    outgoingHeaders.Add("AllOutgoing", "ValueAllOutgoing");
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