MassTransit Documentation - Read the Docs

MassTransit Documentation 

Release 2.0 

Chris Patterson, Travis Smith, and Dru Sellers 

October 02, 2014

Contents 

1 MassTransit Installation 3 

1.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 

1.2 How to install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 

1.3 Getting hold of us . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 

1.4 How to report bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 

2 Configuring MassTransit 7 

2.1 Show me the code! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 

2.2 Common Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 

2.3 Common Subscription Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 

2.4 Locations in your Application where MT is usually configured . . . . . . . . . . . . . . . . . . . . . 12 

2.5 Transport Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 

2.6 Using MassTransit with an IoC Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 

2.7 Common Gotcha’s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 

3 How MassTransit Works 23 

3.1 Key Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 

3.2 When messages are published, how do they get there? . . . . . . . . . . . . . . . . . . . . . . . . . 26 

3.3 When messages are sent, how do they get there? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 

3.4 How to do Request/Response with MassTransit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 

3.5 Versioning Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 

3.6 Inbound Message Processing Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 

3.7 How are subscriptions shared? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 

3.8 What does MassTransit add on top of MSMQ and RabbitMQ? . . . . . . . . . . . . . . . . . . . . . 37 

3.9 Defining Sagas using the Saga State Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 

3.10 Routing of Messages in MassTransit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 

3.11 What is the Data Bus? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 

3.12 What is a Control Bus? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 

3.13 Inheritance and Message Class Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 

3.14 Companies Using MassTransit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 

3.15 Serialization Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 

3.16 Logging in MassTransit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 

3.17 Performance Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 

3.18 Standard Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 

3.19 Runtime Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 

3.20 Videos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 

3.21 What is MassTransit? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 

3.22 Correlation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 

i

3.23 Handling errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 

4 Troubleshooting MassTransit 53 

4.1 Issues and possible solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 

5 Advanced MassTransit Concepts 55 

5.1 Interop with MassTransit (Routing RFC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 

5.2 The Distributor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 

6 Samples 59 

6.1 Starbucks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 

6.2 Heavy Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 

6.3 Open All Night . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 

7 MassTransit Learning Series 61 

7.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 

7.2 Creating Your First Consumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 

8 Indices and tables 69 

ii

MassTransit Documentation, Release 2.0 

Contents: 

Contents 1


2 Contents

CHAPTER 1 

MassTransit Installation 

This section of the online docs will explain how to get MassTransit into your project. It will also show you were to get 

help, how to report bugs, etc. Hopefully, you will find it useful as you explore the MassTransit framework. 

1.1 Prerequisites 

MassTransit is a .Net framework for C# and will need a .Net runtime to run on. 

To work with MassTransit you will need to be running on a Windows operating system. The developers of MassTransit 

regulary test on Windows 7 and Windows Server 2008RC2. Though it should still work on Windows Server 2003, as 

long as .Net 3.5 sp1 is installed. 

Note: People are starting to run MassTransit with RabbitMQ on Mono with success. 

1.1.1 .Net Framework 

Currently MassTransit is tested on .Net 3.5 sp1 and .Net 4.0. 

1.1.2 Transport Choices 

MassTransit sits on top of a communication layer like MSMQ, or RabbitMQ. So you will need to have one of those 

installed. We currently support: 

Loopback 

Note: The loopback transport is great for testing. Not so much for production. 

ServiceBusFactory.New(sbc => 

{ 

//loopback is configured by default 

}); 

MSMQ 

The default queueing platform for Windows 

3


RabbitMQ 

A high volume queueing platform 

1.2 How to install 

1.2.1 NuGet 

The simplest way to install MassTransit into your solution/project is to use NuGet.: 

nuget Install-Package MassTransit 

However, the NuGet packages don’t contain the MassTransit.RuntimeServices executable and database SQL scripts. 

The RuntimeServices system routes messages to multiple subscribers via the Subscription Service. If you plan to use 

the “UseSubscriptionService” feature, then you’ll need to get compile that from source. 

1.2.2 Compiling From Source 

Lastly, if you want to hack on MassTransit or just want to have the actual source code you can clone the source from 

github.com. 

To clone the repository using git try the following: 

git clone git://github.com/MassTransit/MassTransit.git 

If you want the development branch (where active development happens): 

git clone git://github.com/MassTransit/MassTransit.git 

git checkout develop 

1.2.3 Build Dependencies 

To compile MassTransit from source you will need the following developer tools installed: 

• .Net 4.0 sdk 

• ruby v 1.8.7 

• gems (rake, albacore) 

1.2.4 Compiling 

To compile the source code, drop to the command line and type: 

.\build.bat 

If you look in the .\build_output folder you should see the binaries. 

4 Chapter 1. MassTransit Installation


1.3 Getting hold of us 

Getting hold of the gang behind MassTransit is pretty straight forward, we try to help as much as time permits and 

have tried to streamline this process as much as possible. 

But before you grab hold of us, spend a moment composing your thoughts and formulate your question, there is 

nothing as pointless as simply telling us “MassTransit does not work for me” with no further information to give any 

clue to why. 

And before you even do that, do a couple of searches to see if your question is already answered, if it has been, you 

will get your answer much faster that way. 

1.3.1 Mailing List 

Getting on or off our mailinglist happens through Google Groups. 

http://groups.google.com/group/masstransit-discuss/ 

If you are going to use MassTransit, subscribing to our masstransit-discuss mailing list is probably a very 

good idea. This is where most conversation about MassTransit is going to happen. 

Make sure to pick a good subject line, and if the subject of the thread changes, please change the subject to match, 

some of us deal with hundreds of emails per day, after spam-filters, and we need all the help we can get to pick the 

interesting ones. 

Also, please include the diagnostics output generated by the config switch 

sbc.WriteDiagnosticsToFile("a_file.txt"). This will help jump start a lot of the context for 

us. 

1.3.2 Twitter 

The most immediate way to get hold of us, is to shoot a tweet to #mtproj 

Our main time zone is Central time in the United States. 

If you can explain your problem in a clear sentence, twitter is a good way to get quick response. If you do need to 

paste log files, config and so on, please use a gist. But because its often not clear because usually there is a great 

deal of context to a question we may push you to our mailing list on google groups. 

If twitter is all quiet, try the mailing list as well, we do have lives, families and jobs to deal with also. 

1.3.3 Issues / Tickets 

Please do not open an issue on github, unless you have spotted an actual bug in MassTransit. Ask on the mailing list 

first if you are in doubt. 

https://github.com/masstransit/masstransit/issues 

The reason for this policy, is to avoid the bugs being drowned in a pile of sensible suggestions for future enhancements 

and call for help from people who forget to check back if they get it and so on. 

1.4 How to report bugs 

MassTransit can be a tricky beast to debug, with a multi-threaded system, trying to track down the issue can be a bit 

painful. 

1.3. Getting hold of us 5


So if you run into a bug, please spend a minute collecting the right information to help us fix the bug. 

The most valuable piece of information you can give us, is always give us a failing unit test, if you can’t give us that 

then how to reproduce the bug in a step by step fashion. Other wise its going to be a lot of back and forth until we can 

better understand and get to a failing unit test. 

6 Chapter 1. MassTransit Installation

CHAPTER 2 

Configuring MassTransit 

Now that you have MassTransit installed into your project, we need to get it configured so that you can start bringing 

the awesome! First we have a quickstart which will be followed up with a few configuration examples. 

2.1 Show me the code! 

All right, all right, already. Here you go. Below is a functional setup of MassTransit. 

1 public class YourMessage { public string Text { get; set; } } 

2 public class Program 

3 { 

4 public static void Main() 

5 { 

6 Bus.Initialize(sbc => 

7 { 

8 sbc.UseMsmq(); 

9 sbc.VerifyMsmqConfiguration(); 

10 sbc.UseMulticastSubscriptionClient(); 

11 sbc.ReceiveFrom("msmq://localhost/test_queue"); 

12 sbc.Subscribe(subs=> 

13 { 

14 subs.Handler(msg=>Console.WriteLine(msg.Text)); 

15 }); 

16 }); 

17 

18 Bus.Instance.Publish(new YourMessage{Text = "Hi"}); 

19 } 

20 } 

2.1.1 So what is all of this doing? 

If we are going to create a messaging system, we need to create a message. YourMessage is a .Net class that will 

represent our message. Notice that it’s just a plain C# class (or POCO). 

Next up, we need a program to run our code. Here we have a standard issue command line Main method. To setup 

the bus we start with the static class Bus and its Initialize method. This method takes a lambda whose first and 

only argument is a class that will let you configure every aspect of the bus. 

One of your first decisions is going to be “What transport do I want to run on?” Here we have choosen MSMQ 

(sbc.UseMsmq()) because its easy to install on a Windows machines (sbc.VerifyMsmqConfiguration()), 

will do just that and its most likely what you will use. 

7


After that we have the sbc.UseMulticastSubscriptionClient() this tells the bus to pass subscription 

information around using PGM over MSMQ giving us a way to talk to all of the other bus instances on the network. 

This eliminates the need for a central control point. 

Now we have the sbc.ReceiveFrom("msmq://localhost/test_queue) line which tells us to listen for 

new messages at the local, private, msmq queue ‘test_queue’. So anytime a message is placed into that queue the 

framework will process the message and deliver it to any consumers subscribed on the bus. 

Lastly, in the configuration, we have the Subscribe lambda, where we have configured a single Handler for our 

message which will be activated which each message of type YourMessage and will print to the console. 

And now we have a bus that is configured and can do things. So now we can grab the singleton instance of the service 

bus and call the Publish method on it. 

2.1.2 But Singletons are Evil! 

If you shudder at the thought of a singleton in your code, that’s ok - we have you covered too. Instead of using 

Bus.Initialize you can use the code below: 

1 var bus = ServiceBusFactory.New(sbc => 

2 { 



5 sbc.ReceiveFrom("msmq://localhost/test_queue"); 

6 }); 

2.2 Common Configuration Options 

Trying to get multiple applications to talk to each other is not a simple problem. The biggest difficulty seems to be just 

getting everything configured correctly. With over three years of experience in setting up message based systems the 

developers on MassTransit have tried their darndest to make sure that the MassTransit’s defaults cover the majority of 

the decisions you will have to make while minimizing the configuration code you have to deal with. We hope that the 

options are clear and make sense why you need to select them. Below are some of the options you have: 

2.2.1 Transport Factory Options 


{ 

sbc.UseMsmq(); 

sbc.UseRabbitMq(); 

}); 

//if you would like to implement your own. 

sbc.AddTransportFactory(); 

The first decision is what transport are you going to use? RabbitMQ or MSMQ? If you don’t know which one to 

choose I suggest reading up on the two and see which one works better for your environment. 

2.2.2 Basic Options 

8 Chapter 2. Configuring MassTransit



{ 

//transport choice 

}); 

sbc.ReceiveFrom("address"); 

sbc.UseControlBus(); 

The next decision we have to make is what address are we going to listen on? Addresses are 

in the form of a URL and will look like msmq://localhost/queue_name or for RabbitMQ 

rabbitmq://localhost/queue_name. 

Warning: Each instance must have its own address. For more information see ‘gotchas’ 

The last concern is, do you want to use a control bus or not. Control Bus 


{ 


//address 

}); 


2.2.3 Serializer Options 


{ 


//address 

//control bus 

}); 

sbc.UseBinarySerializer(); 

sbc.UseBsonSerializer(); 

sbc.UseJsonSerializer(); 

sbc.UseVersionOneXmlSerializer(); 

sbc.UseXmlSerializer(); 

//if you would like to implement your own. 

sbc.SetDefaultSerializer(); 

This is mostly optional, because the transports will set their preferred defaults, but if you need to override the default 

you can using these methods. With the SetDefaultSerializer you can provide a custom serializer that you 

created. 

2.2.4 Bus Tuning Options 


{ 

sbc.SetConcurrentConsumerLimit(2); 

sbc.SetDefaultTransactionTimeout(5.Minutes()); 

sbc.AfterConsumingMessage(()=>{}); 

2.2. Common Configuration Options 9


sbc.BeforeConsumingMessage(()=>{}): 

sbc.ConfigureEndpoint(); 

}); 

These options, aren’t usually needed until you get into production and need to tune the behavior of the bus. 

2.2.5 Turning on Diagnostics 

If you want to get a snapshot of how your service bus is configured, you can get a pretty good picture of it by using 

the method. 

var bus = ServiceBusFactory.New(sbc => { /* usual stuff */ }); 

var probe = bus.Probe(); 

//you can now inspect the probe 

//for your convience we also have added a few helper methods. 

bus.WriteIntrospectionToFile("a_file.txt"); //great to send with support requests :) 

bus.WriteIntrospectionToConsole(); 

You may also want to inspect a running bus instance remotely. For that you just need to enable remote introspection 

like so. 


{ 

//the usual options 

}); 

sbc.EnableRemoteInstrospection(); 

You can then use the busdriver to query the status. using: 

busdriver status -uri: 

2.2.6 Low Level Config Api 


{ 

sbc.AddBusConfigurator 

sbc.AddService(); 

}); 

If you are using these, then we probably need to talk. This usually means that there is a low level feature we are not 

supplying to you. Its totally ok to use these, but they tend to need a lot of parameters and require intimate knowledge 

of MassTransit. 

2.3 Common Subscription Options 

MassTransit has a lot of ways that you can provide subscription options. 



2.3.1 Subscription Options During Configuration 


{ 

sbc.Subscribe(s=> 

{ 

s.Handler(msg => {}); 

s.Handler((cxt, msg) => {}); 

s.Instance(yourObject); 

s.Consumer(()=> new YourConsumer() ); 

s.Consumer(consumerFactory); 

s.Consumer(consumerType); 

s.Consumer(); 

//for a permanent subscription 

s.Consumer() 

.Permanent(); 

s.Saga(sagaRepository); 

}); 

}); 

//if using an IoC container 

//this will scan the container and call Consumer(type) on found 

//types 

s.LoadFrom(container); 

Now that we have a transport, an address, and some basic options figured out the meat of the work is in front of you. 

Establishing your subscriptions. As you can see there are a lot of options so I am going to save most of the explanation 

for the next page. 

Note: Permanent Subscriptions will NOT be automatically unsubscribed at bus shutdown. See keyideas 

2.3.2 Subscription Options With IoC Container 


{ 

sbc.Subscribe(s=> 

{ 

//if using an IoC container 

//this will scan the container and call Consumer(type) on found 

//types 

s.LoadFrom(container); 

}); 

}); 

Note: Need more notes here 

2.3. Common Subscription Options 11


2.3.3 Subscription Options During Post Configuration 

var bus = ServiceBusFactory.New(sbc => { /* configure */ }); 

//options 

bus.SubscribeConsumer(); 

bus.SubscribeHandler(); 

bus.SubscribeInstance(); 

bus.SubscribeSaga(); 

Note: Subscriptions established post-configuration are assumed to be transient. If this is to be a permanent subscription, 

it needs to be established during configuration. 

2.4 Locations in your Application where MT is usually configured 

Now that we know how to configure the MassTransit system, the next question is usually where should I do the 

configuration? 

The short answer is: Configure it when you are configuring your IoC Container. 

2.4.1 Configuring MassTransit in a Console Application / Windows Service 

I typically do this inside of the methods that build up my IoC container and typically I do this in the main method. 

public class Program 

{ 

public void static main(string[] args) 

{ 

//configure MT 

} 

} 

//execute program logic 

2.4.2 Configuring MassTransit in a Website 

I still typically do this inside of the methods that build up my IoC container, but instead of the main method it usually 

happens in the global.asax file. 

Note: A lot of our samples show using MT with another open source project Topshelf. This is a .Net Windows 

Service host, and should not be used with web sites. 

public class Global : HttpApplication 

{ 

protected void Application_Start() 

{ 

//configure MT 

} 

} 

//execute program logic 



2.5 Transport Configuration 

Each transport has different configuration options. 

2.5.1 Msmq Configuration Options 


{ 


sbc.VerifyMsmqConfiguration(); 

sbc.VerifyMsDtcConfiguration(): 

}); 

Crap. I just wiped out the msmq and have to rewrite. 

UseMsmq() should be obvious. It configures the bus to use the MSMQ transport. 

VerifyMsmqConfiguration() will confirm that MSMQ is correctly installed and fix the install by adding missing 

components. 

VerifyMsDtcConfiguration() will confirm that the DTC is setup correctly. 

Note: A post on MSMQ and Ports: http://blogs.msdn.com/b/johnbreakwell/archive/2008/04/29/clear-the-way-msmqcoming-through.aspx 

Note: A post on public vs private queues: http://technet.microsoft.com/en-us/library/cc776346.aspx 

Installing MSMQ Step by step (12/21/2011) #. Get to ‘Computer Management’ #. Expand ‘Services and Applications’ 

#. Expand ‘Message Queuing’ #. Right click on ‘Private Queues’: New > Private Queue #. Enter a ‘Queue Name’ #. 

Choose whether or not you would like it to be ‘Transactional’ or not. 

Note: Creating a queue this way will require permission changes. As you will be the only person able to administer 

the queue! STRONGLY suggested that you at this time give the Administrator role Full Control over the queue. 

2.5. Transport Configuration 13


Permission Role: Consumer Role: Sender 

Full Control 

• • 

Delete 

Receive Message 

Peek Message 

Receive Journal Message 

Y 

Y 

• • 

• • 

• 

• 

Get Properties Y Y 

Set Porperties 

• • 

Get Permissions Y Y 

Set Permissions 

• • 

Take Ownership 

• • 

Send Message Y Y 

Special Permissions 

• • 

2.5.2 RabbitMQ Configuration Options 

This is the recommended approach for configuring MassTransit for use with RabbitMQ. 


{ 

sbc.UseRabbitMq(r => 

{ 

r.ConfigureHost(new Uri("rabbitmq://hostname/vhost/queue"), h => 

{ 

h.SetUsername("username"); 

h.SetPassword("password"); 

}); 

}); 

// other options 

}); 

UseRabbitMq tells the MassTransit code to use RabbitMQ as the transport. This also sets the default serializer to 

JSON. 

About the RabbitMQ routing topology in place with MassTransit. 

• networks are segregated by vhosts 

• we generate an exchange for each queue so that we can do direct sends to the queue. it is bound as 

a fanout exchange 

• for each message published we generate series of exchanges that go from concrete class to each of 

its subclass / interfaces these are linked together from most specific to least specific. This way if you 



subscribe to the base interface you get all the messages. or you can be more selective. all exchanges 

in this situation are bound as fanouts. 

• the subscriber declares his own queue and his queue exchange - he then also declares/binds his 

exchange to each of the message type exchanges desired 

• the publisher discovers all of the exchanges needed for a given message, binds them all up and then 

pushes the message into the most specific queue letting RabbitMQ do the fanout for him. (One 

publish, multiple receivers!) 

• control queues are exclusive and auto-delete - they go away when you go away and are not shared. 

• we also lose the routing keys. WIN! 

You will need to configure RabbitMQ to support SSL also http://www.rabbitmq.com/ssl.html. 

Concurrent Consumers with RabbitMQ 

When using concurrent consumers with rabbitmq you need to set both the number of concurrent consumers to X and 

you need to set the prefetch. This is a quick note in the docs to remind people of this. A bit of detail is in the link 

below. 

https://groups.google.com/forum/#!topic/masstransit-discuss/-0F7jswXIso 

2.5.3 Loopback Configuration Options 


{ 

//loopback is the default 

sbc.ReceiveFrom("loopback://localhost/queue"); 

}); 

Note: Great for testing, not great for production. 

So the loopback uses the protocol ‘loopback’ - localhost is the machine name and then you can use whatever you want 

for the ‘queue’ bit as long as each bus instance has a unique one, you should be good to go. 

2.6 Using MassTransit with an IoC Container 

MassTransit has been built from the beginning with the concept of an IoC container being involved. Our support 

for using them is quite solid and mature and is most certainly recommended. However with everything else you are 

learning trying to figure out just how to get the container involved might be overwhelming. Below you will find 

prototypical examples of container integration. 

2.6.1 StructureMap 

public static void main(string[] args) 

{ 

var container = new Container(cfg => 

{ 

// register each consumer 

cfg.ForConcreteType(); 

2.6. Using MassTransit with an IoC Container 15


}); 

//or use StructureMap’s excellent scanning capabilities 

var bus = ServiceBusFactory.New(sbc => 

{ 

//other configuration options 

}); 

//this will find all of the consumers in the container and 

//register them with the bus. 

sbc.Subscribe(x => x.LoadFrom(container)); 

} 

//now we add the bus 

container.Inject(bus); 

Note: We recommend that most of this type of code be placed in an StructureMap Registry 

2.6.2 Windsor 


{ 

var container = new WindsorContainer(); 

// register each consumer manually 

container.Register(Component.For().LifestyleTransient()); 

//or use Windsor’s excellent scanning capabilities 

container.Register(AllTypes.FromThisAssembly().BasedOn()); 


{ 


}); 



sbc.Subscribe(x => x.LoadFrom(container)); 

} 


container.Register(Component.For().Instance(bus)); 

Note: We recommend that most of this type of code be placed in an IWindsorInstaller 

A POCO handler approach and IWindsorInstaller wrapped could be like the following: 

public class MassTransitInstaller : IWindsorInstaller 

{ 

public void Install(IWindsorContainer container, Castle.MicroKernel.SubSystems.Configuration.ICon 

{ 

var consumerConfig = container.Resolve(); // for configurations, like 

var busBatchClose = ServiceBusFactory.New(sbc => 

{ 



); 

} 


sbc.UseMulticastSubscriptionClient(); 

sbc.ReceiveFrom(consumerConfig.BatchCloseQueue); 

sbc.EnableMessageScope(); 

sbc.Subscribe(x => x.Handler(msg => 

{ 

var handler = container.Resolve(); 

handler.CloseBatch(msg); 

container.Release(handler); 

})); 

} 

} 

container.Register(Component.For().Instance(busBatchClose).Named("BatchCloseQueu 

container.Release(consumerConfig); // irrelevant for this sample, but we need to release what 

2.6.3 AutoFac 


{ 

var builder = new ContainerBuilder(); 


builder.RegisterType().AsSelf(); 

//or use Autofac’s scanning capabilities -- SomeClass is any class in the correct assembly 

builder.RegisterAssemblyTypes(typeof(SomeClass).Assembly) 

Where(t => t.Implements()) 

.AsSelf(); 


builder.Register(c => ServiceBusFactory.New(sbc => 

{ 




sbc.Subscribe(x => x.LoadFrom(c.Resolve())); 

})).As() 

.SingleInstance(); 

} 

var container = builder.Build(); 

Note: We recommend that most of this type of code be placed in an Autofac Module 

2.6.4 Ninject 


{ 

var kernel = new StandardKernel(); 

2.6. Using MassTransit with an IoC Container 17



kernel.Bind().ToSelf(); 

//Dru is currently unaware of any scanning capability 


{ 


}); 

//we have to explicitly configure the subscriptions because 

//the Ninject metadata model is not rich enough. 

sbc.Subscribe(subs => 

{ 

subs.Consumer(kernel) 

}); 

} 


kernel.Bind().To(bus); 

Note: We recommend that most of this type of code be placed in an Ninject Module 

Warning: The Ninject container doesn’t currently support the workflow that we can use with the other 

containers, and because of that the LoadFrom method that our other container extensions use is not supported. 

We filed an issue with the Ninject team, and the issue was closed with ‘Not going to fix’. 

https://github.com/ninject/ninject/issues/35 

2.6.5 Unity 

{ 


var container = new UnityContainer(); 

// Lookup the types. 

// You can scan for all types that implement the .All-interface of the Consumes-class. 

var types = new TypeFinder().FindTypesWhichImplement(typeof(Consumes.All)); 

foreach (var type in types) 

{ 

var interfaceType = type.GetInterfaces().FirstOrDefault(a=> a == typeof(Consumes< 

container.RegisterType(interfaceType, type, new ContainerControlledLifetimeManage 

} 

// or you can register your types directly. 

container.RegisterType 

{ 

sbc.UseRabbitMq(c => 

{ 

// Add configation options if required. 

// Default JSON serialization is set by MassTransit. 



} 

})); 

}); 

// Configure exchanges. 

sbc.ReceiveFrom(receiveQueue); 

sbc.Subscribe(s => s.LoadFrom(container)); 

sbc.SetConcurrentConsumerLimit(concurrentConsumers); 

sbc.SetDefaultRetryLimit(retryLimit); 

// When using MSMQ as Transport you can choose to verify the DTC configuration. 

// if (verifyDTCConfiguration) 

// sbc.VerifyMsDtcConfiguration(); 

// Configure logging. 

if (enableLogging) 

sbc.UseLog4Net(); 

// No performance counters. 

sbc.DisablePerformanceCounters(); 

2.6.6 Hey! Where’s my container?? 

Don’t see your container here? Feel free to submit a pull request. You should easily be able to add support by following 

the other containers. 

2.7 Common Gotcha’s 

2.7.1 Trying to share a queue 

Each application needs it own address! If you have a website and a console application they will each need 

their own address. For instance the website could listen at msmq://localhost/web and the console at 

msmq://localhost/console. 

The reason for this is you are defining the ‘receiving’ queue. This is where the bus instance will receive its messages. 

It would be like sharing a mailbox with your neighbor, some times you get all the mail, sometimes they get all the 

mail. 

2.7.2 How to do an NServiceBus send only endpoint? 

Use the IEndpointResolver to get an Endpoint that you can call .Send(msg) on. 

2.7.3 How to setup a competing consumer? 

need to doc this. ;) 

RabbitMQ and Msmq 

2.7. Common Gotcha’s 19


2.7.4 Where did the Batch go? 

We removed the concept, as it required you to bind to the MT dll too tightly in your messages. We don’t yet have a 

way to reproduce the behavior but you can do this in your application. If you would like to submit an example we 

would appreciate it. :) 

2.7.5 So, what links two bus instances together? 

This is a common question. The binding element, really is the message contract. If you want message A, then you 

subscribe to message A. The internals of MT wires it all together. 

2.7.6 Why aren’t queue / message priorities supported? 

Message Priorities are used to allow a message to jump to the front of the line. When people ask for this feature they 

usually have multiple types of messages all being delivered to the same queue. The problem is that each message has 

a different SLA (usually the one with the shorter time window is the one getting the priority flag). The problem is that 

w/o priorities the important message gets stuck behind the less important/urgent ones. 

The solution is to stop sharing a single queue, and instead establish a second queue. In MassTransit you would 

establish a second instance of IServiceBus and have it subscribe to the important/urgent message. Now you have two 

queues, one for the important things and one for the less urgent things. This helps with monitoring queue depths, error 

rates, etc. By placing each IServiceBus in its own Topshelf host / process you further enhance each bus’s ability to 

process messages, and isolate issues / downtime. 

Reading 

http://www.udidahan.com/2008/01/30/podcast-message-priority-you-arent-gonna-need-it/ 

http://lostechies.com/jimmybogard/2010/11/18/queues-are-still-queues/ 

2.7.7 I want to know if another bus is subscribed to my message. 

So, if you try to program this way, you’re going to have a bad time. ;) 

Knowing that you have a subscriber is not the concern of your application. It is something the system architect should 

know, but not the application. Most likely, we just need to introduce all of the states in our protocol more explicitly, 

by using a Saga. 

A Sample Saga 

//Magnum.StateMachine based saga 

public class MySaga : 

SagaStateMachine, 

ISaga 

{ 

static MySaga() 

{ 

Define(() => 

{ 

Initially( 

When(CommandOccured) 

.Then(saga => saga.StartTimer()) //pseudo code 

.TransitionTo(InProcess)); 



During(InProcess, 

When(Timeout) 

.TransitionTo(TimedOut), 

When(Succeeded) 

.TransitionTo(Success), 

When(Error) 

.TransitionTo(Failed)); 

} 

}); 

//States 

public static State Initial { get; set; } 

public static State InProcess { get; set; } 

public static State TimedOut { get; set; } 

public static State Succeeded { get; set; } 

public static State Error { get; set; } 

public static State Completed { get; set; } 

//Events 

public static Event CommandOccured { get; set; } 

public static Event Timeout { get; set; } 

public static Event Succeeded { get; set; } 

public static Event Error { get; set; } 

} 

//instance data 

public virtual Guid CorrelationId {get;set;} 

2.7. Common Gotcha’s 21



CHAPTER 3 

How MassTransit Works 

3.1 Key Terminology 

When getting started using MassTransit, it is a good idea to have a handle on the terminology used in messaging. 

To ensure that you are on the right path when looking at a class or interface, here are some of the terms used when 

working with MassTransit. 

3.1.1 Messages and Serialization 

MassTransit is a service bus, and a service bus is designed to move messages. At the lowest level, a message is a chunk 

of JSON, XML, or even binary data. When using a statically typed language (such as C#), a message is represented 

by an instance of a class (or interface) that has relevant properties, each of which can be a value, list, dictionary, or 

even another nested class. 

When using MassTransit, messages are sent and received, published and subscribed, as types. The translation (called 

serialization) between the textual representation of the message (which is JSON, XML, etc.) and a type is handled 

using a message serializer. The default serialization varies (for MSMQ, the framework uses XML by default, for 

RabbitMQ JSON is used instead). The default serialization can be changed when a service bus is being configured. 

sbc.UseJsonSerializer(); // uses JSON by default 

sbc.UseXmlSerializer(); // uses XML by default 

sbc.UseBsonSerializer(); // uses BSON (binary JSON) by default 

3.1.2 Receiving Messages 

At the application layer, most users of MassTransit are interested in receiving messages. There are several different 

receiver types that are supported, providing flexibility it how you interact with the framework. 

Handlers 

The easiest (and, by definition, least flexible) type of receiver is the Handler. A handler is any method (including 

anonymous and lambda methods) that has a single argument of a message type and a void return type. 

void MyMessageHandler(MyMessage message) 

{} 

When a message is received, MassTransit will call the method passing the message as the argument. With a handler, 

no special controls are available to manage the lifecycle of the receiver. Therefore, it is up to the application to deal 

23


with the fact that the handler may be called simultaneously from multiple threads if more than one message is being 

received. If your application is not thread-safe, it is recommended that the concurrent consumer limit be set to one in 

the bus configuration to avoid multithreading issues. 

Instances 

An Instance receiver is a class instance where the class implements one or more Consumes interfaces. Each of the 

Consumes interfaces accepts a generic argument (which must be a reference type) that declares the type of message 

the instance wants to consume. Once an instance is subscribed, as messages of the subscribed types are received, 

MassTransit will call the Consume method on the class instance passing the message as the argument. 

public class MyClass : 

Consumes.All, 

Consumes.All 

{ 

public void Consume(MyMessage message) 

{} 

public void Consume(MyOtherMessage message) 

{} 

} 

Consumers 

A Consumer is the most useful type of receiver and support a number of features that allow proper lifecycle management 

of dependencies, as well as multiple message type handling. Consumers are declared using the same interfaces 

as an instance, however, instead of subscribing an already created instance of the class to the bus, the consumer type 

is subscribed along with a consumer factory. As messages are received, MassTransit calls the consumer factory to get 

an instance of the consumer and calls the Consume method on the instance passing the message as the argument. 

By using the consumer factory, MassTransit allows the implementation to handle the lifecycle of consumer instances. 

Actual implementations vary, and can range from a simple constructor call to create an instance to the retrieval of a 

consumer and any of the consumers dependencies (such as a database session, cache reference, etc.) from an inversion 

of control (IoC) container. Since the consumer factory returns a handler to MassTransit, the factory can wrap the 

consumer call with any lifecycle management/synchronization code before and after the message is consumed. 

Interfaces for Consumers 

public class Consumes 

{ 

public interface All : IConsumer 

{ 

void Consume(TMessage message); 

} 

public interface Selected : All 

{ 

bool Accept(TMessage message); 

} 

public interface For : 

All, 

CorrelatedBy 

{ 

24 Chapter 3. How MassTransit Works


} 

} 

All 

Consumes.All 

This interface defines the void Consume(TMessage message) method 

Selected 

Consumes.Selected 

This interface defines an additional method allowing to process only selected messages, by implementing the bool 

Accept(TMessage message) method. 

For 

Consumes.For 

This interface defines how to do a correlated consumer. 

Note: Consumers are usually sourced from an IoC container. When they are, MassTransit respects your container’s 

lifecycle. 

Sagas 

All of the receiver types above are stateless by design, the framework makes no effort to correlate multiple messages 

to a single receiver. Often it is necessary to orchestrate multiple messages, usually of different types, into a saga 

(sometimes called a workflow). A saga is a long-running transaction that is managed at the application layer (instead 

of, for example, inside of a database or a distributed transaction coordinator). MassTransit allows sagas to be declared 

as a regular class or as a state machine using a fluent interface. 

The key difference for sagas is that the framework manages the saga instance and correlates messages to the proper 

saga instance. This correlation is typically done using a CorrelationId, which is an interface (called CorrelatedBy). 

Messages correlated an individual saga must be done using a Guid. Sagas may also observe messages that are not 

correlated directly to the saga instance, but this should be done carefully to avoid potentially matching a message to 

hundreds of saga instances which may cause database performance issues. 

public class MySaga : 

ISaga, 

InitiatedBy.All, 

Orchestrates.All 

{ 

public Guid CorrelationId { get; set; } 

public void Consume(MyInitialMessage message) 

{} 

public void Consume(MyFollowUpMessage message) 

{} 

} 

3.1. Key Terminology 25


3.1.3 Transports and Endpoints 

MassTransit is a framework, and being a framework has certain rules. The first of which is known as the Hollywood 

principle – “Don’t call us, we’ll call you.” Once the bus is configured and running, the receivers are called by the 

framework as messages are received. There is no need for the application to poll a message queue or repeated call a 

framework method in a loop. 

To initiate the calls into your application code, MassTransit creates an abstraction on top of the messaging platform 

(such as MSMQ or RabbitMQ). 

Transports 

At the lowest level, closest to the actual messaging platform used, is the transport. Transports communicate with the 

actual platform API to send and receive messages. The transport implementation is split into two parts, inbound and 

outbound, providing the ability to support asymmetric APIs where sending and receiving have different behaviors 

and/or addresses. 

Endpoints 

The endpoint is the abstraction used to send messages directly and to receive messages by the service bus. It is very 

uncommon (and not recommended) for an application to call Receive on an endpoint. Endpoints are referenced by 

address and no distinction is made between inbound and outbound at the endpoint level. 

Address 

In MassTransit, a URI is used as an address to an endpoint. The elements of the URI are used to determine the proper 

transport, server, port, and queue name of the actual endpoint. For example, an MSMQ endpoint on the local machine 

named “my_queue” would have the address shown below. 

msmq://localhost/my_queue 

A RabbitMQ queue on a remote server may be listed as below. 

rabbitmq://user:password@remote_server/my_queue 

3.2 When messages are published, how do they get there? 

What actually happens when you call bus.Publish(yourMessage)? The process itself is pretty simple, but 

it does depend on your transport. The first thing to know is that MassTransit has something called an ‘Outbound 

Pipeline’. Messages enter into the outbound pipeline to be sent to the actual transport. Once they hit the transport, the 

messages leave your .Net process and enter the process of the transport infrastructure. 

Note: Transports that are currently supported are MSMQ and RabbitMQ. There are also community contributed 

ActiveMQ and Azure Service Bus transports. Finally there is a non-production In-Memory Loopback which we use 

for testing. 

MassTransit prefers a dynamic routing model, we do not enforce a static routing model, however it can be achieved 

with the ‘static routing bits’. What this means is that when you call the Subscribe methods, MassTransit is going 

to setup the necessary routing for you. 

The ‘necessary’ routing will vary by transport that you use. 



Note: We do realize that some prefer a more static approach to this process, so there is an extension to the system 

to allow this called static routing. You will HAVE to manually set up all subscriptions on ALL endpoints for this to 

work. Its a lot of manual monkey work in my opinion, but a scalpel you shall have. 

With that out of the way lets discuss how the transport affects routing. 

3.2.1 Multicast MSMQ 

Subscription are communicated to each bus through the use of multicast MSMQ. This allows us to not have single point 

of failure, but it does NOT tollerate all of the bus instances going down. This is because the subscription information 

is being held in memory. 

3.2.2 Plain MSMQ 

Subscription data is communicated to each bus through an intermediary known as the ‘Subscription Service’. The subscription 

service is a well known location where each bus sends its subscription requests to, and gets the subscription 

requests of others from. 

Publisher 

1 // Setup Mass Transit. 


3 { 


5 sbc.ReceiveFrom("msmq://localhost/BulkProcessing.Web"); 

6 sbc.UseSubscriptionService("msmq://localhost/mt_subscriptions"); 

7 // sbc.VerifyMsmqConfiguration(); This doesn’t work on Windows 8. 

8 }); 

9 

10 // Send Message 

11 var sendContext = new SendContext(message); 

12 sendContext.SetMessageId(Guid.NewGuid().ToString()); 

13 sendContext.SetCorrelationId(Guid.NewGuid().ToString()); 

14 sendContext.SetExpirationTime(DateTime.Now.AddDays(1)); 

15 

16 Bus.Instance.Publish(message); 

Subscriber 

1 static void Main(string[] args) 

2 { 


4 { 


6 sbc.ReceiveFrom("msmq://localhost/BulkProcessing.Consumer"); 

7 sbc.UseSubscriptionService("msmq://localhost/mt_subscriptions"); 

8 // sbc.VerifyMsmqConfiguration(); This doesn’t work on Windows 8. 

9 

10 sbc.Subscribe(subs => 

11 { 

12 subs.Handler(msg => Console.WriteLine(msg.Text)); 

13 }); 

3.2. When messages are published, how do they get there? 27


14 }); 

15 

16 while (true) 

17 { 

18 Thread.Sleep(1000); 

19 } 

20 } 

3.2.3 Internal detail of both MSMQ transports 

Because MSMQ doesn’t have any routing capabilities, MassTransit has built them internal using a construct called a 

‘Pipeline.’ This pipeline is configured by the local subscription adapter (one for Plain MSMQ and one for Multicast 

MSMQ) to add and remove segments to the pipeline. When a message comes in it goes through the pipeline logic, 

and then is sent directly to the bus on the other end. 

Note: It is the subscription service that keeps all of the outbound and inbound pipelines, across all of the instances, 

in order. 

3.2.4 RabbitMQ 

Because RabbitMQ has a much, much better routing system, instead of trying to redo that work for RabbitMQ, we 

instead configure the RabbitMQ system’s routing primitives to achieve the same thing that we have done in MSMQ 

and the Outbound/Inbound pipelines. 

So a message is routed straight to the correct RabbitMQ Exchange. The internal workings of MassTransit make sure 

to configure RabbitMQ exchanges and bindings to implement the MassTransit pattern of routing. This means MT can 

make one call to RMQ, and let RabbitMQ deal with it from there. 

3.3 When messages are sent, how do they get there? 

TBD 

3.4 How to do Request/Response with MassTransit 

This is a super simple example. I just hacked it up so that we would have something to improve upon later. :) 

1 //the messages 

2 public class BasicRequest : 

3 CorrelatedBy 

4 { 

5 public Guid CorrelationId { get;set; } 

6 public string Text { get; set; } 

7 } 

8 public class BasicResponse : 


10 { 

11 public Guid CorrelationId { get; set; } 

12 public string Text { get; set; } 

13 } 



1 //the responder 


3 { 


5 { 


7 { 




11 sbc.ReceiveFrom("msmq://localhost/message_responder"); 

12 sbc.Subscribe(subs=> 

13 { 

14 subs.Handler( (cxt, msg )=> 

15 { 

16 cxt.Respond(new BasicResponse{Text = "RESP"+msg.Text}); 

17 }); 

18 }); 

19 }); 

20 } 

21 } 

1 //the requester 


3 { 


5 { 


7 { 




11 sbc.ReceiveFrom("msmq://localhost/message_requestor"); 

12 }); 

13 

14 Bus.Instance.PublishRequest(new BasicRequest(), x => 

15 { 

16 x.Handle(message => Console.WriteLine(message.Text)); 

17 x.SetTimeout(30.Seconds()); 

18 }); 

19 } 

20 } 

Warning: Each instance must have its own address. For more information see ‘gotchas’ 

So what is going on? The first chunk has the messages we are going to work with. 

The second chunk shows the code to simple echo back the request message as a response. 

The final chunk shows the code to publish the request and handle any responses that relate to the original request 

message. Once any response is received (with the same correlation id as the original request) the remaining handlers 

are unsubscribed and the request operation completes. 

This style of request will block the calling thread until either a response is received by one of the handlers, or the 

timeout period expires. If it expires, a RequestTimeoutException is thrown. If a response handler throws an exception, 

that exception is rethrown on the thread that sent the request (since it is blocked waiting on the response anyway). 

The request can also be executed asynchronously using the Asychronous Programming Model of .NET. By call- 

3.4. How to do Request/Response with MassTransit 29


ing BeginPublishRequest (or the endpoint-based BeginSendRequest), an IAsyncResult is returned to the caller. The 

IAsyncResult could then be passed to whatever framework code is handling the asynchronous operation (such as a 

BeginWebMethod/EndWebMethod pair or an AsyncController). 

Once the callback is invoked (or the wait handle is signaled), the EndRequest method (which is an extension method 

off IEndpoint or IServiceBus) must be called to complete the request (at this point, any timeout or response handler 

exceptions will be thrown). 

NOTE: The asynchronous model will create a wait event if requested, but the callback style is greatly preferred since 

it reduces the amount of operating system resources required. 

3.5 Versioning Messages 

Versioning of messages is going to happen, services evolve and requirements change. 

3.5.1 Versioning Existing Message Contracts 

Consider a command to fetch and cache a local copy of an image from a remote system. 

1 public interface FetchRemoteImage 

2 { 

3 Guid CommandId { get; } 

4 DateTime Timestamp { get; } 

5 Uri ImageSource { get; } 

6 string LocalCacheKey { get; } 

7 } 

After the initial deployment, a requirement is added to resize the image to a maximum dimension before saving it to 

the cache. The new message contract includes the additional property specifying the dimension. 

1 public interface FetchRemoteImage 

2 { 

3 Guid CommandId { get; } 




7 int? MaximumDimension { get; } 

8 } 

By making the _int_ value nullable, commands that are submitted using the original contract can still be accepted as 

the missing value does not break the new contract. If the value was added as a regular _int_, it would be assigned a 

default value of zero, which may not convey the right information. String values can also be added as they will be 

_null_ if the value is not present in the serialized message. The consumer just needs to check if the value is present 

and process it accordingly. 

3.5.2 Versioning Existing Events 

Consider an event to notify that an image has been cached is now available. 

1 public interface RemoteImageCached 

2 { 

3 Guid EventId { get; } 


5 Guid InitiatingCommandId { get; } 





8 } 

An application will publish the event using an implementation of the class, as shown below. 

1 class RemoteImageCachedEvent : 

2 RemoteImageCached 

3 { 

4 Guid EventId { get; set; } 

5 DateTime Timestamp { get; set; } 

6 Guid InitiatingCommandId { get; set; } 

7 Uri ImageSource { get; set; } 

8 string LocalCacheKey { get; set; } 

9 } 

The class implements the event interface, and when published, is delivered to consumers that are subscribed to the 

RemoteImageCached event interface. MassTransit dynamically creates a backing class for the interface, and populates 

the properties with the values from the serialized message. 

Note that you cannot dynamically cast the RemoteImageCached interface in the consumer to the RemoteImageCachedEvent, 

as the actual class is not deserialized. This can be confusing, but is intentional 

to prevent classes (and the behavior that comes along with it) from being serialized and deserialized. 

As the event evolves, additional event contracts can be defined that include additional information without modifying 

the original contract. For example. 

1 public interface RemoteImageCachedV2 

2 { 

3 Guid EventId { get; } 


5 Guid InitiatingCommandId { get; } 


7 

8 // the string is changed from LocalCacheKey to a full URI 

9 Uri LocalImageAddress { get; } 

10 } 

The event class is then modified to include the additional property, while still implementing the previous interface. 

1 class RemoteImageCachedEvent : 

2 RemoteImageCached, 

3 RemoteImageCachedV2 

4 { 

5 Guid EventId { get; set; } 

6 DateTime Timestamp { get; set; } 

7 Guid InitiatingCommandId { get; set; } 

8 Uri ImageSource { get; set; } 

9 string LocalCacheKey { get; set; } 

10 Uri LocalImageAddress { get; set; } 

11 } 

When the event class is published now, both interfaces are available in the message. When a consumer subscribes to 

one of the interfaces, that consumer will receive a copy of the message. It is important that both interfaces are not 

consumed in the same context, as duplicates will be received. If a service is updated, it should use the new contract. 

Note that ownership of the contract belongs to the event publisher, not the event observer/subscriber. 

And contracts should not be shared between event producers as this can create some extensive leakage of 

multiple events making it difficult to consume unique events. 

3.5. Versioning Messages 31


As mentioned above, depending upon the interface type subscribed, a dynamic backing class is created by MT. 

Therefore, if a consumer subscribes to RemoteImageCached, it is not possible to cast the message to RemoteImageCachedV2, 

as the dynamic implementation does not support that interface. 

It should be noted, however, that on the IConsumeContext interface, there is a method to TryGetContext 

method, which can be used to attempt to deserialize the message as type T. So it is possible to 

check if the message also implements the new version of the interface and not process as the original 

version knowing that the new version will be processed on the same message consumption if both types 

are subscribed. 

The message is a single message on the wire, but the available/known types are captured in the message headers so 

that types can be deserialized from the message body. 

A lot of flexibility and power, it’s up to the application developer to ensure that it is used in a way that ensures 

application evolution over time without requiring forklift/switchover upgrades due to breaking message changes. 

3.6 Inbound Message Processing Pipeline 

There are a lot of moving parts in MassTransit to receive a chunk of text from a queue, deserialize the text into a 

message object, dispatch that message to one or more receivers, and finally acknowledge the message on the queue. 

The diagram below shows the path a message takes from the transport all the way up to the receiver. 



3.6. Inbound Message Processing Pipeline 33


3.7 How are subscriptions shared? 

Once a subscription is created on a local bus, this information then needs to be shared between all the different bus 

instances in your application network. 

Say you have a Timeout service. This service runs on a separate bus that is hooked to the queue 

msmq://localhost/timeout. Whenever your application wants to schedule a timeout, it needs to send a 

ScheduleTimeout message to this queue. But in order for your application bus to know this routing path, it 

needs to receive this information first. 

Though the routing data is the same, how this information get to all of the nodes is different depending on your 

transport configuration. 

3.7.1 Permanent v.s. Temporary Subscriptions 

Subscriptions are what registers the intent to consume a given message. The structure of the subscription is 

Subscription(message_name, address, correlation_id). Permanent subscriptions represent a 

subscription that you want to have stay around even if your process is shut down (maybe you are doing an upgrade and 

don’t want to miss a message). A temporary subscription is to be used in the case where you won’t care if you miss a 

message while shut down. 

3.7.2 Unsubscribe Token 

Any time you call subscribe off of IServiceBus you will get a token back that can be called to unsubscribe the 

subscription. 

var subscriptionToken = bus.Subscribe(); 

//later, when you want to unsubscribe 

if(!subscriptionToken()) 

{ 

//handle failure condition 

} 

Note: If you are using a permanent subscription and don’t want unsubscribe don’t call the delegate. 

If you do call the token it will be re-subscribed on start up. 

3.7.3 Transport Specific Notes 

As said earlier, different transport mechanisms use different subscription distributions. Please take a look below how 

your transport layer handles this and to see the differences. If your transport layer does not handle this specifically, 

you can rely on the SubscriptionService 

MSMQ Multicast 

Warning: 

• limited by default to one subnet 

• subscriptions do not survive service restarts (no perm subscriptions) 

• sensitive to the order in which services are brought online 



Each bus instance communicates with every other instance on the network through a reliable multicast network protocol. 


{ 

//other settings 

}); 


sbc.UseMulticastSubscriptionClient(); //turns on multicast 

sbc.SetNetwork("YOUR_KEY"); //must be set to cross machines 

MSMQ Runtime Services 

Each bus instance communicates with every other instance through an intermediary known as the Runtime Services 

(specifically the Subscription Service). 

Note: supports permanent subscriptions 


{ 

//other settings 

}); 


sbc.UseSubscriptionService("msmq://localhost/my_queue"); 

RabbitMQ 

Each bus instance communicates with a local rabbitmq server. Setting up the necessary bindings and queues based on 

MassTransit conventions. RabbitMQ then syncs all binding information to all nodes in the cluster. 

Note: supports permanent subscriptions 


{ 

// this is the recommended routing strategy, and will call ’sbc.UseRabbitMq()’. 

sbc.UseRabbitMqRouting(); 

}); 

// more config 

3.7.4 Subscription Service 

If your transport layer does not provide a transport specific way of sharing subscription information you can use the 

SubscriptionService. In this case subscription coordination depends on a central manager. This manager is 

an instance of a SubscriptionService that runs somewhere in your network. Each bus instance then uses a 

SubscriptionClient to communicate with this central management and exchanges subscription information. 

By default MassTransit bundles with the MSMQ Runtime Services. This is an MSMQ implementation of the 

SubscriptionService that you can run seperatly from your project. If you do not use the MSMQ as a transport 

layer you can easily host it yourself. 

3.7. How are subscriptions shared? 35


Hosting a subscription service 

The example below creates two ‘application domain’ bus instances and a subscription service. The service bus is 

responsible for transporting timeout messages, the second is your own awesome application. 

// 

// setup the subscription service 

// 

var subscriptionBus = ServiceBusFactory.New(sbc => 

{ 

sbc.UseStomp(); 

sbc.SetConcurrentConsumerLimit(1); 

}); 

sbc.ReceiveFrom("stomp://localhost/mt_subscriptions"); 

var subscriptionSagas = new InMemorySagaRepository(); 

var subscriptionClientSagas = new InMemorySagaRepository(); 

var subscriptionService = new SubscriptionService(subscriptionBus, subscriptionSagas, subscriptionCli 

subscriptionService.Start(); 

// 

// setup the time out service 

// 

var timeoutBus = ServiceBusFactory.New(sbc => 

{ 



}); 

sbc.ReceiveFrom("stomp://localhost/mt_timeouts"); 

sbc.UseSubscriptionService("stomp://localhost/mt_subscriptions"); 

var timeoutService = new TimeoutService(timeoutBus, new InMemorySagaRepository()); 

timeoutService.Start(); 

// 

// setup your awesome application bus 

// 


{ 



sbc.ReceiveFrom("stomp://localhost/your_awesome_application"); 

sbc.UseSubscriptionService("stomp://localhost/mt_subscriptions"); 

}); 

Subscription Client 

By stating sbc.UseSubscriptionService("stomp://localhost/mt_subscriptions"); you implicitly 

attach a SubscriptionClient to your service bus. 

One of the first thing this client does, is send a AddSubscriptionClient to the SubscriptionService 

queue. After that it starts observing subscription modifications and subsequently sends either an AddSubscription 

or RemoveSubscription messsage. This way updates are propagated to other nodes in your application network. 



The client also handles the SubscriptionRefresh messages it receives from the SubscriptionService. 

These refresh messages contain the subscription information of other nodes. 

3.8 What does MassTransit add on top of MSMQ and RabbitMQ? 

MassTransit is a service bus implementing the data bus pattern in a distributed setting. It aims to be a .Net-friendly 

abstraction over the messaging technologies MSMQ and RabbitMQ. As such it brings a lot of the application-specific 

logic closer to the programmer in an easy-to-configure manner. 

Below follows a few of the benefits of having MassTransit as opposed to having raw access to the transport and 

building everything directly on top of the transport. 

3.8.1 Sagas 

Sagas is a coordination mechanism in distributed systems that helps with checkpointing. Often Sagas listen for events 

or messages and reacts on them by sending further messages; what the outgoing messages are may depend on contextual 

information and questions; such as ‘How long ago was this orchestration started?’ 

3.8.2 Threaded Consumers 

Multiple concurrent receives possible. 

3.8.3 Exception Management 

If your connection to the message broker or queue server goes down, MassTransit takes care of trying to reconnect 

and deal with those failures, so that you don’t have to. 

3.8.4 Retries & Poison Messages 

MassTransit implements some level of generic exception handling for your consumers: upon complete failure from 

your application to deal with a message, it’s moved to an error queue which allows you to inspect the message and 

requeue it. 

If exceptions are thrown from consumers, MassTransit by default performs a number of retries by requeueing the 

message, before moving it to the error queue. 

3.8.5 Transactions 

Currently only supported on MSMQ, transactions allow you to join a dequeue operation with a database operation 

inside of a transaction and have them execute with ACID properties. 

3.8.6 Serialization 

How do you format a message over the wire? How to handle DateTime (Unspecified, Local, Utc)? How to handle 

decimal numbers? MassTransit has already thought about it an implemented sensible defaults. MassTransit provides 

a number of serializers, including BSON, JSON, XML and Binary. 

3.8. What does MassTransit add on top of MSMQ and RabbitMQ? 37


3.8.7 Headers 

Manufacturing a header and using a common envelope format can be a nitty-gritty afair until things stabilize. 

MassTransit has a documented format that has been tested with billions of messages. Furthermore, the envelope 

in use allows buses on other nodes to reply using the source address and perform other messaging patterns more 

easily. 

3.8.8 Consumer Lifecycle 

MassTransit handles the creation and disposal of your consumers and doesn’t unsubscribe from a queue/exchange until 

all consumers, consuming specifically the messages that cause the exchange/queue binding, have been unsubscribed. 

Also MassTransit handles durable and transient subscriptions and their semantics. 

3.8.9 Routing 

MassTransit implements a subscription service over dumb transports such as MSMQ and intelligent exchange-queue 

bindings for smart transports like RabbitMQ. This service communicates in a prioritized band called the Control Bus. 

3.8.10 Rx integration 

Interested in using Reactive Extensions to consume? MassTransit gives you this. 

3.8.11 Unit Testability 

The loopback transport is an in-memory transport that allow you a certain freedom in your integration tests (end-to-end 

in a local service). 

Furthermore, the TestFactory allows you to easily set up both loopback and real transport-based unit tests for your 

consumers. 

The code-base of MassTransit at https://github.com/MassTransit/MassTransit contains a large number of well written 

tests that service both as verification of functionality and examples for your own unit tests. 

3.8.12 Fluent NHibernate Integration 

Easily map and register your Sagas with Fluent NHibernate and let MassTransit handle the transaction boundary of 

your Saga, while giving your application easy access to the data in the saga. 

In this case you further have the option of unit testing your sagas using Fluent NHibernate using an in-memory SQLite 

database, which will make your tests run smooth like a mountain river. 

3.8.13 Routing & Static Routing 

The routing engine is state-of-the-art, using the Rete Algorithm:http://en.wikipedia.org/wiki/Rete_algorithm with Stact 

- the .Net actor framework. 

If you want to route differently than the default per-type routing, MassTransit will allow you to do this easily. 



3.8.14 Hackable 

If you feel like extending MassTransit with a Transport, Serializer or Service; the interfaces have small surface areas 

and we’re here to help you (both on github and in MassTransit-discuss). 

3.8.15 Diagnostics 

Using BusDriver, you can diagnose and inspect any bus on the network by communicating with it over the control bus. 

3.8.16 Tracing 

Using the tracing functionality you can get very detailed timings of when and where things were consumed, how long 

the receive took, how long the consume took and what exceptions were thrown if any. 

3.8.17 Monitoring 

Using the System.Diagnostics namespace and Performance Counters, you can let your operations team know how 

your applications are doing; message rates and health status. 

3.8.18 Distributor 

Using the distributor you can create load-based routing, thereby maximizing the use of your computers. 

3.8.19 Timeout Service 

You can schedule persistent callbacks/timeouts in your sagas that allow your application to wake up after e.g. a 

scheduled SLA limit. 

3.8.20 Encryption 

Using the PreSharedKeyEncryptedMessageSerializer you get pre-shared key Rijndael encryption. 

3.9 Defining Sagas using the Saga State Machine 

Sagas are one of the more powerful features in MassTransit, allowing complex state and behavior to be defined using 

a fluent syntax. 

3.9.1 What is a saga? 

A saga is a long-lived transaction managed by a coordinator. Sagas are initiated by an event, sagas orchestrates events, 

and sagas maintain the state of the overall transaction. They are designed to manage the complexity of a distributed 

transaction without locking and immediate consistency. They manage state, and track compensations that are required 

if a partial failure occurs. 

We didn’t create it, we learned it from: 

Cornell paper: http://www.cs.cornell.edu/andru/cs711/2002fa/reading/sagas.pdf 

3.9. Defining Sagas using the Saga State Machine 39


Arnon Rotem-Gal-Oz’s book chapter: http://www.rgoarchitects.com/Files/SOAPatterns/Saga.pdf 

3.9.2 Defining a Saga 

There are two ways to define a saga using MassTransit. The first approach is similar to creating a _consumer_ and 

uses interfaces on a class to define the messages that can initiate, orchestrate, or be observed by a saga instance. The 

second approach creates a state machine from a class definition that defines the events, states, and actions that make 

up the state machine. 

3.9.3 Defining a Saga Using the State Machine Syntax 

To define a saga using the state machine, a class that inherits from SagaStateMachine must be created. 

1 public class AuctionSaga : 

2 SagaStateMachine, 

3 ISaga 

4 { 

5 static AuctionSaga() 

6 { 

7 Define(() => 

8 { 

9 // the state machine behavior is defined here 

10 }); 

11 } 

12 public Guid CorrelationId { get; set; } 

13 public IServiceBus Bus { get; set; } 

14 } 

Shown above is an empty definition of a saga state machine. This is just the start, however, as there is much more to be 

done. The CorrelationId is the Guid assigned to the saga when it is created. The _IServiceBus_ property is set before 

any methods on the saga instance are called, allowing it to be used by the event handlers defined in the saga. 

First, we need to declare the valid states for the saga. There are two predefined states, _Initial_ and _Completed_, 

both of which must be included in the saga definition. Any states required by the saga also need to be added. Some 

example states are shown below. 

1 public static State Initial { get; set; } 

2 public static State Completed { get; set; } 

3 public static State Open { get; set; } 

4 public static State Closed { get; set; } 

As you see, the states are added as public static properties of type _State_. This allows the states to be used in code as 

properties, instead of relying on strings or other symbols. 

Now, let’s define some events to go along with those states. 

1 public static Event Create { get; set; } 

2 public static Event Bid { get; set; } 

Just like states, events are defined as public static properties on the saga class. The generic type specified for the event 

is the message type associated with the event. When the saga is subscribed to the bus, the message types for the events 

are subscribed. 

The messages need to be linked to the saga instance in some way so the proper messages are delivered. The messages 

are shown below. 



1 public interface CreateAuction : 


3 { 

4 string Title { get; } 

5 string OwnerEmail { get; } 

6 decimal OpeningBid { get; } 

7 } 

When an auction is created, a CreateAuction command is sent to the endpoint where the saga is subscribed. Since 

the message is correlated by Guid, the CorrelationId of the message will be used as the CorrelationId of the saga by 

default (this can be overridden as well). 

1 public interface PlaceBid 

2 { 

3 Guid BidId { get; } 

4 Guid AuctionId { get; } 

5 decimal MaximumBid { get; } 

6 string BidderEmail { get; } 

7 } 

For the bid message, we want to have a unique identifier for the bid, so we have a BidId on the message. We also need 

the AuctionId so that the message can be delivered to the proper saga instance. 

Now that we have defined the messages that are associated with the events defined in the saga, we need to specify the 

behavior of how and when those events can be handled. To define the behavior, we need to add code to the Define call 

in the static initializer of the saga class as shown. 


2 { 


4 { 

5 Initially( 

6 When(Create)); 

7 During(Open, 

8 When(Bid)); 

9 }); 

10 } 

The linkage above is pretty simple, but it defines some important characteristics of the saga. First, based on the 

definition above, we can see that the Create event is only accepted when the saga is in the _Initial_ state (which is the 

default for newly created saga instances). When an event is handled in the initial state, a message for which there is 

not an existing saga will create a new saga instance. 

A saga instance can only be created by events that appear in the Initially section. 

_NOTE: Initially() is an alias that is equivalent to specifying During(Initial)._ 

The During statement defines the events that are accepted in the state specified. In this case, the Bid event is allowed 

while the saga is in the Open State. Since the Bid event is not accepted in the Initial state, it cannot be used to create 

a new saga and will result in an error being logged (which should move the message to the error queue and publish a 

Fault message in response to the command). 

The Bid event is a special case, however, since the message is not correlated by a Guid. In order to deliver the message 

to the proper saga instance, we need to define the relationship between the message and the saga. This is done using 

the Correlate method, as shown below. 


2 { 


4 { 



5 Correlate(Bid) 

6 .By((saga,message) => saga.CorrelationId == message.AuctionId); 

7 }); 

8 } 

By defining the correlation, the proper filter expressions are created to load the existing saga instance for the message. 

It is important to realize that these translate directly into LINQ expressions that are passed to the saga repository for 

loading the saga instance, so depending upon your repository implementation you may have to tweak the syntax to get 

the proper result for your database provider. In most cases, a one-to-one relationship as shown above is your best bet. 

NOTE: Since the CreateAuction message is correlated by Guid, the default correlation is used. 

Now we need to define some behavior to happen when the events occur. We’ve already defined the events, we just 

need to link up some behavior. 


2 { 


4 { 

5 Initially( 

6 When(Create) 

7 .Then((saga,message) => 

8 { 

9 saga.OpeningBid = message.OpeningBid; 

10 saga.OwnerEmail = message.OwnerEmail; 

11 saga.Title = message.Title; 

12 }) 

13 .TransitionTo(Open)); 

14 }); 

15 } 

16 // 

17 public decimal OpeningBid { get; set; } 

18 public string OwnerEmail { get; set; } 

19 public string Title { get; set; } 

Two simple behavior steps have been defined above. The first, an anonymous method called with the saga instance and 

the message, initializes some properties on the saga. The second transitions the state of the saga to Open. Properties 

were also added to store the auction details that were provided in the CreateAuction message. 


2 { 


4 { 

5 During(Open, 

6 When(Bid) 

7 .Call((saga,message) => saga.Handle(message), 

8 InCaseOf() 

9 .Publish((saga,message,ex) => new OutBid(message.BidId)))); 

10 }); 

11 } 

12 void Handle(PlaceBid bid) 

13 { 

14 if(!CurrentBid.HasValue || bid.MaximumBid > CurrentBid) 

15 { 

16 if(HighBidder != null) 

17 { 

18 Bus.Publish(new Outbid(HighBidId)); 

19 } 

20 CurrentBid = bid.MaximumBid; 



21 HighBidder = bid.BidderEmail; 

22 HighBidId = bid.BidId; 

23 } 

24 else 

25 { 

26 throw new UnderBidException(); 

27 } 

28 } 

29 // 

30 public decimal? CurrentBid { get; set; } 

31 public string HighBidder { get; set; } 

32 public Guid HighBidId { get; set; } 

Above, the behavior for accepting a bid is defined. If the bid received is higher than the current bid, the current bid 

is updated and the high bidder information is stored with the saga instance. If there was a high bidder, a message is 

published indicating the a previous bidder was outbid, allowing actions to be taken such as sending an email to the 

previous high bidder. If the new bid is too low, and exception is thrown which is caught by the InCaseOf method. 

This specifies an exception handler for the Call method. Multiple exception handlers can be specified and they are 

evaluated in a chain-of-command order where the first one that matches the type (IsAssignableFrom) is invoked. 

The use of the Bus property is also demonstrated in the Handle method, as it is used to publish the outbid message. 

3.9.4 Combining Events (think Fork/Join) 

In some cases, you may want to create a saga that orchestrates several child sagas or initiate multiple concurrent 

commands and continue processing once all of the commands have been acknowledged. This can be done using a 

clever construct known as Combine(). For example, the saga below sends two requests and handles the response to 

each request separately. An additional Combine statement signifies that the two events have completed and triggers a 

third event on the saga instance. 

1 static SupervisorSaga() 

2 { 


4 { 

5 Initially( 

6 When(Create) 


8 { 

9 saga.PostalCode = message.PostalCode; 

10 }) 

11 .Publish((saga,message) => new RequestPostalCodeDetails(saga.PostalCode)) 

12 .Publish((saga,message) => new RequestGeolocation(saga.PostalCode)) 

13 .TransitionTo(Waiting)); 

14 

15 During(Waiting, 

16 When(PostalCodeDetailsReceived) 


18 { 

19 saga.City = message.City; 

20 saga.State = message.State; 

21 }), 

22 When(GeolocationReceived) 


24 { 

25 saga.Latitude = message.Latitude; 

26 saga.Longitude = message.Longitude; 

27 })); 



28 

29 Combine(PostalCodeDetailsReceived, GeolocationReceived) 

30 .Into(ReadyToProceed, saga => saga.ReadyFlags); 

31 

32 During(Waiting, 

33 When(ReadyToProceed) 


35 { 

36 saga.Bus.Publish(new PostalCodeDetails(...)); 

37 }) 

38 .Complete()); 

39 }); 

40 } 

41 // 

42 public int ReadyFlags { get; set; } 

43 public static Event Create { get; set; } 

44 public static Event PostalCodeDetailsReceived { get; set; } 

45 public static Event GeolocationReceived { get; set; } 

46 public static Event ReadyToProceed { get; set; } 

The combine method declares a set of events that must be triggered before the combined event is triggered. In this 

case, the ReadyToProceed event is fired when the two separate result messages have both been received. The reception 

and handling of those messages is done separately as each individual response is received. 

This is a pretty simple example of the saga, but with this great power comes great responsibility. 

(and with that, I’m too tired to continue for now and must rest) 

3.9.5 Subscribing to the Saga 

Once the saga has been defined, it is subscribed to the bus using the Saga subscription method. 


2 { 


4 { 


6 { 

7 sbc.ReceiveFrom("loopback://localhost/my_saga_bus"); 

8 sbc.Subscribe(subs => 

9 { 

10 subs.Saga(new InMemorySagaRepository()) 

11 .Permanent(); 

12 }); 

13 }); 

14 } 

15 } 

NOTE: The example above uses an in-memory transport and saga repository, which is not durable. It is shown 

for testing purposes only. There is a library for use with NHibernate provided with MassTransit, called MassTransit.NHibernateIntegration. 

It uses FluentNHibernate with NHibernate currently. 

3.10 Routing of Messages in MassTransit 

How are messages routed? 



3.10.1 RabbitMQ Routing Conventionns 

As we were building in the RabbitMQ support into MassTransit, we tried to follow the best practices for RabbitMQ 

at the time. Also, since C# is a strongly typed language, we have tried to make the most of that as well. MassTransit 

follows a routing scheme that is based on the type of the message. All messages published in MassTransit are routed 

by the Message Type. In our case the Message Type is going to be the .Net type of the message class. 

Another goal was leveraging RabbitMQ for as much of the routing logic possible. With MSMQ we had to manage 

the routing logic ourselves and that added quite a bit of code to the project. But with RabbitMQ’s advanced routing 

features we hoped we could excise that piece of the system. 

To achieve that we devised a routing system that leaned on RabbitMQ’s concepts of bindings and exchanges. By 

doing so the routing logic has been completely moved to RabbitMQ, which has lead to us also working well with 

RabbitMQ’s clustering support giving us more HA scenarios as well. 

Let’s see the story of the following message classes 

public class PingMessage { ... } 

public interface LiteCustomerData { ... } 

public class FullCustomerData : LiteCustomerData { ... } 

Next we will see what happens when you subscribe to any of these messages. 

A note about RabbitMQ. You send to exchanges in RabbitMQ. You receive messages from queues. So how the hell 

do messages get anywhere? That’s where bindings come into play. You bind a queue to an exchange. That way one 

exchange can service multiple queues. This abstracts the sending of the message from the target queue. Pretty cool, 

eh? Ok, anyways. 

MassTransit creates an exchange for each message type. So in the three messages above you would see three exchanges. 

We also set up a pattern where we bind exchanges to exchanges from the most specific to the most general. 

In this example that would be: 

PingMessage 

FullCustomerData -> LiteCustomerData 

Note: A word about Exchange to Exchange bindings. It is a RabbitMQ only feature. Exchange queue. To limit the 

amount of RabbitMQ churn we have established a directly bound exchange to your queue. This lets you come on and 

off the network with little impact to the flow of messages. 1 

If you are leveraging our interface based messaging with a message class like 

public class MyMessage : IMessageAA {} 

You would see two exchanges ‘MyMessage’ and ‘IMessageAA’. You will also see an exchange to exchange binding 

from ‘MyMessage’ to ‘IMessageAA’ (from concrete to the interface). If you subscribet to the concrete type you get a 

binding to ‘MyMessage’ if you subscribe to ‘IMessageAA’ you get a binding to ‘IMessageAA’. 

NOTE: Why are we doing this? 

3.11 What is the Data Bus? 

The data bus is the instance of IServiceBus that you will work with day in and day out. It is the instance that listens 

at msmq://localhost/servicea that you configured at start up. This is typically the one you want set to 

transactional queues and want to be careful about just randomly purging. 

1 http://blog.springsource.com/2011/04/01/routing-topologies-for-performance-and-scalability-with-rabbitmq/ 

3.11. What is the Data Bus? 45


3.12 What is a Control Bus? 

Warning: The existing ControlBus configuration method is being removed. Please read below for the replacement 

The idea of the control bus is one that responds to control messages. That is to say, not the messages and events that 

are running your business. It is recommended that the control messages also be sent on a separate Endpoint or in 

our case a different RabbitMQ Queue or MSMQ Queue. 

By setting the control bus up on a different Endpoint control messages can’t get blocked by data messages and vice 

versa. We use this to do various things such as reload configuration data, clear caches, or check on the health of our 

distributed services. 

Note: We recommend doing a purge before startup of the queue to make sure old/stale control messages are not 

consumed. 

1 var controlBus = ServiceBusfactory.New(sbc => 

2 { 

3 sbc.SetPurgeOnStartup(true); 

4 

5 //other configuration code 

6 }); 

Inspiration: 

http://www.eaipatterns.com/ControlBus.html 

3.13 Inheritance and Message Class Design 

That said, I would advise you to think about the following things: 

1. Interface-based inheritance is OK 

2. Class-based inheritance is to be approached with caution 

3. Composing messages together ends up pushing us into content-based routing which is something we don’t 

recommend 

4. Message Design is not OO Design (A message is just state, no behavior) There is a greater focus on interop and 

contract design. 

5. As messages are more about contracts, we suggest subscribing to interfaces that way you can easily evolve the 

implementation of the message. 

6. A big base class may cause pain down the road as each change will have a larger ripple. This can be especially 

bad when you need to support multiple versions. 

3.14 Companies Using MassTransit 

3.14.1 Company Name 

How are you using it. Transport Choice Other Comments 



3.14.2 Academy Mortgage Corporation 

3.14.3 Federal Home Loan Bank of Topeka 

Using MassTransit to support the internal integration of bank processes. 

Using: MSMQ 

3.15 Serialization Options 

Using NHibernate terminology 

3.16 Logging in MassTransit 

Logging in MassTransit is done with the de facto logging tool ‘log4net.’ This tool was chosen for its many 

years of battle hardened code and ease of use. You can find out more about log4net and its configuration at 

http://logging.apache.org/log4net 

Like NHibernate’s ‘NHibernate.SQL’ where all of NHibernate’s generated sql is logged, MassTransit has a log named 

‘MassTransit.Messages’ where all of the message traffic is logged. This logging looks like: 

RECV:{Address}:{Message Id}:{Message Type Name} SEND:{Address}:{Message Name} 

3.16.1 Logging with MassTransit.Log4Net 

First you need to get the latest MassTransit.Log4Net from NuGet or download it from 

https://nuget.org/packages/MassTransit.Log4Net. 

Then add logging to your service bus initialization. 

using MassTransit.Log4NetIntegration; 

XmlConfigurator.Configure(); 

ServiceBus = ServiceBusFactory.New(sbc => 

{ 

/* usual stuff */ 

sbc.UseLog4Net(); 

}); 

The easiest way to configure logging is through the web.config or app.config. 

 

 

 

 

 

 

 

 

 

 

3.15. Serialization Options 47


 

 

 

 

 

 

 

 

This will log to MassTransit.log in the root folder. There are a lot more configuration options explained at 

http://logging.apache.org/log4net/release/manual/configuration.html. 

3.16.2 Logging with MassTransit.NLog 

First you need to get the latest MassTransit.NLog for NuGet or download it from 

https://nuget.org/packages/MassTransit.NLog 

Then add logging to your service bus initialization 

The easiest way to configure logging is through ???? (thoughs for the NLog community?) 

3.17 Performance Counters 

Masstransit has support for updating Windows performance counters. Chris has a post introducing them - Performance 

Counters Added to MassTransit. http://lostechies.com/chrispatterson/2009/10/14/performance-countersadded-to-masstransit/ 

3.17.1 User Permissions 

The user running your mass transit enabled application will need access to update the performance counters. 

HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib 

If Masstransit does not detect the performance counters it wishes to write to it will attempt to create them. If the user 

credentials do not have administrative access likely they will not have the ability to create the performance counters 

and errors will be logged. 

3.17.2 Windows Installer 

When deploying your mass transit enabled application it is possible to have Windows Installer create your performance 

counters for you. Below is Xml used by Wix 3.0 to define the Masstransit performance counters. 

 

... 

 


Threads” Help=”The current number of threads receiving messages.” Type=”numberOfItems32”/> 

 

 

 

 

 

 

3.18 Standard Services 

Note: needs to be cleaned up 

Installing MSMQ 

run the install_msmq.bat run the server_install_msmq.bat You can also do this form C# code when configuring the 

bus. Subscription Service 

• Installation 

MSMQ should be installed (see Installing MSMQ) By default this service is set to run in-memory store Run the 

create_[servicename]_queue.vbs Go to the queues Properties>Security tab and ensure to give ?local administrators? 

Full Access. By default MSMQ only gives YOU access. Leave all other permissions at default. Copy the files 

wherever you want them run ?SubscriptionServiceHost.exe /install? Health Service 





wherever you want them run ?SubscriptionServiceHost.exe /install? Timeout Service 





wherever you want them run ?SubscriptionServiceHost.exe /install? Health, and Subscription Services can be as one 

?Runtime? services instead of distinct services 

MSMQ should be installed The service will attempt to create any missing queues Copy the files to where you want 

them Edit the MassTransit.RuntimeServices.exe.config to point to the right connection string and subscriptions queue 

run ?MassTransit.RuntimeServices.exe /install? To set these services up to run with a persistant (MSSSQL) store 

3.18. Standard Services 49


A SQL Server 2008 database installed. If it is not on the local drive, please follow the setup considerations below. 

Mass Transit will try to install to your local database. If you need it to install to a different one, please edit the 

?SET INSTANCE=(local)? in the _install.cmd file and set that to a database instance you would like to use. Ensure 

you have permission to create databases on that instance. Open the servicename.castle.xml in an editor. Find the 

hibernate.connection.connection_string in the facilities section of the file. Edit the server location. If you would like 

to set a more secure password for the login, please update it in the SQLScriptsCreateUserAccountLoginDDL.sql and 

also in the hibernate connection string from the step before this. 

3.19 Runtime Services 

The MassTransit framework also comes with several services which can be run to provide additional functionality, as 

well as examples of how to build services that either extend bus behavior or provide a general service. These services 

are: 

3.19.1 Subscription Service 

Note: This is only needed for MSMQ or other transports that have no routing capabilities 

Because MSMQ has anemic routing capabilities MassTransit originally shipped with a central subscription registry 

that all of the busses could listen to, to learn when a new ?subscription? would come online. As of 2.0 the Msmq- 

MulticastSubscription manager provides similar functionality while removing the need for a single point of failure. 

For users of RabbitMQ this service is not needed as the RabbitMQ approach leverages its excellent message routing 

capabilities. 

Warning: The MsmqMulticastSubscription should not be considered for production yet. I doesn’t persist to disk 

so a restart can mean a wipeout of subscriptions. If we had a way to write these to disk this would be a more robust 

option. We use it mostly for demo / unit testing. 

3.19.2 Timeout Service 

This service provide an easy event based way to register timeouts for your sagas. These timeouts are persisted to disk 

and will survive restart. 

3.19.3 Health Service 

Attempts to track all known endpoints and monitor their status for up/down. Currently is very remedial. 

3.20 Videos 

There are several videos of presentations featuring MassTransit. 

Event Driven Architecture Presented at the North Dallas .NET User Group in February, 2010 by Chris Patterson. 

http://www.drowningintechnicaldebt.com/ShawnWeisfeld/archive/2010/02/04/event-driven-architecture-by-chrispatterson-north-dallas-.net.aspx 

Others I?m sure, I just need to find them and link them here. 



3.21 What is MassTransit? 

MassTransit (MT) is a framework for creating distributed applications on the .Net platform. MT provides the ability 

to subscribe to messages by type and then connect different processing nodes through message subscriptions building 

a cohesive mesh of services. 

3.21.1 A bit of the back story? 

We are often asked why MassTransit was created, well here’s the story. :) 

In 2007, Chris Patterson (@phatboyg) and Dru Sellers (@drusellers) met, for what Dru thinks is the first time, at the 

first Alt.Net conference. It was at this conference that Chris and Dru not only realized that they had a lot of the same 

problems that they needed to solve, but also how much the standard tooling being provided by Microsoft just didn’t 

fit their needs. Surrounded by the best and brightest in .Net the energy to build better tooling that supported testable 

processes, was aware of the latest advances in tooling, libraries, and coding practices; they decided that a better option 

must exist. After searching the .Net ecosystem for a tool that would help them achieve goals, the only real option 

was the venerable NServiceBus (NSB). After reviewing NSB, it was determined that the only real IoC support was 

for Spring.Net, and that the NSB wasn’t quite ready for external contributors to come in. Therefore, they decided to 

embark on the quixotic trek of building their own service bus. 

Initially the goals were as much about learning about distributed message based systems, as well as building something 

both of their companies could use. The first commit was pushed to GoogleCode on 12/26/2007, and shortly there after 

both Dru and Chris went to production with MT and both of their companies have had success in getting value out of 

their efforts. 

Now 4 years later, Chris and Dru continue to push forward on their Journey, and have been joined by Travis Smith 

(@legomaster). The near future should bring much for the MT community as RabbitMQ and ActiveMQ support take 

front center with the quest for Mono support becoming increasingly important. 

3.21.2 The Philosophy 

First and foremost, we are not an Enterprise Service Bus (ESB). While MT is used in several enterprises its not a swiss 

army knife, we are not driven by sales to be a million features wide, and an inch deep. We focus on a few key concepts 

and try to make them as robust as possible. 

We don’t do doodleware, you won’t find a designer, we are all about the keyboard samurais, the true in-the-trenches 

coder. That’s who we are, and those are our friends. If you want to draw, use a whiteboard. 

We don’t do FTP->WS-deathstar->BS (not that you can’t, its just not in the box). We focus on the experience of using 

one transport in a given environment, and we try to make it as smooth as possible. 

MT is built to be used inside the firewall, its not built to be used as a means to communicate with external vendors (it 

can be, again its just not in the box), its meant to be used for getting your corporate services talking to each other and 

making building internal software easier. 

3.22 Correlation 

In MassTransit we can mark a message as correlated by implementing the interface 

public interface CorrelatedBy 

{ 

TKey CorrelationId { get; } 

} 

3.21. What is MassTransit? 51


Ok, that?s great, but what does it mean to be correlated? In short it means that this message is a part of a larger story. 

For instance, you may have a message that says ?New Order (Item:Hammers; Qty:22; OrderNumber:45)? and there 

may be another message that is a response to that message that says ?Order Allocated(OrderNumber:45)?. In this case 

the order number is acting as your correlation id, it ties the messages together. 

NOTE: Since most transactions in a system will ultimately be logged and wide-scale correlation is likely, it is recommended 

to use a Guid type. The Magnum library has a CombGuid that is clustered-index friendly for SQL Server, 

making it as efficient to insert as an integer/bigint key. Just use CombGuid.Generate() to get a new one and be happy. 

Note, this is the same algorithm that NHibernate uses for guid.comb primary keys. 

Also, sagas are always correlated with Guids, so any messages that will interact with the saga should use a Guid 

correlationId. 

3.23 Handling errors 

Handling errors in your consumers is quite easy. 

Let’s suppose that you have a message containing a some data that needs to be saved to a database. In the event of a 

failure to save that data, that code throws an exception say, SqlErrorException or someother monkey business. 

What do you do? 

The easiest thing is to just let the exception bubble out of your consumer method and MassTransit will automatically 

catch the exception for you, and then, by default, will retry the message 5 times for you. After 5 attempts it will move 

the error to the ‘error queue’. From there you will need to inspect the message in the error queue and decide what you 

need to do. 


CHAPTER 4 

Troubleshooting MassTransit 

4.1 Issues and possible solutions 

• Messages are not being received by bus instances 

4.1.1 Possible solutions 

1) Assuming bus instances are configured to use MSMQ transport and are using multicast. Machines with multiple 

NICs (either hardware or virtual devices) need to have MSMQ binding configured in the following way : 

At the registry key [HKEY_LOCAL_MACHINESOFTWAREMicrosoftMSMQParameters] 

• Add new string value with name “BindInterfaceIP”. As a value enter machine’s IP address 

• Add new string value with name “MulticastBindIP”. As a value enter machine’s IP address 

• Restart MSMQ service 

At the end the registry entries should look like this : 

References 

• http://support.microsoft.com/kb/974813 

• http://technet.microsoft.com/en-us/library/cc756156(v=ws.10).aspx 

Confirmed to work in Windows Vista SP2 and Windows Server 2008 R2 environments 

53


54 Chapter 4. Troubleshooting MassTransit

CHAPTER 5 

Advanced MassTransit Concepts 

Advanced notes. 

5.1 Interop with MassTransit (Routing RFC) 

MassTransit’s serializers do the main work of formatting the data that goes over the wire. Below is the message format 

that everything is mapped to/from: 

string RequestId 

string ConversationId 

string CorrelationId 

string DestinationAddress 

DateTime? ExpirationTime 

string FaultAddress 

IDictionary Headers 

object Message 

string MessageId 

IList MessageType 

string Network 

string ResponseAddress 

int RetryCount 

string SourceAddress 

This is a minimal message: 

Which translates to these required properties: 

• message 

• messageType 

• destinationAddress 

MessageType is a list of urns. See MessageUrnSpecs for the format. Informally, it’s like this: 

urn:message:NAMESPACE1.NAMESPACE2:TYPE 

‘retryCount’, ‘headers’ will be defaulted. 

55


5.2 The Distributor 

5.2.1 What is the distributor? 

The Distributor in MassTransit provides the ability to allocate work across multiple workers when using MSMQ. This 

would be similar to using completing consumers with other transports, such as RabbitMQ. If you are not using MSMQ, 

the distributor is not suggested for use. 

The distributor works by consuming the message (TMessage) that the workers will be consuming, checking to see 

if a worker is free, then sending a Distributed message directly to the worker. This is done within 

MassTransit, so you are just required to register your configuration and the rest is taken managed by MassTransit. 

5.2.2 How do I set up the producer? 

When configuring the bus, use UseDistributorFor() per the example below... 

Replace MyMessageType with the message you want distributed across your workers. 

5.2.3 How do I set up workers? 

The configuration for workers is similar, ImplementDistributorWorker(consumerFactory). The consumer 

factory should return an action for consuming message, if apporiate. 

5.2.4 How can I alter the scheduling algo in use? Can I alter it at all? 

The default scheduling is not configuratable, but implementing a IWorkerSelectionStrategy interface and registering it 

with the Producer will allow you to use your own 

56 Chapter 5. Advanced MassTransit Concepts


5.2.5 Does the distributor only schedule inside of a single bus, or does it work 

across the network? 

Distributed messages are intercepted at the source bus, and distributed to the workers from there. 

5.2.6 Can I use the distributor as a router inside of a service bus that would serve 

similar to a gateway/message broker? 

In theory yes. Content based routing can be supported with the IWorkerSelectionStrategy, however, we suggest that 

implementors consider not using this for content based routing. 

5.2. The Distributor 57


58 Chapter 5. Advanced MassTransit Concepts

CHAPTER 6 

Samples 

6.1 Starbucks 

This sample is based on: http://www.enterpriseintegrationpatterns.com/ramblings/18_starbucks.html 

Note: Do not run both the pre-built services and the subscription manager GUI at the same time. The GUI has the 

same services in one WinForm app for the purposes of demoing the code base. If both are on they will steal messages 

from each other. 

6.1.1 To Run 

Open up ~/Samples/Starbucks/Starbucks.sln 

Start the following projects 

/Starbucks.Barista 

/Starbucks.Cashier 

/Starbucks.Customer 

Enjoy. 

6.2 Heavy Load 

This sample attempts to push the limits of the infrastructure, and can be run as a gauge on your hardware?s capacity 

to perform. 

6.3 Open All Night 

This sample attempts to be a long term test of the infrastructure, and can be set to run for a set number of time. It 

works with the prebuilt services as well, to both quickly test and to put through their paces over time. 

6.3.1 Overview 

This sample is used to both test the pre-built services and perform long running (multi-hour) stress tests. 

59


6.3.2 To Run 

Open up $/Samples/OpenAllNight/OpenAllNight.sln 

Start the following projects (in order) 

/MassTransit/RuntimeServices 

/OpenAllNight 

Starbucks - This sample attempts to be a complete sample of a message based solution as well as a concrete example 

of Gregor Hophe’s article “Starbucks doesn’t use two phase commit. 

HeavyLoad - This sample attempts to push the limits of the infrastructure, and can be run as a gauge on your hardware’s 

capacity to perform. 

OpenAllNight - This sample attempts to be a long term test of the infrastructure, and can be set to run for a set number 

of time. It works with the prebuilt services as well, to both quickly test and to put through their paces over time. 

60 Chapter 6. Samples

CHAPTER 7 

MassTransit Learning Series 

For many developers, asynchronous messaging is a new pattern. In this series of learning exercises, developers will 

learn how to create applications using asynchronous messaging with MassTransit. 

This series covers using MassTransit with RabbitMQ. The skills, however, are relevant regardless of which messaging 

transport is used. There are some operational differences between the transports, but the programming interface 

remains the same. 

It is recommended that the learning exercises be completed in order, as more advanced exercises build upon skills that 

were learned in the earlier exercises. 

7.1 Requirements 

To perform the learning exercises, the following applications should be installed. 

Visual Studio 2010 Service Pack 1 NuGet Package Manager (see Installing NuGet) 

NuGet requires an internet connection to download packages. 

7.2 Creating Your First Consumer 

To create your first consumer, create a new project using Visual Studio. The project should be configured to use .NET 

4.0, and should be created as a class library. In this exercise, the project name is “LearningMT.OrderConsumer”. 

61


Once the project is created, delete the Class1.cs file which was automatically created. 

A reference to MassTransit must now be added, which you will do using the NuGet package manager. To add the 

reference, right-click on the project References and select Manage NuGet Packages from the context menu. 

Select the Online section on the left, and enter MassTransit into the search box. Once the results are displayed, select 

the MassTransit.RabbitMQ package and click Install. This will install the RabbitMQ transport, and its dependencies, 

62 Chapter 7. MassTransit Learning Series


which include MassTransit itself. You many have to click the license acceptance box to continue. 

Once the package manager is finished downloading the package and adding the references, close the package manager 

and verify that the references have been added to your project. Note that some unneeded references added by Visual 

Studio have been removed. 

7.2. Creating Your First Consumer 63


7.2.1 Adding the Message Contract 

Using MassTransit, there are several ways that message subscriptions can be added to a service bus instance. In this 

exercise, you will be creating a message consumer. Other types of message subscriptions include message handlers, 

consumer instances, and sagas. 

Before creating your consumer, however, you must first define a message. Using MassTransit, messages should be 

defined using C# interfaces. To create a message, add a new interface to the project called SubmitOrder. 

1 using System; 

2 using MassTransit; 

3 

4 public interface SubmitOrder : 


6 { 

7 DateTime SubmitDate { get; } 

8 string CustomerNumber { get; } 

9 string OrderNumber { get; } 



10 } 

The interface defines the message contract that the consumer accepts. In this exercise, you are creating a service that 

accepts the SubmitOrder command. Command message contracts are defined and owned by the service and specify 

the input requirements for the service. 

The properties on the interface are defined with getters only, because message contents are immutable. The interface 

extends the CorrelatedBy interface, specifying that a Guid should be used for message correlation. Correlation allows 

the message to be tracked from the message produder to the message consumer. 

7.2.2 Adding the Consumer Class 

A consumer in MassTransit is a class that implements one or more Consumes interfaces. To create the consumer, add 

a new class to the project called SubmitOrderConsumer as shown. 


2 

3 public class SubmitOrderConsumer : 

4 Consumes.Context 

5 { 

6 public void Consume(IConsumeContext context) 

7 { 

8 } 

9 } 

The Consume method is defined by the Consumes.Context interface, and is used by MassTransit to 

identify the message type for the consumer. At this point, the consumer has no behavior, but has enough code to 

continue the exercise. 

7.2.3 Creating a Service Bus Instance 

With the consumer class created above, you are now ready to subscribe that consumer to an instance of a MassTransit 

service bus. However, you must first create a service to host the service bus. 

Create a new class in the same project called OrderService as shown below. 


2 

3 public class OrderService 

4 { 

5 IServiceBus _bus; 

6 

7 public void Start() 

8 { 

9 _bus = ServiceBusFactory.New(x => 

10 { 

11 x.UseRabbitMq(); 

12 x.ReceiveFrom("rabbitmq://localhost/learningmt_orderservice"); 

13 }); 

14 } 

15 

16 public void Stop() 

17 { 

18 _bus.Dispose(); 

19 } 

20 } 



In the class above, two methods have been added, Start and Stop. In the Start method, the ServiceBusFactory is used 

to configure an instance of the service bus, which includes specifying the input queue for the bus instance. The Stop 

method disposes of the bus instance, which is necessary to ensure that all pending subscriber threads have completed. 

7.2.4 Testing the Service Bus Instance 

At this point, there is a lot of code written and no unit tests. To fix that, create another project in the solution called 

LearningMT.OrderConsumerTests. Once created, use the NuGet Package Manager to add NUnit to the project. (If 

you are running Visual Studio 2012/13, you may want to NuGet “NUnit TestAdapter including NUnit...framework” 

instead.) Then add a reference to your LearningMT.OrderConsumer project. Finally, NuGet “MassTransit.RabbitMQ” 

(which includes MassTransit) like you did for the original OrderConsumer project. 

After creating the tests project, create a new unit test (e.g., copy the following in to a new class), build the project, 

and then click/run “Should_create_the_service_bus” in the Test Explorer window to verify the OrderService can be 

started and stopped. (This will ensure that your project and dependencies are all setup correctly and that RabbitMQ is 

installed and configured properly as well.) Basic unit test code is shown below. 

1 using NUnit.Framework; 

2 using OrderConsumer; 

3 

4 [TestFixture] 



5 public class Starting_an_order_service 

6 { 

7 OrderService _orderService; 

8 

9 [TestFixtureSetUp] 

10 public void Before() 

11 { 

12 var orderService = new OrderService(); 

13 orderService.Start(); 

14 

15 _orderService = orderService; 

16 } 

17 

18 [TestFixtureTearDown] 

19 public void Finally() 

20 { 

21 if(_orderService != null) 

22 { 

23 _orderService.Stop(); 

24 _orderService = null; 

25 } 

26 } 

27 

28 [Test] 

29 public void Should_create_the_service_bus() 

30 { 

31 } 

32 } 

The test fixture setup and teardown code manage the creation, starting, and stopping of the service. The unit test itself 

is empty since this test is only verifying that the bus can be created. 




CHAPTER 8 

Indices and tables 

• genindex 

• modindex 

• search 

69

MassTransit Documentation - Read the Docs

Create successful ePaper yourself

Delete template?

Save as template?