Up and Running with nServiceBus 1.9

nServiceBus version 1.9 is much more approachable for new developers, as compared to previous versions. This article describes how to quickly start experimenting with nServiceBus based on one of the examples, PubSub. Along the way, I also discuss some details about how nServiceBus works.

The nServiceBus PubSub sample has three parts: a server that publishes two types of messages, and two subscribers that each consumes one type of message. The PubSub sample is self-contained - it includes the code and setup scripts you'll need to easily get the solution running.

nServiceBus requires Visual Studio 2008 and the .NET Framework 3.5. You also need MSMQ installed. The next series of steps walk you through setting up MSMQ and downloading and running the nServiceBus samples.

Install MSMQ on your system:

1. Select Control Panel
2. Click Add/Remove Programs
3. Click Add/Remove Windows Components
4. Select Message Queuing
5. Select the "Common" component

Once MSMQ is installed, download nServiceBus by heading over to: http://sourceforge.net/projects/nservicebus. Then:

• Click the big download link, then click 'Download' in the downloads column of the table that appears, and download this file: NServiceBus1.9.RC1_BinariesAndSamples.zip.
• Extract the file to a folder on your system (I extracted the files to C:\bus).
• Using Windows Explorer, navigate to the NServiceBus folder.
• Install the nServiceBus queues by double-clicking the "msmq install.vbs" file.

Verify that the script successfully sets up the queues:

1. Start - Settings - Control Panel
2. Administrative Tools
3. Computer Management
4. Expand 'Services and Applications'
5. Expand 'Message Queuing'
6. Expand 'Private Queues'

You'll see a number of new queues including "client", "error", "messagebus", and "worker2".

• Navigate to the NServiceBus\Samples\PubSub folder
• Double-click the PubSub.sln file

Build the solution (select Build - Build Solution); it should compile without any problems.

Subscribers need to run first, initially, so that they can register themselves on the bus. Start subscribers one and two by double-clicking Subsriber1.exe in the NServiceBus\Samples\PubSub\Subscriber1\bin\Debug folder - do the same for Subscriber2.exe in the NServiceBus\Samples\PubSub\Subscriber2\bin\Debug folder.

With both subscribers running, start the Server - double-click Server.exe in the NServiceBus\Samples\PubSub\Server\bin\Debug folder.

Not much appears to happen on the screen once everything is running - the interesting stuff is happening on the queues. You'll see two messages in the 'subscriptions' queue (press F5 to refresh the display of messages in the queue) - one for each subscriber. The messages in the queue include the name of the queue that the subscriber uses to monitor for new messages, and include a description of the messages that a subscriber is capable of handling.

You send messages to subscribers by pressing Enter in the Server's window. The Server alternates between sending one of two types of messages whenever you press Enter; as a result, you'll notice that only one of the subscribers responds whenever you press Enter in the Server window.

This is interesting; however, it's of limited use since subscribers and servers can become unavailable at any time. Quit one of the subscribers, making its window active, and then type Q followed by Enter. Press Enter a few times in the Server window, and re-start the subscriber that you quit a few moments ago.

You'll notice that the subscriber processes queued messages as soon as it finishes initializing. How does that happen? The messages you saw earlier in the Subscriptions queue are persistent in this example, so quitting a subscriber and sending messages to it causes the messages to get queued until the subscriber picks them up.

The Server process publishes messages by looking through messages in the 'subscriptions' queue. The server attempts to match the message type it is currently sending with a subscriber that's interested in the message. If the server finds a subscriber, it publishes the message to the subscriber's queue - otherwise, it ignores the message and continues to the next message.

Let's take a look at how this works in a little more detail. Quit the Server and both the subscribers. Next, clear the following queues (right click 'Queue messages' under each queue and select 'All Tasks', then select 'Purge'): messagebus, subscriptions, worker, worker2.

Start just one subscriber (no server) and check out the subscriptions queue (press F5 to refresh the display of messages in the queue). You'll see that the queue is empty. The messagebus queue is more interesting (press F5 to refresh the display) - it contains one message.

The message label of the message in the 'messagebus' queue includes your computer/domain and username. Take a look at the message body - you'll see that this is a SubscriptionMessage to register the subscriber. When the server starts, it checks the messagebus queue and sets up subcribers, as you saw earlier, by posting new messages into the subscriptions queue. You can start the Server to see what happens to the message that's in the messagebus queue (it disappears and a new message appears in the subscriptions queue).

Configuring all of this is straightforward. Open the App.Config file in the Subscriber1 project and find the following lines:

<MsmqTransportConfig    
    InputQueue="worker"    
    ErrorQueue="error"    
    NumberOfWorkerThreads="1"    
    MaxRetries="5"
/>
    
<UnicastBusConfig DistributorControlAddress="" DistributorDataAddress="">
    <MessageEndpointMappings>        
        <add Messages="Messages" Endpoint="messagebus" />    
    </MessageEndpointMappings>
</UnicastBusConfig>

The MsMqTransportConfig section describes the subscriber’s input queue (worker) and its error queue (error). The UnicastBusConfig section describes the messages that flow through the system.

The Server’s configuration is a little different:

<MsmqTransportConfig
    InputQueue="messagebus"
    ErrorQueue="error"
    NumberOfWorkerThreads="1"
    MaxRetries="5"
/>  
<UnicastBusConfig DistributorControlAddress="" DistributorDataAddress="">
    <MessageEndpointMappings>
        <add Messages="Messages" Endpoint="messagebus" />
    </MessageEndpointMappings>
</UnicastBusConfig>

<MsmqSubscriptionStorageConfig Queue="subscriptions" />

The Server's MsmqTransportConfig section sets the Server's input queue to the 'messagebus' queue and the error queue, 'errors'. The Server - the publisher, conceptually handles messages by publishing them to the messagebus queue and then transferring the published messages to interested subscribers. In reality, as of version 1.9, the server matches a message it wants to publish with a subscriber by iterating over a mapping of message types and subscriber information. When the server finds a match, it publishes the message to the subscriber's queue. The next section of the server's configuration should be familiar to you now.

As before, the UnicastBusConfig section describes messages that flow through the system and the endpoint (queue) that manages them. The messages in this case reside in an assembly called Messages and their endpoint (or queue, in this case) is the messagebus queue.

This last section of the Server's configuration, MsmqSubscriptionStorageConfig, describes where the Server finds information about subscribers - the subscriptions queue you worked with earlier.

nServiceBus makes it easy to change the behavior of both publishers and subscribers with just a few lines of code, or some changes to the configuration file. In this example, I walk you through changing the durable nature of a subscription to something less durable. Subscribers normally continue to receive messages, even when they are offline. This example changes a subscriber such that it unregisters itself when it terminates; therefore, the subscriber won't be aware of messages that were sent to it while it was offline.

You can change Subscriber1 to unregister itself when it terminates by adding just one line of code to Program1.cs in the Subscriber1 project.

Add the following line, just after the end of the while loop in the Subscriber1 project's Program.cs file:

bus.Unsubscribe<EventMessage>();

So, the resulting code should look something like this:

while (Console.ReadLine().ToLower() != "q")
{ }
bus.Unsubscribe<EventMessage>();

Start the Server, and then start Subscriber1. Publish some messages and note that Subscriber1 receives them, then quit Subscriber1. Publish some more messages, and finally restart Subscriber1. You'll notice that it no longer handles messages that were sent to it while it was offline.

The server in this case did not even publish messages for Subscriber1 because, when Subscriber1 goes offline, it removes its entry from the 'subscriptions' queue; the Server does not publish messages that don't have a subscriber. While this example demonstrates un-subscription behavior, you should be aware that there may be some cases where this does not work as seamlessly as it does in this example. It's recommended that you always work with the latest version of nServiceBus, and that you consult the discussion board to research current issues before your project depends on certain functionality.

The next article in this series walks you through the nServiceBus solution, and demonstrates how to compile it.