Getting Started
Architecture
NServiceBus
Transports
Persistence
ServiceInsight
ServicePulse
ServiceControl
Monitoring
Samples

Samples

For a guided introduction to essential NServiceBus concepts start with the NServiceBus step-by-step tutorial.

The samples are designed to highlight how various features of NServiceBus work and how the extension points plug into other libraries and tooling.

Skip to the list of samples

Samples are not production ready

Samples are not meant to be production-ready code or to be used as-is with Particular Platform tools. They are meant to illustrate the use of an API or feature in the simplest way possible. For this reason, these samples make certain assumptions on transport, hosting, etc. See Technology choices for more details.

Samples are not "endpoint drop in" projects

Since the endpoint in samples have to choose specific technologies (transport, serializer, persistence, etc.), before using this code in production ensure the code conforms with any specific technology choices.

Samples are downloadable and runnable

All samples have a download link that allows the sample solution to be downloaded as a zip file. Once opened in Visual Studio, the samples are then runnable. Note some samples may have certain infrastructure requirements, for example a database existing in a local SQL Server.

The full GitHub Repository

The samples are located in GitHub at Particular/docs.particular.net/samples and both issues and pull requests are accepted.

Samples targeting non-supported versions of the platform

Samples that target non-supported versions of NServiceBus have been archived, according to the support policy. Customers with an extended support agreement can request archived samples by contacting support.

Technology choices

Unless otherwise specified (by an individual sample) the following are the default technology choices.

Visual Studio and .NET

Visual Studio 2022. If any help is required upgrading to a new version of Visual Studio, raise an issue.

Most samples are made available for multiple frameworks, available through a dropdown menu on the download button. Each framework has its own requirements for what version of Visual Studio is supported. For instance, .NET 6 requires at least Visual Studio 2022.

ConfigureAwait

Samples only call ConfigureAwait(bool) when it is required. If any code is copied from samples, appropriate calls to ConfigureAwait(bool) should be added if it might be used in an environment that requires it.

For example, to help avoid deadlocks and improve performance, it is recommended to call ConfigureAwait(false) whenever possible, in case the code is used in a context which requires it1. The code in samples is not designed to be used anywhere else as-is, so it does not contain these calls.

1 For more detail, see the ConfigureAwait FAQ.

Transport

Samples default to the learning transport as it has the least friction for experimentation. The learning transport is not for production use.

Persistence

Samples default to either the learning persistence or the Non-Durable persistence since both have no requirement on installed infrastructure. The learning persistence is not for production use.

Console hosting

Samples default to self-hosting in a console since it is the most explicit and contains fewer moving pieces. This would not be a suitable choice for a production system and other hosting options should be considered.

Logging

Samples default to logging at the Info level to the console. In production, the preferred approach is some combination of Warning and Error with a combination of targets.

Messages definitions

In many samples, messages are defined in a shared project along with reusable helper and configuration classes. This is done to reduce the number of projects in a solution. In a production solution, message definitions are usually isolated in their own projects.

Message destinations

Many samples make use of SendLocal and send to an endpoint directly by specify the destination using a string in code. This is done to simplify the amount of configuration in samples. In a production solution, most message destinations should be defined via routing configuration.

Dependency injection

Samples default to using the built-in dependency injection since it does not require any external NuGet packages. Switching to external dependency injection will give greater flexibility in customizations.

Samples

  • AWS
  • Azure Samples
  • Azure Functions
    Samples showing how to host NServiceBus within an Azure Function.
  • Azure Service Bus transport
  • Bridge samples
  • Cosmos DB
  • Data Bus Samples
  • Dependency Injection Samples
  • Encryption samples
  • Hosting Samples
  • Logging and Metrics Samples
  • MongoDB Samples
  • MSMQ Samples
  • Multi-tenant Samples
  • NHibernate Persistence Samples
  • OpenTelemetry Samples
  • Outbox Samples
    • Using Outbox with RabbitMQ
      Demonstrates how the Outbox handles duplicate messages using RabbitMQ and SQL Server hosted in Docker containers.
    • Using Outbox with SQL Server
      A sample demonstrating the SQL Server transport with SQL Persistence and ADO.NET user data store using outbox.
  • Pipeline Samples
  • ServicePlatform Connection Samples
  • PostgreSQL Transport Samples
  • Publish/Subscribe
    Sample code related to publish/subscribe.
  • RabbitMQ Transport Samples
  • RavenDB Persistence Samples
  • Routing Samples
    Sample code related to routing.
  • Saga Samples
  • Scale-out Samples
    Sample code for scaling out NServiceBus endpoints.
  • Scheduling Samples
    • Hangfire Usage
      Using Hangfire to send messages from within an NServiceBus endpoint.
    • PeriodTimer usage
      Using PeriodicTimer in a BackgroundJob to send messages from within an NServiceBus endpoint.
    • Quartz.NET Usage
      Using Quartz.NET to send messages from within an NServiceBus endpoint.
    • Scheduler
      A simple example of the NServiceBus scheduler API.
    • Scheduling with Timers
      An example of scheduling using .NET Timers.
  • Serializer Samples
  • ServiceControl Samples
  • ServiceInsight Samples
  • Showcase Samples
    More complex samples showing many features working together.
    • Cinema Showcase
      A sample for a fictional cinema demonstrating a saga that aggregates ticket sales.
    • On-Premises Showcase
      Implements a fictional store using several features of NServiceBus.
  • SQL Persistence Samples
  • SQL Server Transport Samples
  • Transactional Session Samples
  • Web Samples