MongoDB Persistence

Source
NuGet Package NServiceBus.Storage.MongoDB (2.x)
Target NServiceBus Version: 7.x

Uses the MongoDB document database for storage.

NServiceBus.Storage.MongoDB supports MongoDB server versions 3.6 and higher

Supported persistence types

Usage

Add a NuGet package reference to NServiceBus.Storage.MongoDB. Configure the endpoint to use the persistence through the following configuration API:

endpointConfiguration.UsePersistence<MongoPersistence>();

Customizing the connection

By default, a MongoClient is created that connects to mongodb://localhost:27017 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 MongoDB.Driver.MongoClient("SharedMongoUrl"));

Specify the database to use for NServiceBus documents using the following configuration API:

var persistence = endpointConfiguration.UsePersistence<MongoPersistence>();
persistence.DatabaseName("DatabaseName");

Transactions

MongoDB transactions are enabled and required by default. This allows the persister to update multiple saga instances and commit them atomically during message processing.

MongoDB transactions require a replica set or sharded cluster. Refer to the MongoDB transaction documentation for more information about supported configurations and required MongoDB server versions.
The MongoDB persister supports transactions on shared clusters starting from version 2.1.

Disabling transactions

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);

Shared transactions

NServiceBus supports sharing MongoDB transactions between Saga persistence and business data. The shared transaction can be used to persist document updates for both concerns atomically.

To use the shared transaction in a message handler:

public Task Handle(MyMessage message, IMessageHandlerContext context)
{
    var session = context.SynchronizedStorageSession.GetClientSession();
    var collection = session.Client.GetDatabase("mydatabase").GetCollection<MyBusinessObject>("mycollection");
    return collection.InsertOneAsync(session, new MyBusinessObject());
}
In order to participate in the shared transaction the MongoDB session must be passed into collection API calls as demonstrated above.

Testing

The TestableMongoSynchronizedStorageSession class in the NServiceBus.Testing namespace has been provided to facilitate testing a handler that utilizes the shared transaction feature.

Outbox cleanup

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));

Saga concurrency

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

Example exception:

MongoDB.Driver.MongoCommandException: Command insert failed: WriteConflict.

Updating or deleting saga data

MongoDB persistence uses optimistic concurrency control when updating or deleting saga data.

Example exception:

MongoDB.Driver.MongoCommandException: Command update failed: WriteConflict.

Samples

Related Articles


Last modified