Uses the MongoDB document database for storage.
Persistence at a glance
For a description of each feature, see the persistence at a glance legend.
|Supported storage types||Sagas, Outbox, Subscriptions|
|Transactions||Enabled and required by default|
|Concurrency control||Pessimistic concurrency only|
|Scripted deployment||Not supported|
|Installers||None. Documents are created in database at runtime as needed.|
Add a NuGet package reference to
NServiceBus.. Configure the endpoint to use the persistence through the following configuration API:
Customizing the connection
By default, a
MongoClient is created that connects to
mongodb:/ and uses the endpoint name as its database name.
Customize the server, port, and authentication database using the following configuration API:
var persistence = endpointConfiguration.UsePersistence<MongoPersistence>(); persistence.MongoClient(new MongoClient("SharedMongoUrl"));
Specify the database to use for NServiceBus documents using the following configuration API:
var persistence = endpointConfiguration.UsePersistence<MongoPersistence>(); persistence.DatabaseName("DatabaseName");
MongoDB transactions are enabled and required by default. This allows the persister to use pessimistic locking and to update multiple saga instances and commit them atomically during message processing.
The following configuration API is available for compatibility with MongoDB server configurations which don't support transactions:
var persistence = endpointConfiguration.UsePersistence<MongoPersistence>(); persistence.UseTransactions(false);
Note that this disables the ability to use pessimistic locking for sagas which might result in higher contention in the database.
NServiceBus supports sharing MongoDB sessions between Saga persistence, Outbox storage, and business data. The shared session can be used to persist multiple document updates atomically.
To use the shared transaction in a message handler:
The shared session can also be accessed via dependency injection using the
IMongoSynchronizedStorageSessionlifetime is scoped to the message processing pipeline. Do not resolve the shared session into dependencies with a Singleton lifetime.
TestableMongoSynchronizedStorageSession class in the
NServiceBus. namespace has been provided to facilitate testing a handler that utilizes the shared transaction feature.
When the outbox is enabled, the deduplication data is kept for seven days by default. To customize this time frame, use the following API:
var persistence = endpointConfiguration.UsePersistence<MongoPersistence>(); persistence.TimeToKeepOutboxDeduplicationData(TimeSpan.FromDays(30));
When simultaneously handling messages, conflicts may occur. See below for examples of the exceptions which are thrown. Saga concurrency explains how these conflicts are handled, and contains guidance for high-load scenarios.
Starting a saga
MongoDB.Driver.MongoCommandException: Command insert failed: WriteConflict.
Updating or deleting saga data
Starting from version 2.2, MongoDB persistence uses exclusive locks when updating or deleting saga data. The saga persister tries to acquire an exclusive lock on the saga data for up to 60 seconds. If, within this time period, an exclusive lock cannot be acquired, a
TimeoutException is thrown and regular message retry policies are applied.
System.TimeoutException: Unable to acquire exclusive write lock for saga on collection 'collectionName'
In versions prior to version 2.2, MongoDB persistence uses optimistic concurrency control when updating or deleting saga data.
MongoDB.Driver.MongoCommandException: Command update failed: WriteConflict.
Handlemethod on the saga will be invoked, even though the message might be later rolled back. Hence it is important to ensure not to perform any work in saga handlers that can't roll back together with the message. This also means that should there be high levels of concurrency there will be N-1 rollbacks where N is the number of concurrent messages. This can cause throughput issues and might require design changes.