Introduction to NServiceBus: Getting started

The best way to get started with NServiceBus is to use it to build something realistic. In doing so you'll learn the architectural concepts behind the software, and start to learn its capabilities. In this tutorial, you'll be building a back end for a retail e-commerce system. You'll learn how to send asynchronous messages between processes, how to use the Publish/Subscribe pattern to decouple business processes, and the advantages of using reliable messaging to enable automatic retries after processing failures.

The tutorial is divided into five lessons, each of which can be accomplished in a half hour or less — perfect for your lunch break.

In this first lesson, which should take 10-15 minutes, you will create your very first messaging endpoint.


Let's build something simple to give NServiceBus a try.

Although NServiceBus only requires .NET Framework 4.5.2, this tutorial assumes at least Visual Studio 2015 and .NET Framework 4.6.1.

Create a solution

First, let's create a basic solution and include the dependencies we need.

  1. In Visual Studio, create a new project and select the Console Application project type.
  2. Be sure to select the correct .NET Framework version from the dropdown at the top of the dialog. You'll want at least .NET Framework 4.6.1 for access to the convenient Task.CompletedTask API.
  3. Set the project name to ClientUI.
  4. Set the solution name to RetailDemo.

Next, we need to add the NServiceBus NuGet package as a dependency. From the NuGet Package Manager Console, type the following:

Install-Package NServiceBus -ProjectName ClientUI

This adds a reference to the NServiceBus.Core assembly to ClientUI. Now we're ready to start writing code.

Configure an endpoint

Now we're ready to create a messaging endpoint. A messaging endpoint (or just endpoint) is a logical component that's capable of sending and receiving messages. An endpoint is hosted within a process, which in this case is a simple console application, but could be a web application or other .NET process.

Because of the current limitations of console applications, we need to add some boilerplate code to be able to use the async/await keywords.

In the Program.cs file, modify the code to look like the following:

class Program
    static void Main()

    static async Task AsyncMain()


Add the following code to your program first and then let's analyze the importance of each line.

Add this code to your AsyncMain method:

static async Task AsyncMain()
    Console.Title = "ClientUI";

    var endpointConfiguration = new EndpointConfiguration("ClientUI");

    var transport = endpointConfiguration.UseTransport<LearningTransport>();


Now, let's go line-by-line and find out exactly what each step is doing.

Console Title

Console.Title = "ClientUI";

When running multiple console apps in the same solution, giving each a name makes them easier to identify. This console app's title uses ClientUI. In later lessons, we'll expand this solution to host several more.


var endpointConfiguration = new EndpointConfiguration("ClientUI");

The EndpointConfiguration class is where we define all the settings that determine how our endpoint will operate. The single string parameter ClientUI is the endpoint name, which serves as the logical identity for our endpoint, and forms a naming convention by which other things will derive their names, such as the input queue where the endpoint will listen for messages to process.


var transport = endpointConfiguration.UseTransport<LearningTransport>();

This setting defines the transport that NServiceBus will use to send and receive messages. We are using the LearningTransport, which is bundled within the NServiceBus core library as a starter transport to learn how to use NServiceBus without any additional dependencies. All other transports are provided using different NuGet packages.

Capturing the transport settings in a variable as shown will make things easier in Lesson 3 when we start defining message routing rules.

Starting up

At the end of the AsyncMain method, after the configuration code, add the following code which will start up the endpoint, keep it running until we press the Enter key, and then shut it down.

var endpointInstance = await Endpoint.Start(endpointConfiguration)

Console.WriteLine("Press Enter to exit...");

await endpointInstance.Stop()
In this tutorial we will always use .ConfigureAwait(false) when awaiting tasks, in order to avoid capturing and restoring the SynchronizationContext.

The endpoint is initialized according to the settings defined by the EndpointConfiguration class. Once the endpoint starts, changes to the configuration information are no longer applied.

When you run the endpoint for the first time, the endpoint will:

  • Display its logging information, which is written to a file, Trace and the Console. NServiceBus also logs to multiple levels, so you can change the log level from INFO to log level DEBUG in order to get more information.
  • Display the status of your license.
  • Attempt to add the current user to the "Performance Monitor Users" group so that it can write performance counters to track its health and progress.
  • Create fake, file-based "queues" in a .learningtransport directory inside your solution directory. It would be a good idea to add .learningtransport to your source control system's ignore file.


In this lesson we created a simple messaging endpoint to make sure it works. In the next lesson, we'll define a message, a message handler, and then send the message and watch it get processed.

Next Lesson: Sending a command

Last modified