Getting Started

Architecture

Service Platform

NServiceBus

Transports

Persistence

Hosting

ServiceInsight

ServicePulse

ServiceControl

Monitoring

Modernization

Shape the future

Samples

General
Aspire
AsyncAPI
AWS
Azure
Azure Functions
Azure Service Bus transport
Bridge samples
Cosmos DB
Data Bus
Dependency Injection
Encryption samples
Hosting
IBM MQ Transport
Logging and Metrics
MongoDB
Multi-tenant
NHibernate Persistence
OpenTelemetry
Outbox
Pipeline
ServicePlatform Connection
PostgreSQL Transport
Publish/Subscribe
RabbitMQ Transport
RavenDB Persistence
Routing
Saga
Scheduling
Serializer
ServiceControl
Showcase
SQL Persistence
SQL Server Transport
Transactional Session
Web

Overview

Feedback

Article navigation

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. See about the samples for important information about the samples and the code contained within them.

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

Samples

Automatic Retries
Shows immediate and delayed retries when a handler throws an exception.
Building a custom feature
How to build a custom feature in NServiceBus.
Callback Usage
Demonstrates the use of callbacks.
Consumer-driven Contracts sample
NServiceBus sample that shows a consumer-driven contract (CDC) approach to messaging.
Cooperative cancellation
Stopping both the endpoint and a long running handler with a cancellation token.
Custom Recoverability
Custom Recoverability Messaging Policy approaches to help with failure scenarios.
Delayed Delivery
A simple ordering system that defers handling or delivery of a message.
Entity Framework Core integration with SQL Persistence
Integrating Entity Framework Core with SQL Persistence.
Fault Tolerance
Messaging approaches to help with failure scenarios.
Full Duplex
Using full-duplex and request/response communication.
Gateway
Header Manipulation
All extension points for mutating messages.
Immutable Messages samples
Demonstrate how to use immutable messages when exchanging messages between endpoints.
Message Mutators
Change messages by plugging custom logic in to a couple of interfaces, encrypting as required.
Message Throughput Throttling
Near Real-Time Occasionally-Connected Clients
How to relay NServiceBus events to occasionally-connected clients via SignalR.
Performance Counter Usage
Using the built-in Performance Counters.
Sharing message assemblies
Demonstrate how the NServiceBus.MessageInterfaces package enables message assemblies to be shared across major versions of NServiceBus.
SQL Server Transport and NHibernate Persistence
Integrating SQL Server transport with NHibernate persistence.
SQL Server Transport and SQL Persistence
Integrating the SQL Server transport with SQL persistence.
Unit Testing a custom recoverability policy
Writing unit tests for custom recoverability policies.
Unit Testing NServiceBus
Writing unit tests for NServiceBus systems.
Unobtrusive
Demonstrates NServiceBus operating in unobtrusive mode.
Versioning
Message evolution over time using interfaces.

Aspire Samples

Particular Platform in Aspire
Minimal orchestrating the Particular Platform via Aspire.
Particular Platform with ASB in Aspire
Orchestrating the Particular Platform with Azure ServiceBus transport via Aspire.
Particular Platform with RabbitMQ in Aspire
Orchestrating the Particular Platform with RabbitMQ transport via Aspire.
Particular Platform with SQL Server in Aspire
Orchestrating the Particular Platform with SQL Server transport via Aspire.
Particular Platform with Amazon SQS in Aspire
Orchestrating the Particular Platform with Amazon SQS transport via Aspire.

AsyncAPI

AsyncAPI with custom message conventions
How to generate an AsyncAPI schema document from NServiceBus with custom message conventions.
Simple AsyncAPI
How to generate an AsyncAPI schema document from NServiceBus.

AWS

AmazonSQS CloudEvents Sample
Demonstrates how to consume CloudEvents received through Amazon SQS.
Simple DynamoDB Persistence Usage
Using DynamoDB Persistence to store sagas.
DynamoDB Persistence Usage with transactions
Using DynamoDB persistence to store sagas and outbox records atomically.
Using NServiceBus in AWS Lambda with SQS
Using NServiceBus in AWS Lambda with annotations and SQS
Using NServiceBus Sagas with AWS Lambda, SQS, and DynamoDB
A sample demonstrating the AWS DynamoDB persistence, AWS Lambda, and AWS SQS with NServiceBus sagas.
Using NServiceBus Sagas with AWS Lambda, SQS, and Aurora
A sample demonstrating the AWS Aurora persistence, AWS Lambda, and AWS SQS with NServiceBus sagas.
AmazonSQS transport native integration sample
Simple AmazonSQS Transport usage

Azure Samples

Using NServiceBus with Azure Table
Azure Table Persistence Using Saga IDs as Partition Keys
Using Saga IDs as partition keys in Azure Table Persistence to store sagas and outbox records atomically.
Simple Azure Table Persistence Usage
Using Azure Table Persistence to store sagas.
AzureTable Persistence Usage with non-default table
Using Azure Table Persistence to store sagas providing a non-default table dynamically.
Azure Table Persistence Usage with Transactions
Using Azure Table Persistence to store sagas and outbox records atomically.
Custom audit transport
Azure Service Bus endpoint with audit via Azure Storage Queue.
Azure Storage Queues transport native integration sample
Consuming messages sent by non-NServiceBus endpoints with the Azure Storage Queues transport.
Azure Storage Queues Transport
Self-Hosting in Azure WebJobs
Host an NServiceBus endpoint in Azure WebJobs.

Azure Functions
Samples showing how to host NServiceBus within an Azure Function.

Using NServiceBus in Azure Functions
Using NServiceBus with Azure Service Bus triggers and Azure Functions hosting.
Using NServiceBus and Kafka in Azure Functions (isolated)
Using NServiceBus with Kafka triggers and Azure Functions isolated worker hosting model.
Using NServiceBus in Azure Functions (isolated worker)
Using NServiceBus with Azure Service Bus triggers and Azure Functions isolated worker hosting model.

Azure Service Bus transport

Azure Service Bus CloudEvents Sample
Demonstrates how to consume CloudEvents received through Azure Service Bus.
Azure Service Bus Hierarchy Namespace Sample
Demonstrates how to use hierarchical namespaces with Azure Service Bus.
Azure Service Bus KeyVault Sample
Demonstrates how to use KeyVault to store connection string to the Azure Service Bus.
Azure Service Bus transport native integration sample
How to consume messages published by non-NServiceBus endpoints.
Azure Service Bus Pub/Sub Native Integration
How to consume event messages published by non-NServiceBus endpoints.
Azure Service Bus Topology Options
How to use topology options to layout the topic topology in app settings.
Build message-driven business applications with NServiceBus
Build message-driven business applications with NServiceBus and Azure Service Bus.
Azure Service Bus Send/Reply Sample
Demonstrates the send/reply pattern with Azure Service Bus.
Azure Service Bus topology migration
Demonstrates how to migrate from the single-topic to topic-per-event topology.

Bridge samples

Bridge messages between endpoints using MSMQ and Azure Service Bus
A sample showing how to send messages between endpoints using different transports using NServiceBus Messaging Bridge.
Use Bridge to connect to ServiceControl running on different transport
Centralize monitoring of mixed transport solution with the Bridge.
Simple Bridge Usage
How to use the NServiceBus messaging bridge to connect endpoints on different transports.
Multi-Instance Mode
SQL Server transport running in multi-instance mode using Bridge.

Cosmos DB

Cosmos DB Persistence Usage with non-default container
Using Cosmos DB Persistence to store sagas providing a non-default container dynamically.
Simple Cosmos DB Persistence Usage
Using Cosmos DB Persistence to store sagas.
Cosmos DB Persistence Usage with transactions
Using Cosmos DB Persistence to store sagas and outbox records atomically.

Data Bus Samples

Azure Blob Storage DataBus
Sending large attachments with NServiceBus over Azure blob storage.
Azure Blob Storage Data Bus Cleanup with Azure Functions
Using an Azure Function instead of the built in blob cleanup capabilities.
Custom Serializer for Data Bus
Send a message that includes a DataBus property serialized using a custom serializer.
Databus with SystemJsonSerializer message serializer
The file share data bus allows large properties to be transferred via a Windows file share using custom converter for SystemJsonSerializer.
File Share Data Bus Usage
The file share data bus allows large properties to be transferred via a Windows file share.
Redis claim check
Implementing the claim check pattern with Redis.

Dependency Injection Samples

ASP.NET Core Dependency Injection Integration
Externally Managed Mode
A sample that uses the externally managed mode feature to configure a dependency injection container.

Encryption samples

Message property encryption
Encrypting specific parts of a message using the message property encryption feature.
Unobtrusive property encryption
Encrypting specific parts of a message using conventions.
Message body encryption
Encrypting the full message body using a mutator.

Hosting Samples

Hosting endpoints in Aspire
Hosting endpoints in Docker Linux containers
Hosting multiple endpoints in several Docker Linux containers managed by Docker Compose.
Endpoint hosting with the Generic Host
Hosting an endpoint with the Microsoft Generic Host.

IBM MQ Transport Samples

IBM MQ EBCDIC interoperability
Receiving fixed-length EBCDIC-encoded messages from a legacy mainframe system via IBM MQ.
IBM MQ polymorphic event routing
Demonstrating explicit subscription routing so that a handler for a base event type receives messages published as derived types.
IBM MQ simple sender/receiver
Sending commands from a send-only endpoint to a receiving endpoint using the IBM MQ transport.

Logging and Metrics Samples

Capture and visualize metrics using Datadog
Illustrates how to capture, store, and visualize NServiceBus metrics in Datadog.
Default Logging
The default logging capability of NServiceBus.
NServiceBus.Extensions.Logging Usage
A sample that uses Microsoft.Extensions.Logging with NLog.
Write metrics to the trace log
How to write metrics information to the trace log.
Capture and visualize metrics using NewRelic
Illustrates how to capture, store, and visualize NServiceBus metrics in NewRelic.
Notifications

MongoDB Samples

MongoDB Persistence
Learn how to use MongoDB as a persistence mechanism for NServiceBus, including saga and timeout storage.

Multi-tenant Samples

Injecting tenant-aware components into message handlers
How to configure IoC to inject tenant-aware components into message handlers.
NHibernate persistence in multi-tenant systems
Configure NHibernate persistence to support multi-tenant scenarios.
Propagating Tenant Information to Downstream Endpoints
How to configure the pipeline to propagate tenant information to downstream endpoints automatically.
RavenDB Persistence in multi-tenant systems
Configure RavenDB Persistence to support multi-tenant scenarios.
SQL Persistence in multi-tenant system
Configure SQL Persistence to support multi-tenant scenarios.

NHibernate Persistence Samples

NServiceBus.NHibernate custom saga mapping sample
An NServiceBus sample demonstrating a custom saga mapping to change how NHibernate creates the database schema using different techniques.
Simple NHibernate Persistence Usage
Using NHibernate to store sagas and timeouts.

OpenTelemetry Samples

Monitoring NServiceBus endpoints with Application Insights
How to configure NServiceBus to export OpenTelemetry traces and meters to Application Insights.
Customizing OpenTelemetry tracing
Demonstrates how to add data to existing OpenTelemetry traces.
Monitoring NServiceBus endpoints with Jaeger
How to configure NServiceBus to export OpenTelemetry traces to Jaeger.
Connecting OpenTelemetry traces and logs
How to connect OpenTelemetry traces to logs in an NServiceBus endpoint.
Use a shim to expose NServiceBus.Metrics via OpenTelemetry
How to set up a shim to expose NServiceBus.Metrics via OpenTelemetry.
Monitoring NServiceBus endpoints with Prometheus and Grafana
How to configure NServiceBus to export OpenTelemetry metrics to Prometheus and Grafana.

Outbox Samples

Using Outbox with CosmosDB
Demonstrates how the Outbox handles duplicate messages using RabbitMQ and CosmosDb hosted in Docker containers.
Using Outbox with MongoDB
Demonstrates how the Outbox handles duplicate messages using RabbitMQ and MongoDB hosted in Docker containers.
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

Audit Filter Pipeline Extension
Extending the pipeline to stop certain messages from being audited.
Dispatch notification pipeline extension
Extending the pipeline to fire a notification when messages are dispatched.
Add feature toggles to handlers
Checks feature toggles to determine whether or not a handler should be executed for a given message.
Repair malformed messages using pipeline behavior
A sample showing how to repair malformed messages by implementing a pipeline behavior.
Header propagation using the pipeline
How to use the pipeline to copy a header from incoming messages to outgoing messages.
Consuming MassTransit messages with NServiceBus
Use the NServiceBus pipeline to consume messages sent by MassTransit.
Message signing using NServiceBus pipeline behaviors
Shows how to implement message signing and verification using NServiceBus pipeline behaviors.
Session filter pipeline extension
How to extend the pipeline to filter out messages from older sessions.
Unit of work using custom pipeline behavior
How to use IoC and a pipeline behavior to create a custom unit of work implementation.

ServicePlatform Connection Samples

Connect to ServicePlatform with code-first configuration
A sample that shows how to connect an NServiceBus endpoint to the Particular Service Platform using the code-first API.
Connect to ServicePlatform with JSON configuration
A sample that shows how to connect an NServiceBus endpoint to the Particular Service Platform using the JSON schema.
Connect to ServicePlatform using the .NET Generic Host
A sample that shows how to connect an NServiceBus endpoint hosted in the .NET Generic Host to the Particular Service Platform.

PostgreSQL Transport Samples

Simple PostgreSQL transport usage
Learn how to configure NServiceBus with the PostgreSQL transport to send commands and publish events between endpoints using native publish-subscribe.

Publish/Subscribe
Sample code related to publish/subscribe.

Native Publish/Subscribe
Publish/Subscribe with multicast-enabled transports.

RabbitMQ Transport Samples

RabbitMQ transport native integration sample
Consuming messages published by non-NServiceBus endpoints.
Simple RabbitMQ Transport Usage

RavenDB Persistence Samples

Simple RavenDB Persistence Usage
Using RavenDB to store Sagas.

Routing Samples
Sample code related to routing.

Command routing
Basic NServiceBus message routing.
Message forwarding
Forwarding a copy of every message to another destination after it is processed.

Saga Samples

Batch messages using sagas
Use batching when generating tasks using sagas.
NHibernate Custom Saga Finding Logic
Implement custom saga-finding behavior using custom query logic when saga data is stored in a relational database and accessed via the NHibernate ORM.
Simple Saga Usage
How build and use a saga.
SQL Persistence Saga Finding Logic
Perform custom saga finding logic based on custom queries when the Saga storage is the native SQL Persistence.

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.
Scheduling with Timers
An example of scheduling using .NET Timers.

Serializer Samples

Avro Serializer sample
NServiceBus sample that shows how to use the Avro serializer in an endpoint.
Multiple Deserializers
Using the AddDeserializer API to enable deserializing multiple formats.
Newtonsoft JSON Serializer sample
NServiceBus sample that shows how to use the Newtonsoft JSON serializer in an endpoint.
Newtonsoft BSON Serializer
Using the Newtonsoft BSON serializer in an endpoint.
System.Text.Json Serializer sample
NServiceBus sample that shows how to use the builtin System.Text.Json serializer in an endpoint.
Transition serialization formats
An approach for introducing a breaking change to message serialization with no downtime.
XML Serializer sample
NServiceBus sample that shows how to use the default NServiceBus XML serializer.

ServiceControl Samples

Monitor ServiceControl events with Azure Application Insights
A sample showing how to monitor events published by ServiceControl with Azure Application Insights.
Monitor with ServiceControl events
A sample showing how to monitor events in ServiceControl.
Repair malformed messages using ServiceControl retry redirects
A sample showing how to repair malformed messages by redirecting them to a temporary endpoint.
Monitor third-party systems with custom checks
Monitoring third-party systems which are exposed as HTTP endpoints with custom checks.
Retry failed messages using ServicePulse
A sample showing how to retry failed messages.

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

Injecting repository pattern services
Inject services into an endpoint that share the same DbConnection used by NServiceBus.
SQL Persistence Saga Rename
Renaming a saga that is stored in the SQL Persistence.
Simple SQL Persistence Usage
Using SQL Persistence to store sagas and timeouts.
Transitioning Saga Correlation IDs
An approach for transitioning between different correlation IDs with no downtime.

SQL Server Transport Samples

SQL Server transport native integration sample
Integrating natively with the SQL Server transport.
Simple SQL Server transport usage
A simple send and receive scenario with the SQL Server transport.

Transactional Session Samples

Using TransactionalSession with Entity Framework and ASP.NET Core
Transactional Session sample that illustrates how to send messages and modify data with Entity Framework in an atomic manner using ASP.NET Core.
Using Transactional Session with CosmosDB
Transactional Session sample that illustrates how to send messages and modify data with CosmosDB in an atomic manner outside message handlers.

Web Samples

Using NServiceBus in an ASP.NET Core Web Application

Feedback

Overview

Samples

In this article