Learning NServiceBus - Second Edition

Before diving in, we should take a moment to consider why NServiceBus might be a tool worth adding to your repertoire. If you're eager to get started, feel free to skip this section and come back later.

So what is NServiceBus? It's a powerful, extensible framework that will help you to leverage the principles of Service-oriented architecture (SOA) to create distributed systems that are more reliable, more extensible, more scalable, and easier to update.

That's all well and good, but if you're just picking up this book for the first time, why should you care? What problems does it solve? How will it make your life better?

Ask yourself whether any of the following situations describes you:

If any of these situations has you nodding your head in agreement, I invite you to read on.

NServiceBus will help you to make multiple transactional updates utilizing the principle of eventual consistency to reduce database locking and blocking and make deadlocks easy to deal with in a reliable way. It will ensure that valuable customer order data is not lost in the deep dark depths of a multi-megabyte logfile.

By the end of the book, you'll be able to build systems that can easily scale out as well as up. You'll also be able to reliably perform non-transactional tasks such as calling web services and sending emails. You will be able to easily start up long-running processes in an application server layer, leaving your web application free to process incoming requests and you'll be able to unravel your spaghetti codebases into a logical system of commands, events, and handlers that will enable you to more easily add new features and version the existing ones.

You could try to do this all on your own by rolling your own messaging, but that would be really dangerous and wasteful. It is a far better strategy to take advantage of all of the industry-leading expertise that has been applied in NServiceBus in the last several years, and concentrate on what your business does best. NServiceBus is the easiest and most capable solution to solve the aforementioned problems without having to expend too much effort to get it right, allowing you to put your focus on your business concerns, where it belongs.

So if you're ready, let's get started creating an NServiceBus solution.

We will be covering a lot of information very quickly in this chapter, so if you see something that doesn't immediately make sense, don't panic! Once we have the basic example in place, we will look back and explain some of the finer points in more detail.

To get the actual NServiceBus binaries, we will use NuGet exclusively, but before we get started on our first project, we should download and run the installer for the entire Particular Service Platform, which will ensure that your machine is set up properly to run NServiceBus solutions. Additionally, the platform installer will install several other helpful applications that will assist in your NServiceBus development, which we will cover in more detail in Chapter 8, The Service Platform.

Download the installer from http://particular.net/downloads and run it on your machine. The following screenshot depicts the applications installed by the platform installer:

You should select all the options that are available to you. There are two options for ServiceMatrix because of differences in how Visual Studio handles add-ins between Visual Studio 2012 and 2013, so you can install whichever matches the version of Visual Studio you use.

In addition to the Service Platform apps, the installer does several things to get your system ready to go:

Now that our system is ready to go, we can get started building our first solution by pulling in the NServiceBus NuGet packages.

For this example, let's pretend we're creating a simple website that users can join and become a member of. We will construct our project so that the user is created in a backend service and not in the main code of the website.

The following diagram depicts our goal. We will have an ASP.NET MVC web application that will send a command from the HomeController process, and then the command will be handled by another process called UserService.

The first step while creating an NServiceBus system is to create a messages assembly. Messages in NServiceBus are simply plain old C# classes. Like the WSDL document of a web service, your message classes form a contract by which services communicate with each other.

Follow these steps to create your solution:

When you're done, your class should look like this:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using NServiceBus;

namespace UserService.Messages.Commands
{
  public class CreateNewUserCmd : ICommand
  {
    public string EmailAddress { get; set; }
    public string Name { get; set; }
  }
}

Congratulations! You've created a message. This new message will form the communication contract between the message sender and receiver. This is just a message; now you need to create a service that can receive and process it.

Now we're going to create a service endpoint—a process that will host code to handle our command message:

Now that we have a service endpoint to host our code, we will create a message handler within the endpoint that will process our message when it arrives:

Normally, we would want to create the user here with calls to a database. In order to keep the examples straightforward, we will skip the details of database access and just demonstrate what will happen by logging a message.

With NServiceBus, you can use any logging framework you like without being dependent upon that framework. NServiceBus internally includes a logging system that logs to both console and file, with an API that looks very much like log4net (previous versions of NServiceBus actually used the log4net framework directly). In Chapter 7, Advanced Configuration, you will learn how to easily swap these out for the real log4net framework, NLog framework, or implement an adapter for any logger we like. For now, we are more than content with the built-in logging implementation via the NServiceBus.Logging namespace.

Now lets finish our fake implementation for the handler:

When you're done, your class should look like this:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using UserService.Messages.Commands;
using NServiceBus;

namespace UserService
{
  public class UserCreator : IHandleMessages<CreateNewUserCmd>
  {
    private static readonly ILog log = 
      LogManager.GetLogger(typeof(UserCreator));

    public void Handle(CreateNewUserCmd message)
    {
      log.InfoFormat("Creating user '{0}' with email '{1}'",
        message.Name,
        message.EmailAddress);
    }
  }
}

Now we have a command message and a service endpoint to handle it. Its okay if you don't understand quite how all of this connects yet. Next, we need to create a way to send the command.

An ASP.NET MVC web application will be the user interface for our system. It will be sending a command to create a new user to the service layer, which will be in charge of processing it. Normally this would be from a user registration form, but in order to keep the example to the point, we'll take a shortcut and enter the information in the form of query string parameters, and return data as JSON.

using NServiceBus;

namespace ExampleWeb
{
  public static class ServiceBus
  {
    public static IBus Bus { get; private set; }
    private static readonly object padlock = new object();

    public static void Init()
    {
      if (Bus != null)
        return;
      lock (padlock)
      {
        if (Bus != null)
          return;
        var cfg = new BusConfiguration();
        cfg.UseTransport<MsmqTransport>();
        cfg.UsePersistence<InMemoryPersistence>();
        cfg.EndpointName("ExampleWeb");
        cfg.PurgeOnStartup(true);
        cfg.EnableInstallers();
        
        Bus = NServiceBus.Bus.Create(cfg).Start();
      }
    }
  }
}

protected void Application_Start()
{
  AreaRegistration.RegisterAllAreas();
  RouteConfig.RegisterRoutes(RouteTable.Routes);

  ServiceBus.Init();
}

public ActionResult Index()
{
  return Json(new { text = "Hello world." });
}

public ActionResult CreateUser(string name, string email)
{
  var cmd = new CreateNewUserCmd
  {
    Name = name,
    EmailAddress = email
  };

  ServiceBus.Bus.Send(cmd);

  return Json(new { sent = cmd });
}

protected override JsonResult Json(object data, 
  string contentType, 
  System.Text.Encoding contentEncoding, 
  JsonRequestBehavior behavior)
{
  return base.Json(data, contentType, contentEncoding, JsonRequestBehavior.AllowGet);
}

<configuration>
  <configSections>
    <section name="MessageForwardingInCaseOfFaultConfig" type="NServiceBus.Config.MessageForwardingInCaseOfFaultConfig, NServiceBus.Core" />
    <section name="UnicastBusConfig" type="NServiceBus.Config.UnicastBusConfig, NServiceBus.Core" />
  </configSections>
  
  <MessageForwardingInCaseOfFaultConfig ErrorQueue="error" />
  <UnicastBusConfig>
    <MessageEndpointMappings>
      <add Messages="UserService.Messages" Endpoint="UserService" />
    </MessageEndpointMappings>
  </UnicastBusConfig>
  
  <!-- Rest of Web.config -->
  
</configuration>

One thing that will be useful when developing NServiceBus solutions is being able to specify multiple startup projects for a solution:

Now build the solution if you haven't already, and assuming there are no compilation errors, click on the Start Debugging button or press F5.

So what happens now? You get a result that looks like what is shown in the following screenshot:

When you run the solution, both the MVC website and a console window should appear as shown in the preceding screenshot. As we can see, the browser window isn't terribly exciting right now. It's just showing the JSON results of the /Home/Index action. The console window is far more interesting.

If you remember, we never created a console application; our service endpoint was a class project. When we included the NServiceBus.Host NuGet package, a reference to NServiceBus.Host.exe was added to the class project (remember that a .NET executable is also an assembly and it can be referenced by another project) and the project was set to run that executable when you debug it.

NServiceBus uses different colors to log messages of different levels of severity. INFO messages are logged in white, and WARN messages are displayed in yellow. In addition, there can be DEBUG messages, also displayed in white, or ERROR and FATAL messages which are both logged in red. By default, the INFO log level is used for display, which filters out all the DEBUG messages here, and luckily we don't have any ERROR or FATAL messages.

The entire output is too much to show in a single screenshot. It's worth reading through, even though you may not understand everything that's going on quite yet. Here are some of the important points:

That's a lot of plumbing that NServiceBus takes care of for us! But this just gets the endpoint ready to go. We still need to send a message.

Visual Studio will likely give you a different port number for your MVC project than the number in the preceding example, so change the URL in your browser to the following, keeping the host and port the same. Feel free to use your own name and email address:

/Home/CreateUser?name=David&email=david@example.com

Look at what happens in your service window:

INFO  UserService.UserCreator Creating user 'David' with email 'david@example.com'

This might seem simple, but consider what had to happen for us to see this message. First, in the MVC website, an instance of our message class was serialized to XML. Then that payload was added to an MSMQ message with enough metadata to describe where it came from and where it needs to go. The message was sent to an input queue for our background service, where it waited to be processed until the service was ready for it. The service pulled the message from the queue, deserialized the XML payload, and was able to determine a handler that could process the message. Finally, our message handler was invoked, which resulted in the message being output to the log.

This is a great start, but there is a great deal more to discover.

In this chapter, we created an MVC web application and an NServiceBus-hosted service endpoint. Through the web application, we sent a command to the service layer to create a user where we just logged the fact that the command was received, but in real life, we would likely perform database work to actually create the user. For our example, our service was running on the same computer, but our command can just as easily be sent to a different server, enabling us to offload work from our web server.

In the next chapter, we will take the code we developed in this chapter and extend it using Publish/Subscribe to enable decoupling services from each other. Then we will start to discover the true power that NServiceBus has to offer.