Message routing

Component: NServiceBus
NuGet Package NServiceBus (7.2)

The routing subsystem is responsible for finding destinations for messages. In most cases, the code which sends messages should not specify the destination of the message being sent:

var endpointInstance = await Endpoint.Start(endpointConfiguration)
var message = new MyMessage();
await endpointInstance.Send(message)

Based on the type of the message, the routing subsystem will provide the destination address.

NServiceBus routing consists of two layers, logical and physical. Logical routing defines which logical endpoint should receive a given outgoing message. Physical routing defines to which physical instance of the selected endpoint should the message be delivered. While logical routing is a developer's concern, physical routing is controlled by operations.

Broker transports handle the physical routing automatically. Other transport might require specific configuration. See also MSMQ Routing.

Command routing

As described in messages, events and commands, NServiceBus distinguishes between these kinds of messages. Command messages are always routed to a single logical endpoint.

Command routing can be configured in code. The routing API is attached to the transport configuration object because some routing APIs are transport-specific. The routes can be specified at assembly, namespace or specific type levels.

var transport = endpointConfiguration.UseTransport<MyTransport>();

var routing = transport.Routing();
    assembly: typeof(AcceptOrder).Assembly,
    destination: "Sales");

    assembly: typeof(AcceptOrder).Assembly,
    @namespace: "PriorityMessages",
    destination: "Preferred");

    messageType: typeof(SendOrder),
    destination: "Sending");

The routing engine prevents ambiguous routes so if route information comes from more than one source (e.g. code API and configuration file) the user has to make sure the type specifications do not overlap. If they do overlap, an exception will be thrown preventing the endpoint from starting up.

Per-namespace routes override assembly-level routes while per-type routes override both namespace and assembly routes.

Overriding the destination

In specific cases, like sending to the same endpoint or to a specific queue (e.g. for integration purposes), the routing configuration can be overridden when sending a given message. Refer to documentation on sending messages for further details.

Event routing

When events are published, they can be received by multiple logical endpoints. However, even in cases where those logical endpoints are scaled out, each event will be received by only one physical instance of a specific logical subscriber. It is important to note that before the event is published and delivered, the subscriber has to express its interest in that event by having a message handler for it.


Multicast transports support the Publish-Subscribe pattern natively. In this case the subscriber uses the APIs of the transport to create a route for a given subscribed message type.

The Azure Service Bus EndpointOrientedTopology requires publisher names to be configured.


Other transports do not support Publish-Subscribe natively. These transports emulate the publish behavior by sending message to each subscriber directly. To do this, the publisher endpoint has to know its subscribers and subscribers have to notify the publisher about their interest in a given event type. The notification message (known as the subscribe message) has to be routed to the publisher.

Subscribe message routing can be configured using code API

var transport = endpointConfiguration.UseTransport<MyTransport>();

var routing = transport.Routing();
    assembly: typeof(OrderAccepted).Assembly,
    publisherEndpoint: "Sales");

    assembly: typeof(OrderAccepted).Assembly,
    @namespace: "PriorityMessages",
    publisherEndpoint: "Preferred");

    eventType: typeof(OrderSent),
    publisherEndpoint: "Sending");

Similarly to the command routing, more specific publisher registrations override less specific ones. The registrations need to be unambiguous.

Subscribe message routing can also be configured in a configuration section.

In the UnicastBusConfig/MessageEndpointMappings configuration section, publishers are registered in the same way as the command destinations are defined. If a given assembly or namespace contains both events and commands, the mapping will recognize that fact and configure the routing correctly (both commands and subscribe messages will be routed to the destination specified in the Endpoint attribute).

MessageEndpointMappings routing configuration can also take advantage of message inheritance: base types "inherit" routes from the derived types (opposite to member inheritance in .NET). If both EventOne and EventTwo inherit from BaseEvent, when subscribing to BaseEvent the subscription messages are sent to publishers of both EventOne and EventTwo.

Reply routing

Reply message are always routed based on the ReplyTo header of the initial message regardless of the endpoint's routing configuration. Only the sender of the initial message can influence the routing of a reply. Refer to documentation on sending messages for further details.


  • Publish/Subscribe
    Publish/Subscribe, fault-tolerant messaging, and durable subscriptions.

Related Articles

Last modified