# Getting Started with NServiceBus

> Add NServiceBus to a .NET 8 Clean Architecture app: define a message, configure endpoints, send from a web project, and handle it in a worker service.

- URL: https://blog.nimblepros.com/blogs/getting-started-with-nservicebus/
- Author: [Kyle McMaster](https://blog.nimblepros.com/authors/kyle/)
- Published: 2024-03-13
- Updated: 2026-11-06
- Series: [NServiceBus](https://blog.nimblepros.com/series/nservicebus/)
- Categories: [Software Development](https://blog.nimblepros.com/categories/software-development/)
- Publisher: [NimblePros](https://blog.nimblepros.com/)

---

This post is the second in a series on [NServiceBus](https://go.particular.net/using-nservicebus-2024). In the previous article, we looked at [What is NServiceBus](/blogs/what-is-nservicebus). In this article, we will look at how to get started with NServiceBus in .NET 8. All code for this article can be found in the [NServiceBusTutorial repository](https://github.com/KyleMcMaster/NServiceBusTutorial) on GitHub.

## Prerequisites 📝

For this tutorial, we will use the Ardalis CleanArchitecture template. It's worth noting that you do not need to use this template to use NServiceBus. But it is a good starting point for building a .NET application and our sample domain will be based on the entities and actions found in that solution. You can [find the project template here](https://github.com/ardalis/CleanArchitecture) or install it as a dotnet CLI template using the following command:

```bash
dotnet new install Ardalis.CleanArchitecture.Template::9.1.2
```

Then, in a new directory, run:

```bash
dotnet new clean-arch -o NServiceBusTutorial
```

This will give you a new solution with a few projects and a sample domain. You can find more information about the template and its structure in the [Ardalis.CleanArchitecture README](https://github.com/ardalis/CleanArchitecture?tab=readme-ov-file). For this tutorial, this project will give us a .NET web application with CRUD functionality for a Contributor entity which we can use to demonstrate how NServiceBus can be used to send and receive messages. Let's dive right into sending an event when a new Contributor is added to the system.

The sample applications we'll be building in this project will be a .NET web application and a .NET worker service. The web application will be used to send a message when a new Contributor is added to the system, and the worker service will be used to receive the message. Below is a simple architecture diagram of the applications and the queue between them. 

![Tutorial Architecture Diagram](https://blog.nimblepros.com/blogs/getting-started-with-nservicebus/getting-started-architecture.png)

## Adding NServiceBus to the Project ➕

To add NServiceBus to the project, we will use the NServiceBus NuGet package. You can find the latest version of [the package on NuGet](https://www.nuget.org/packages/NServiceBus/). To add the package to the project, run the following command at the root of the solution:

```bash
dotnet add src/NServiceBusTutorial.Core/NServiceBusTutorial.Core.csproj package NServiceBus --version 8.1.6
```

This will add the NServiceBus package to the Core project. The Core project is where we will define our messages so that they can be shared between the web application and the endpoint that will process the messages. There is a noteworthy tradeoff taking a dependency on NServiceBus in the Core project. It will allow us to share the message definitions between the sending and receiving endpoints, but it will also mean that the Core project will have a dependency on NServiceBus. In larger applications or projects that span multiple repositories, you may move this shared message contract to a library that many projects can consume. This is a tradeoff that you will need to consider when designing your application. For this tutorial, we will take the tradeoff and add the NServiceBus package to the Core project.

## Defining a Message 📨

In the Core project, we will define a message that will be sent when a new Contributor is added to the system. We will call this message `ContributorCreated`. We will define the message as a class that implements the `IMessage` interface from the NServiceBus package. The `IMessage` interface is a marker interface that is used to identify a class as a message. The message will contain the `ContributorId`, `Name`, and `Status` of the new Contributor. The message will look like this:

```csharp
public class ContributorCreatedEvent : IMessage
{
  public Guid ContributorId { get; init; }
  public string Name { get; init; }
  public string Status { get; init; }
}
```

That's it, we've defined our first NServiceBus message! Now, let's send this message when a new Contributor is added to the system.

## Configuring The Web Project Endpoint 🌐

To configure the `NServiceBusTutorial.Web` project as an endpoint, we will need to add the `NServiceBus.Extensions.Hosting` NuGet package.

```bash
dotnet add src/NServiceBusTutorial.Web/NServiceBusTutorial.Web.csproj package NServiceBus.Extensions.Hosting --version 2.0.0
```

In the `Program.cs` file in `NServiceBusTutorial.Web` we will register NServiceBus and its dependencies with our application. Typically, you will register the routing of messages, the transport mechanism for your persistence of messages, and additional NServiceBus configuration in this method. For this tutorial, our configuration is relatively simple. We set up a simple send-only endpoint using `LearningTransport`, define a route for a single message, and enable installers to create the necessary infrastructure for our endpoint.

```csharp
builder.Host.UseNServiceBus(_ =>
{
  var endpointConfiguration = new EndpointConfiguration("contributors-api");
  
  var transport = endpointConfiguration.UseTransport<LearningTransport>();

  transport.Routing().RouteToEndpoint(
    typeof(ContributorCreatedEvent),
    "contributors-worker");

  endpointConfiguration.SendOnly();
  endpointConfiguration.EnableInstallers();

  return endpointConfiguration;
});
```

### A Quick Note on the Learning Transport 🧠

In this tutorial, we are using the Transport, `LearningTransport`, which is an abstraction for defining the underlying persistence and queueing technology for your messages. `LearningTransport` is a Transport that is included with NServiceBus and is used for development and testing. It is not recommended for production use. We'll revisit how Learning Transport works in a future article. For now, it is sufficient to know that it is a file system-based Transport that can be used to send and receive messages in a development environment. These messages will be written to the root of the repository in a folder called `.learningtransport`.

## Sending a Message 📤

In the UseCases layer, we will send the `ContributorCreatedEvent` message when a new Contributor is added to the system. We will inject the `IMessageSession` interface into the `CreateContributorHandler` and use it to send the `ContributorCreatedEvent` message. The `IMessageSession` is NServiceBus's interface for sending messages outside the context of a message handler (which we'll see in a bit). The `CreateContributorHandler` will look like this:

```csharp
var newContributor = new Contributor(request.Name, phoneNumber, ContributorStatus.NotSet);
var createdItem = await _repository.AddAsync(newContributor, cancellationToken);

var message = new ContributorCreatedEvent
{
  ContributorId = createdItem.Id,
  Name = createdItem.Name,
  Status = createdItem.Status.ToString()
};
await _messageSession.Send(message, cancellationToken);

return createdItem.Id;
```

That's it! We are now able to send our first NServiceBus message This should look familiar if you've used a package like MediatR or an equivalent, with the difference that NServiceBus messages are being sent out of process and not in-process in this example. Now, let's set up a .NET worker service to receive the message.

## Setting Up a Worker Service Endpoint 🛠️

Now that our code to send a message is in place, we will set up a new endpoint to receive the message in a .NET worker service. First, we'll create a new project called `NServiceBusTutorial.Worker` using the following command:

```bash
dotnet new worker -n NServiceBusTutorial.Worker -o src/NServiceBusTutorial.Worker
```

Then, we will add the project to our Solution file using the following command:

```bash
dotnet sln add src/NServiceBusTutorial.Worker/NServiceBusTutorial.Worker.csproj
```

Next, we will add the `NServiceBus.Extensions.Hosting` NuGet package to the `NServiceBusTutorial.Worker` project just like we did for the `NServiceBusTutorial.Web` project.

```bash
dotnet add src/NServiceBusTutorial.Worker/NServiceBusTutorial.Worker.csproj package NServiceBus.Extensions.Hosting --version 2.0.0
```

We can delete the `Worker.cs` file that was created by default as we won't be using it. Then, we'll update the contents of the `Program.cs` file to configure the Worker's `IHost` as an endpoint. Similar to the `NServiceBusTutorial.Web` project, we will call the `UseNServiceBus` method but our endpoint will be the receiving name for the route we configured in the previous Transport. We'll again use `LearningTransport` for this demo. The `Program.cs` file will look like this:

```csharp
using NServiceBus;

var builder = Host.CreateDefaultBuilder();

builder.UseConsoleLifetime();
builder.UseNServiceBus(context => 
{
  var endpointConfiguration = new EndpointConfiguration("contributors-worker");
  endpointConfiguration.UseTransport<LearningTransport>();

  return endpointConfiguration;
});

var host = builder.Build();
host.Run();
```

This is all that is needed to set up our worker Service as an endpoint that can send and receive messages. Now, let's create a message handler to process the `ContributorCreatedEvent` message.

## Creating a Message Handler 📭

In the `NServiceBusTutorial.Worker` project, we will create a new class called `ContributorCreatedEventHandler` that will implement the `IHandleMessages<ContributorCreatedEvent>` interface. This interface is used to identify a class as a message handler for the `ContributorCreatedEvent` message. NServiceBus will register this detect and register this handler automagically 🪄 so there is no need to do any manual configuration for this class. For this sample, we will simply log that we received the message and the `Id` of the Contributor from the message body.

```csharp
public class ContributorCreatedEventHandler(ILogger<ContributorCreatedEventHandler> logger) 
  : IHandleMessages<ContributorCreatedEvent>
{
  private readonly ILogger<ContributorCreatedEventHandler> _logger = logger;

  public Task Handle(ContributorCreatedEvent message, IMessageHandlerContext context)
  {
    _logger.LogInformation("Received {EventName} for {ContributorId}",
      nameof(ContributorCreatedEvent),
      message.ContributorId);
    return Task.CompletedTask;
  }
}
```

That's it! We are now able to receive our first NServiceBus message. We have set up a default `IHost` as a worker service to receive the `ContributorCreatedEvent` message and log the Contributor's `Id`. Now, let's run the application and see it in action.

## Running the Application 🏃‍♂️

Below is a gif that shows two console outputs from the `NServiceBusTutorial.Web` and `NServiceBusTutorial.Worker` projects. The bottom console output shows the `NServiceBusTutorial.Web` project running which receives a POST request which creates a Contributor and sends the `ContributorCreatedEvent`. The top console output shows the `NServiceBusTutorial.Worker` project receiving the `ContributorCreatedEvent` message and logging the `ContributorId` when it is received.

![Output of the sample application be executed](https://blog.nimblepros.com/blogs/getting-started-with-nservicebus/message-sending.gif)

## Conclusion 🎬

In this article, we looked at how to get started with NServiceBus in .NET 8. We added the NServiceBus package to the Core project and defined a message that will be sent when a new Contributor is added to the system. We then configured the `NServiceBusTutorial.Web` project as an endpoint and sent the `ContributorCreatedEvent` message when a new Contributor is added to the system. We then set up a new endpoint in the `NServiceBusTutorial.Worker` project to receive the `ContributorCreatedEvent` message and log the `ContributorId` when it is received. In the next article, we will look at different types of messages like commands and events, the differences in how they are sent and received, and some small changes we can make to our code to reflect these differences.

## Resources 🤓

- [NServiceBus](https://go.particular.net/using-nservicebus-2024)
- [NServiceBusTutorial repository](https://github.com/KyleMcMaster/NServiceBusTutorial)
- [Ardalis Clean Architecture template](https://github.com/ardalis/CleanArchitecture)
- [NimblePros' Clean Architecture course](https://academy.nimblepros.com/p/intro-to-clean-architecture) 
- [Learn more about this course!](https://blog.nimblepros.com/blogs/announcing-the-nimblepros-clean-architecture-course/)
