Architecture
NServiceBus
Transports
Persistence
ServiceInsight
ServicePulse
ServiceControl
Monitoring
Samples

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.

If you're not quite ready for a deep dive, and just need to get a sense of what NServiceBus can do for you, check out our Quick Start tutorial instead.

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.

Exercise

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()
    {

    }
}

For the sake of brevity, code snippets in this tutorial do not contain the using statements needed to import namespaces. If you're using Visual Studio, unknown references such as Task or NServiceBus types will generate a "red squiggly" underline effect. If you hover or click on the red squiggly, you can click on the "light bulb" icon or press Ctrl + . to see the available fixes and insert the appropriate using statements for the missing namespaces.

Alternatively, in the code snippet's Copy/Edit menu you will find a Copy usings item that will copy the namespaces used by the snippet to your clipboard.

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
    endpointConfiguration.UseSerialization<SystemJsonSerializer>();

    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.

EndpointConfiguration

var endpointConfiguration = new EndpointConfiguration("ClientUI");

// Choose JSON to serialize and deserialize messages
endpointConfiguration.UseSerialization<SystemJsonSerializer>();

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.

Transport

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...");
Console.ReadLine();

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.

Summary

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.


Last modified