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.

Exercise

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

This tutorial uses NServiceBus version 9, .NET 8, 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 8.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
dotnet add package NServiceBus.Extensions.Hosting

This adds NServiceBus and NSeviceBus.Extension.Hosting package references 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.

We're going to use the top-level statements feature for this tutorial to minimize the boilerplate code we have to write.

First, add the following code to the Program.cs:

Console.Title = "ClientUI";

var builder = Host.CreateApplicationBuilder(args);

var endpointConfiguration = new EndpointConfiguration("ClientUI");
endpointConfiguration.UseSerialization<SystemJsonSerializer>();

var transport = endpointConfiguration.UseTransport(new LearningTransport());

builder.UseNServiceBus(endpointConfiguration);

await builder.Build().RunAsync();

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 one a name makes them easier to identify. This console app's title is ClientUI. In later lessons, we'll expand this solution to host multiple applications.

Setup

var builder = Host.CreateApplicationBuilder(args);

The host is typically configured, built, and run by code in Program.cs. The CreateApplicationBuilder method creates and configures a builder object.

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 identifier for our endpoint, and forms a naming convention by which other components 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(new 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 file, after the configuration code, the following lines will start the endpoint and keep it running until you press Ctrl+C to shut it down.

builder.UseNServiceBus(endpointConfiguration);

await builder.Build().RunAsync();

The endpoint is initialized according to the settings defined by the EndpointConfiguration class. Once the endpoint starts, any changes made to the configuration won't be applied until you restart the endpoint.

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

• Display its logging information via Microsoft.Extensions.Logging
• Display the status of your license.
• Create file-based "queues" in the .learningtransport directory inside your solution directory. We recommend adding .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.