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.
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.
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.
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.
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.
Unless otherwise specified (by an individual sample) the following are the default technology choices.
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 Core 3.1 requires at least Visual Studio 2019.
All samples target C# 8.0 to take advantage of the new language features. If any help is required in converting to earlier versions of C#, raise an issue.
Samples only call
ConfigureAwait(bool) when it is required. If any code is copied from samples, appropriate calls to
ConfigureAwait(bool) should be added.
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.
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.
Samples default to logging at the
Info level to the console. In production, the preferred approach is some combination of
Error with a combination of targets.
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.
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.
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.