Getting Started
Architecture
NServiceBus
Transports
Persistence
ServiceInsight
ServicePulse
ServiceControl
Monitoring
Samples

Routing topology

NuGet Package: NServiceBus.RabbitMQ (8.x)
Target Version: NServiceBus 8.x

The RabbitMQ transport has the concept of a routing topology, which controls how it creates exchanges, queues, and the bindings between them in the RabbitMQ broker. The routing topology also controls how the transport uses the exchanges it creates to send and publish messages. All endpoints in a system must use the same routing topology to be able to communicate with each other. For new systems, the conventional routing topology should be used. The direct routing topology is recommended only when adding an endpoint to an existing system that already uses that routing topology. A custom routing topology can be useful when integrating with a legacy system.

Conventional routing topology

The conventional routing topology relies on fanout exchanges to route messages.

The recommended routing topology is the conventional routing topology. It was the default topology prior to NServiceBus.RabbitMQ version 5.

Sending using the conventional routing topology

Each endpoint creates a pair of a fanout exchange and a queue named after the endpoint's name. It also creates a binding between them. Messages are sent to the endpoint by publishing them to the endpoint's exchange. The binding then routes the message to the endpoint's queue.

Publishing using the conventional routing topology

For each type being published, a series of fanout exchanges are created to model the inheritance hierarchy of the type. For each type involved, an exchange is created, named in the following format: Namespace:TypeName. Bindings are created between the types, going from child to parent, until the entire hierarchy has been modeled. Exchanges are also created for each interface the type implements.

When an endpoint subscribes to an event, it first ensures that the above infrastructure exists. It then adds a binding from the exchange corresponding to the subscribed type to its own exchange.

When an endpoint publishes an event, it first ensures that the above infrastructure exists. It then publishes the message to the exchange corresponding to the message type being published.

Enabling the conventional routing topology

To enable the conventional routing topology, use the following configuration:

var transport = endpointConfiguration.UseTransport<RabbitMQTransport>();
transport.UseConventionalRoutingTopology(QueueType.Quorum);

Direct routing topology

The direct routing topology routes all events through a single exchange, amq.topic by default. Events are published using a routing key based on the event type, and subscribers will use that key to filter their subscriptions.

Sending using the direct routing topology

Every endpoint creates a queue named after the endpoint's name. When an endpoint sends a message it publishes it to a default exchange with a routing key equal to the destination endpoint name. This makes use of RabbitMQ default exchanges to move the message to a queue with the same name.

Publishing using the direct routing topology

Every endpoint publishes an event using the amq.topic exchange with a routing key of the form Namespace.TypeName, corresponding to the type of the event. The event is moved to all queues that have a binding for that event type.

An endpoint that subscribes to a given event creates a binding to the default exchange with the appropriate routing key.

In accordance with the AMQP 0.9.1 standard the routing key has a length limit of 255 characters.

Enabling the direct routing topology

To enable the direct routing topology, use the following configuration:

var transport = endpointConfiguration.UseTransport<RabbitMQTransport>();
transport.UseDirectRoutingTopology(QueueType.Quorum);

Overriding the default conventions

The default conventions for exchange names and routing keys can be overridden by using the following overload:

var transport = endpointConfiguration.UseTransport<RabbitMQTransport>();
transport.UseDirectRoutingTopology(
    QueueType.Quorum,
    routingKeyConvention: MyRoutingKeyConvention,
    exchangeNameConvention: () => "MyTopic");
In some cases, the direct routing topology may not deliver message types with "non-system" interfaces in their inheritance hierarchy. A "non-system" interface is any interface which is not contained in a .NET Framework assembly (any assembly signed with the same public key as mscorlib), and is not one of the interfaces. When using the direct routing topology, message types must not inherit from "non-system" interfaces. To guarantee delivery of message types which inherit from non-system interfaces, the conventional routing topology must be used.

Controlling queue type

The routing topologies provided by the transport can work with classic queues or quorum queues by specifying it via the QueueType parameter. When installers are enabled, this parameter controls what type of queue is created.

For existing endpoints using classic queues, the queue migrate-to-quorum command provided by the command line tool can be used to migrate to quorum queues on a queue-by-queue basis.

Controlling exchange and queue durability

The routing topologies provided by the transport create durable exchanges and queues by default. To create transient exchanges and queues, use the following:

var transport = endpointConfiguration.UseTransport<RabbitMQTransport>();
transport.DisableDurableExchangesAndQueues();

Custom routing topology

If the built-in routing topologies do not satisfy the requirements of the system, a custom routing topology may be used. To do this:

  1. Define the routing topology by creating a class implementing IRoutingTopology.
  2. Register it with the transport as shown below:
var transport = endpointConfiguration.UseTransport<RabbitMQTransport>();
transport.UseCustomRoutingTopology(
    topologyFactory: createDurableExchangesAndQueues =>
    {
        return new MyRoutingTopology(createDurableExchangesAndQueues);
    });

The boolean argument supplied to the factory delegate indicates whether the custom routing topology should create durable exchanges and queues on the broker. Read more about durable exchanges and queues in the AMQP Concepts Guide.

Related Articles


Last modified