Routing

"Routing" is what happens when Rebus, based on some logic that you configure somehow, decide where to send your message.

You don't HAVE to configure anything in order to send messages - you can specify their destination manually, like so:

await bus.SendLocal(someMessage);

in order to send a message directly to yourself, or

await bus.Advanced.Routing.Send("another.queue", someMessage);

to send a message to another.queue. In some cases, this can be fine, but as the size of your system grows, explicitly routing messages is NOT the preferred way. This is mainly due to two facts:

Hardcoding message destinations makes your system unflexible.

Your application should not care about these things - routing should be implemented by the bus.

(although bus.SendLocal might still make a lot of sense if the sent message is "private" to the endpoint and thus is only used internally)

Therefore, Rebus has an extra level of indirection that helps you route messages by adding some configuration in the form of "endpoint mappings".

How do you use the bus to route things?

The most basic routing mechanism in Rebus is based on "topics", where a topic is just a string, like so: "great topic". This is pretty low level and can be pretty useful in itself, but it is a little bit rough around the edges.

On top of this mechanism, Rebus enables you to route your messages based on their type, which has proven to be such a useful model that it's the default routing mechanism, and is the one most prominently exposed in the API.

In order to configure the type-based routing, you use the Routing part of the configurer, like so:

Configure.With(...)
.(...)
.Routing(r => r.TypeBased())
.(...);

The TypeBased() configuration extension above can then be fluently built upon with more extension methods, e.g. like so:

r.TypeBased()
.Map<SomeMessage>("owner.of.SomeMessage")

in order to declare that the owner of SomeMessage is the endpoint receiving messages from the owner.of.SomeMessage queue, or

r.TypeBased()
.MapAssemblyOf<SomeMessage>("owner.of.SomeMessage")

in order to declare that all message types from the assembly containing SomeMessage are owned by owner.of.SomeMessage.

So how does Rebus make use of the endpoint mapping in different scenarios?

When you

await bus.Send(commandMessage);

Rebus will

generate a topic string out of commandMessage's type, e.g. something like Messages.CommandMessage, Messages

look through its endpoint mappings to find the queue name of the owner of Messages.CommandMessage, Messages, e.g. something like command-processor

send the message to the command-processor queue

When you

await bus.Subscribe<EventMessage>();

Rebus will

generate a topic string out of the EventMessage type, e.g. something like Messages.EventMessage, Messages

look through its endpoint mappings to find the queue name of the owner of Messages.EventMessage, Messages, e.g. something like event-publisher

send a SubscribeRequest to the event-publisher queue

(the Rebus endpoint behind event-publisher will intercept the message and store the sender's input queue name as a subscriber of the topic Messages.EventMessage, Messages in its subscription storage)

When you

await bus.Publish(eventMessage);

Rebus will

generate a topic string out of eventMessage's type, e.g. something like Messages.EventMessage, Messages

look into its subscription storage and find the queue names of those, who subscribed to the topic Messages.EventMessage, Messages

send eventMessage to each queue found in the subscription storage

What is this thing about "owning" a message type?

Messages can usually be said to be owned by an endpoint somewhere.

If the message type is a request or a reply, the owner would be the server that is capable of handling that request and sending back that reply.

If the message type is an event, the owner would be the publisher publishing that event.

We do our best to ensure that the documentation wiki is up-to-date - please let us know if you think there's something we should do better.