Get started with Burrow.NET

This document page will help you to get started with Burrow.NET. Burrow.NET is a thin wrapper on RabbitMQ.Client. I hope you've already known what is RabbitMQ and been familiar with some terminologies like Exchange, Queue, Binding, Topic, RoutingKey, etc. If not, please go to http://www.rabbitmq.com/getstarted.html .

Now given that you have already installed RabbitMQ server. You should enable http://www.rabbitmq.com/management.html since it's a visual interface that can help you do alot of interesting stuff. I have problem to enable that plugin on window because I don't have the proper configuration for some reason. If you get the same problem, simply create following file in following folder : %APPDATA%\RabbitMQ

rabbitmq.config

{"[{listeners,     [{mgmt, [{port, 55672}]}]},
{default_listener, [{port, 55670}]},
{contexts,         [{rabbit_mgmt, mgmt}]}]"}

For RabbitMQ 2.8.7 32Bit Windows, I have no idea why but I have to use this config to make it work

[{listeners,     [{mgmt, [{port, 55672}]}]},
   {default_listener, [{port, 55670}]},
   {contexts,         [{rabbit_mgmt, mgmt}]}].

Restart the RabbitMQ service and you will get what you want :)

As I mentioned in the project homepage, I wanted an easy way to define Exchange name, Queue name. Those requirement are fulfilled by interface IRouteFinder. The DefaultRouteFinder will generate the following exchange name: Burrow.Exchange. For the queue names, it's depend on the messages type and the subscription names you provide when you call method Subsribe. For example, if your message name is "MessageA" and you subscribe to the queue with "MyApp" as subscription name, the DefaultRouteFinder will generate the queue name: "Burrow.Queue.MyApp.MessageA".

In the test application, the message type is "Bunny" and the subscription name is "BurrowTestApp" so the following queue need to be created: "Burrow.Queue.BurrowTestApp.Bunny"

Please open the RabbitMQ web management page, (normally it is http://localhost:55672/#/, both username and password are guest). We will create exchange, queue and bind them together.

Create exchange Burrow.Exchange:

You are at RabbitMQ management web, go to Exchanges tab, navigate to “Add a new exchange section” and enter following values

Name: Burrow.Exchange Type: direct Keep the rest as default. Hit Add exchange button.

There are 4 exchange types which are: fanout, direct, topic and headers. Please go to RabbitMQ tutorial page for more details about those exchange. In this test app, we'll use direct.

Create queue Burrow.Queue.BurrowTestApp.Bunny

Please go to Queues tab, navigate to “Add a new queue” section in the bottom and enter the above queue name to textbox “Name” and leave other fields as default, then hit Add queue button.

Bind the queue to exchange

A binding is a relationship between an exchange and a queue. This can be simply read as: the queue is interested in messages from this exchange. (http://www.rabbitmq.com/tutorials/tutorial-four-python.html). We will need to bind the queue “Burrow.Queue.BurrowTestApp.Bunny” to exchange “Burrow.Exchange”. When we publish a message, we dispatch the object to an exchange instead of a queue. However, the subscriber will subscribe to the queue. To add the required binding, please follow these steps:

• Go to RabbitMQ management web, go to Queues tab, click on the queue we want to add binding, at this time it’s “Burrow.Queue.BurrowTestApp.Bunny”
• A queue can be bound to many exchanges but we’ll bind to only 1 exchange for the Bunny message. Scroll down, at section Bindings, you’ll see something like:

• Enter “Burrow.Exchange” (without quotes) to the Exchange box
• Enter “Bunny” (without quotes) to the Routing key box
• Leave other fields empty
• Click Bind

If everything is done correctly, you will see something like the picture below when you go to the Burrow.Exchange exchange:

Run the test applications

Now, get the latest source code, compile and start the Burrow.Publisher project first, it's a simple console application that will send 10.000 Bunny objects to the queue:

var tunnel = RabbitTunnel.Factory.Create();
var sw = new Stopwatch();
sw.Start();
uint index;
for (index = 0; index < numberOfRabbitToCreate; index++)
{
    try
    {
        tunnel.Publish(new Bunny
        {
            Age = index,
            Color = "White",
            Name = "The Energizer Bunny"
        });
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex.Message);
        break;
    }
}
sw.Stop();
Console.WriteLine(string.Format("Publish {0} rabbits in {1}.", index, sw.Elapsed));

After executing the Burrow.Publisher, please go to the RabbitMQ web management, you will see there is 10.000 ready items in the Burrow.Queue.BurrowTestApp.Bunny queue.

Now we'll try to consume those messages by executing the Burrow.Subscriber project. It's also a simple console application that will asynchronously consume messages in the queue:

var tunnel = RabbitTunnel.Factory.Create();
tunnel.SubscribeAsync<Bunny>("BurrowTestApp", bunny =>
{
    var rand = new Random((int) DateTime.Now.Ticks);
    var processingTime = rand.Next(1000, 1500);
    if (bunny.Age % 5 == 0)
    {
        throw new Exception("This is a test exception to demonstrate how a message is handled once something wrong happens: Got a bad bunny, It should be put to Error Queue ;)");
    }
    System.Threading.Thread.Sleep(processingTime);
    Console.WriteLine("Got a bunny {0}, feeding it in {1} ms\n", bunny.Name, processingTime);
});

If you look at the code, you will see that there will be some exceptions to be thrown while being processed . That demonstrates how Burrow.Net handle unhandled errors by default. Here it will put the error data to exchange Burrow.Exchange.Error and eventually go to queue Burrow.Queue.Error. The logic for that can be easily changed by implement another IConsumerErrorHandler and give it to ConsumerManager which is a parameter of RabbitTunnel's constructor.

More details about those classes will be added to other Wiki pages soon. For now, I hope you have enough information to get started. The core of this project is ITunnel and TunnelFactory so those are properly the good places for you to start if you want to read the source code.

Cheers.