Getting Started
While NServiceBus is quite a powerful and flexible framework,
it's designed to have a gentle learning curve.
This page will take you from downloading NServiceBus to
having publish/subscribe messaging working on your machine.
Step 1: Extract to a directory
After the download completes, extract the zip file to a directory on your local hard drive
like D:\NServiceBus. Make sure not to pick a directory that has a very long name (longer than
200 characters) - this may cause the samples to fail compilation.
It's important that you extract to a local hard drive and not a network drive. The .NET framework
places security restrictions on code that runs on network drives which may cause NServiceBus
not to function correctly.
Step 2: Open the publish/subscribe sample
Go to the directory you extracted the zip to in the previous step, and click through the "samples"
and "PubSub" subdirectories. There, double-click the "PubSub.sln" file.
After Visual Studio has finished opening the solution, on your screen you should see the picture to the left.
Before running the sample, take some time to look over the solution structure, the projects
that are there, and the classes inside them.
The projects "MyPublisher", "Subscriber1", and "Subscriber2" each are their own process, even though
they look like regular class libraries.
The project "Messages" contains the definition of the messages that will be sent between the
processes. Open the "Messages.cs" class and you'll see a class called "EventMessage" and an
interface called "IEvent".
The important thing to note is that all messages in NServiceBus must ultimately inherit the
IMessage interface.
The "MyPublisher" process will be publishing each of these message alternately, every time you press
the 'Enter' key in its console window.
The "Subscriber1" process will subscribe to "EventMessage" while "Subscriber2" will subscribe to
the interface "IEvent". Since the class "EventMessage" implements the interface "IEvent", when
the "MyPublisher" process publishes an "EventMessage", both subscribers will receive it.
When running the sample, you'll see 3 console applications open, and each of them fill up with
a great deal of log messages. Hardly any of these logs represent messages sent between the processes.
Step 3: Run the sample
Press 'F5' and see the 3 console applications open.
Identify the "MyPublisher" process by its window's title as shown below:
You'll want to spread out the various console windows so that you can see all three fully.
Press 'Enter' repeatedly in the "MyPublisher" processes console window, and notice how the messages appear
in the other console windows - one click appearing on only one other console, the next click causing
messages to be sent to both subscriber consoles.
Success!
Congratulations - you have processes publishing and subscribing to each other.
Wasn't that easy?
Let's see what else NServiceBus can do...
Fault-tolerant Messaging
Pick one of the subscriber processes (say Subscriber1) and close it.
Now go back the "MyPublisher" process, and press 'Enter' several more times.
Now go to Visual Studio and right-click the project of the closed subscriber, and start it up again
by selecting 'Debug' and then 'Start new instance' as shown below:
Notice how the subscriber processes all the messages that were sent by the "MyPublisher" process while
it was down. This is how you can be sure that even when processes or machines restart, NServiceBus will
ensure that your messages don't get lost.
Zero Install
working pub/sub messaging
in under 5 minutes.
Just like we promised.
Now let's examine some more failure scenarios.
Durable Subscriptions
Restart the "MyPublisher" process and bringing it up again as described above.
Press 'Enter' several times in the publisher's console window.
Notice that the subscribers aren't receiving these events anymore. You might not have expected this.
It is reasonable to assume that a publisher "remember" its subscribers even if it restarts. That would
require that a publisher store which events each subscriber wants to receive on some durable medium.
Luckily, NServiceBus comes with 2 durable subscription storage options in addition to the default in-memory
storage - one makes use of MSMQ, the other makes use of a database.
The MSMQ option is suitable for integration environments where you want to test out various kinds of
fault scenarios but don't require scalability. If you want to scale out a publisher over multiple machines
the MSMQ subscription storage will not work correctly - for that, you need to use the DB subscription storage.
Switching from the in-memory storage to the others suitable for integration and production is done through
the use of "profiles". These are preconfigured combinations of infrastructure technologies suitable for
various scenarios. Let's change the publisher's profile to integration.
Go back to Visual Studio and stop debugging, double click the "Properties" node immediately
under the "MyPublisher" process, and then click the "Debug" tab. In the "Start Options" section,
in the "Command line arguments" textbox enter "NServiceBus.Integration" as shown below:
Now press "F5" again, press 'Enter' several times in the publisher's console, check that the events are
showing up at the subscribers. Now restart the publisher.
This time when you press 'Enter' in the publisher's console, you should see the subscribers still
receive those events.
Production-ready & developer-friendly, NServiceBus has what you need
to build robust, enterprise-scale, distributed systems right the first time.
Next Steps
Learn more about the installation story of NServiceBus.
Leave the messiness of writing Windows services behind you with the generic host.
Take convention-over-configuration to the next level.
Learn how to simplify logging, email, and your own configuration with NServiceBus profiles.
Scale out your publishers and subscribers.
See the other NServiceBus pieces which handle this for you in how pub/sub works.