NServiceBus Step-by-step: 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 build 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 first messaging endpoint.


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

This tutorial uses NServiceBus version 8, .NET 6, and assumes an up-to-date installation of Visual Studio 2022.

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 App project type.
  2. Select .NET 6.0 (Long Term Support) from the Framework dropdown.
  3. Set the project name to ClientUI.
  4. Set the solution name to RetailDemo.

Next, add the NServiceBus NuGet package as a dependency. Using PowerShell or another terminal alternative, navigate to the ClientUI project directory and run the following command:

dotnet add package NServiceBus

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

Configure an endpoint

We're ready to create a messaging endpoint. A messaging endpoint (or just endpoint) is a logical component 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.

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

class Program
    static async Task Main()


Now that we have a Main method, let's take a look at the code we're going to add to it, then analyze the importance of each line. First, add the following code to the Main method:

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

    var endpointConfiguration = new EndpointConfiguration("ClientUI");

    // Choose JSON to serialize and deserialize messages

    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 is ClientUI. In later lessons, we'll expand this solution to host several more.


var endpointConfiguration = new EndpointConfiguration("ClientUI");

// Choose JSON to serialize and deserialize messages

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. When setting up the endpoint configuration you can choose how you want to serialize your messages. For this tutorial, we will be configuring the endpoint to use SystemJsonSerializer which uses the .NET System.Text.Json serializer.


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

This setting defines the transport that NServiceBus will use to send and receive messages. We are using the Learning transport, which is bundled in the NServiceBus core library as a starter transport for learning how to use NServiceBus without 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 a later lesson when we start defining message routing rules.

Starting up

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

var endpointInstance = await Endpoint.Start(endpointConfiguration);

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

await endpointInstance.Stop();

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 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 is recommended 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 and a message handler, then send the message and watch it get processed.