LATEST VERSION: 3.6.5 - CHANGELOG
Pivotal RabbitMQ v3.x

RabbitMQ tutorial - "Hello World!"

Introduction

RabbitMQ is a message broker. In essence, it accepts messages from producers, and delivers them to consumers. In-between, it can route, buffer, and persist the messages according to rules you give it.

RabbitMQ, and messaging in general, uses some jargon.

  • Producing means nothing more than sending. A program that sends messages is a producer. We’ll draw it like that, with “P”: digraph { bgcolor=transparent; truecolor=true; rankdir=LR; node [style=“filled”]; // P1 [label=“P”, fillcolor=“#00ffff”]; }

  • A queue is the name for a mailbox. It lives inside RabbitMQ. Although messages flow through RabbitMQ and your applications, they can be stored only inside a queue. A queue is not bound by any limits, it can store as many messages as you like - it’s essentially an infinite buffer. Many producers can send messages that go to one queue - many consumers can try to receive data from one queue. A queue will be drawn like this, with its name above it: digraph { bgcolor=transparent; truecolor=true; rankdir=LR; node [style=“filled”]; // subgraph cluster_Q1 { label=“queue_name”; color=transparent; Q1 [label=“{||||}”, fillcolor=“red”, shape=“record”]; }; }

  • Consuming has a similar meaning to receiving. A consumer is a program that mostly waits to receive messages. On our drawings it’s shown with “C”: digraph { bgcolor=transparent; truecolor=true; rankdir=LR; node [style=“filled”]; // C1 [label=“C”, fillcolor=“#33ccff”]; }

Note that the producer, consumer, and broker do not have to reside on the same machine; indeed in most applications they don’t.

“Hello World”

(using the .NET/C# Client)

In this part of the tutorial we’ll write two programs in C#; a producer that sends a single message, and a consumer that receives messages and prints them out. We’ll gloss over some of the detail in the .NET API, concentrating on this very simple thing just to get started. It’s a “Hello World” of messaging.

In the diagram below, “P” is our producer and “C” is our consumer. The box in the middle is a queue - a message buffer that RabbitMQ keeps on behalf of the consumer.

(P) -> [|||] -> (C)

The .NET client library
RabbitMQ speaks AMQP, which is an open,
general-purpose protocol for messaging. There are a number of clients
for AMQP in many different
languages. We'll
use the .NET client provided by RabbitMQ.
Download the client library
package, and check its
signature as described. Extract it and copy "RabbitMQ.Client.dll" to your working folder.
You also need to ensure your system can find the C# compiler csc.exe,
you may need to add ;C:\WINDOWS\Microsoft.NET\Framework\v3.5 (change .NET version
to fit your installation) to your Path.

Now we have the .NET client binary, we can write some code.

Sending

(P) -> [|||]

We’ll call our message sender Send and our message receiver Receive.cs. The sender will connect to RabbitMQ, send a single message, then exit.

In Send.cs, we need to use some namespaces:

using System;
using RabbitMQ.Client;
using System.Text;

Set up the class:

class Send
{
    public static void Main()
    {
        ...
    }
}

then we can create a connection to the server:

class Send
{
    public static void Main()
    {
        var factory = new ConnectionFactory() { HostName = "localhost" };
        using (var connection = factory.CreateConnection())
        {
            using (var channel = connection.CreateModel())
            {
                ...
            }
        }
    }
}

The connection abstracts the socket connection, and takes care of protocol version negotiation and authentication and so on for us. Here we connect to a broker on the local machine - hence the localhost. If we wanted to connect to a broker on a different machine we’d simply specify its name or IP address here.

Next we create a channel, which is where most of the API for getting things done resides.

To send, we must declare a queue for us to send to; then we can publish a message to the queue:

class Send
{
    public static void Main()
    {
        var factory = new ConnectionFactory() { HostName = "localhost" };
        using (var connection = factory.CreateConnection())
        {
            using (var channel = connection.CreateModel())
            {
                channel.QueueDeclare("hello", false, false, false, null);

                string message = "Hello World!";
                var body = Encoding.UTF8.GetBytes(message);

                channel.BasicPublish("", "hello", null, body);
                Console.WriteLine(" [x] Sent {0}", message);
            }
        }
    }
}

Declaring a queue is idempotent - it will only be created if it doesn’t exist already. The message content is a byte array, so you can encode whatever you like there.

When the code above finishes running, the channel and the connection will be disposed.

Here’s the whole Send.cs class.

Sending doesn't work!
If this is your first time using RabbitMQ and you don't see the "Sent"
message then you may be left scratching your head wondering what could
be wrong. Maybe the broker was started without enough free disk space
(by default it needs at least 50 MB free) and is therefore refusing to
accept messages. Check the broker logfile to confirm and reduce the
limit if necessary. The configuration
file documentation will show you how to set disk_free_limit.

Receiving

That’s it for our sender. Our receiver is pushed messages from RabbitMQ, so unlike the sender which publishes a single message, we’ll keep it running to listen for messages and print them out.

[|||] -> (C)

The code (in Receive.cs) has almost the same using statements as Send:

using RabbitMQ.Client;
using RabbitMQ.Client.Events;
using System;
using System.Text;

Setting up is the same as the sender; we open a connection and a channel, and declare the queue from which we’re going to consume. Note this matches up with the queue that send publishes to.

class Receive
{
    public static void Main()
    {
        var factory = new ConnectionFactory() { HostName = "localhost" };
        using (var connection = factory.CreateConnection())
        {
            using (var channel = connection.CreateModel())
            {
                channel.QueueDeclare("hello", false, false, false, null);
                ...
            }
        }
    }
}

Note that we declare the queue here, as well. Because we might start the receiver before the sender, we want to make sure the queue exists before we try to consume messages from it.

We’re about to tell the server to deliver us the messages from the queue. Since it will push us messages asynchronously, we provide a callback in the form of an object that will buffer the messages until we’re ready to use them. That is what QueueingBasicConsumer does.

class Receive
{
    public static void Main()
    {
        var factory = new ConnectionFactory() { HostName = "localhost" };
        using (var connection = factory.CreateConnection())
        {
            using (var channel = connection.CreateModel())
            {
                channel.QueueDeclare("hello", false, false, false, null);

                var consumer = new QueueingBasicConsumer(channel);
                channel.BasicConsume("hello", true, consumer);

                Console.WriteLine(" [*] Waiting for messages." +
                                         "To exit press CTRL+C");
                while (true)
                {
                    var ea = (BasicDeliverEventArgs)consumer.Queue.Dequeue();

                    var body = ea.Body;
                    var message = Encoding.UTF8.GetString(body);
                    Console.WriteLine(" [x] Received {0}", message);
                }
            }
        }
    }
}

QueueingBasicConsumer.Queue.Dequeue() blocks until another message has been delivered from the server.

Here’s the whole Receive.cs class.

Putting it all together

You can compile both of these by referencing the RabbitMQ .NET client assembly. We’re using the command line (cmd.exe and csc) to compile and run the code. Alternatively you could use Visual Studio.

$ csc /r:"RabbitMQ.Client.dll" Send.cs
$ csc /r:"RabbitMQ.Client.dll" Receive.cs

Then run the executable

$ Send.exe

then, run the receiver:

$ Receive.exe

The receiver will print the message it gets from the sender via RabbitMQ. The receiver will keep running, waiting for messages (Use Ctrl-C to stop it), so try running the sender from another terminal.

If you want to check on the queue, try using rabbitmqctl list_queues.

Hello World!

Time to move on to part 2 and build a simple work queue.