Handler pipeline

When Rebus handles an incoming message, it constructs a handler pipeline. Why is that?

Well, first of all: Your IActivateHandlers may return multiple handler instances when asked to activate handlers for a particular message type. E.g. you might have two things happening upon receiving a CustomerMoved event:

public class UpdateCustomerInformation : IHandleMessages<CustomerMoved> { ... }

and

public class InitiateDistrictChangedCheck : IHandleMessages<CustomerMoved> { ... }

But then your CustomerMoved event looks like this:

public class CustomerMoved : GeneralCustomerChange { ... }

and you actually have a handler that will sometimes notify some customer handling department of certain things that relate to when general stuff changes on a customer:

pubic class NotifyCustomerDepartmentSometimes : IHandleMessages<GeneralCustomerChange> { ... }

and since Rebus does polymorphic message dispatch, you now have three handlers to be executed on an incoming CustomerMoved event.

Now, what if you NEED to update customer information before doing anything else? I.e. execute the UpdateCustomerInformation handler before the others? With Rebus, it's easy - just set an order of the handlers like this:

Configure.With(...)
    .SpecifyOrderOfHandlers(o => o.First<UpdateCustomerInformation>())
    //etc

which will fit a special implementation of IInspectHandlerPipeline that orders the handlers before the message gets dispatched. If you need to, you can specify the order of multiple handlers, which - if they occur in the handler pipeline - will be guaranteed to be first and respecting the specified order:

Configure.With(...)
    .SpecifyOrderOfHandlers(o => o.First<ThisHandler>()
                                  .Then<AnotherHandler>()
                                  .Then<YetAnotherHandler>())
    //etc

Please note that you cannot specify each handler more than once, and you cannot call SpecifyOrderOfHandlers more than once. If you need more complex logic, you can make your own implementation of IInspectHandlerPipeline, which may even add and remove handlers at will.