Migrating from NServiceBus.Persistence.MongoDB

NuGet Package: NServiceBus.Storage.MongoDB (3-pre)
This page targets a pre-release version. Pre-releases are subject to change and samples are not guaranteed to be fully functional.

The NServiceBus.Storage.MongoDB package was designed to be fully compatible with the community NServiceBus.Persistence.MongoDB package with some minor configuration.

Compatibility with existing data requires additional settings which must be configured, otherwise data duplication and incorrect execution of business logic may occur.

NServiceBus upgrade

NServiceBus.Storage.MongoDB is available for NServiceBus Version 7 and later. When migrating from NServiceBus.Persistence.MongoDB it is recommended to remove the persistence package and upgrade the endpoint to NServiceBus Version 7 before installing the NServiceBus.Storage.MongoDB package.

Customizing the connection

NServiceBus.Storage.MongoDB does not provide a configuration setting to pass a connection string directly. Instead, a MongoClient can be passed to the new configuration API.

-   persistence.SetConnectionString("mongodb://localhost/my-database");
persistence.MongoClient(new MongoDB.Driver.MongoClient("mongodb://localhost"));
A database name passed in the connection string to the MongoClient is only used for authentication. Use persistence.DatabaseName(<database>) to configure the database to be used.

For more details about the MongoDB persistence configuration options, see the MongoDB persistence documentation.

Saga data class changes

Saga data classes no longer need to provide an int version property decorated with a DocumentVersion. The version property and attribute may be safely removed from saga data class implementations:

class MySagaData : IContainSagaData
	public Guid Id { get; set; }
	public string OriginatingMessageId { get; set; }
	public string Originator { get; set; }
-       [DocumentVersion]
-       public int Version { get; set; }

Saga data compatibility mode

Use the following API to configure the package to work with existing saga data:

var persistence = endpointConfiguration.UsePersistence<MongoPersistence>();
var compatibility = persistence.CommunityPersistenceCompatibility();

The VersionElementName value must match the BsonDocument element name used by the previous saga data property decorated with the [DocumentVersion] attribute.

The version element name must be set taking into account any member mapping conventions configured for the MongoDB client.

Migrating saga data

As an alternative to compatibility mode, saga data created by the NServiceBus.Persistence.MongoDB package can be migrated to the data format used by the NServiceBus.Storage.MongoDB package. This approach requires the endpoint to be stopped during migration. Use the mongo shell to connect to the database and execute the following script:

db.getCollectionNames().forEach(collectionName => {
        Originator: { $exists: true },
        OriginalMessageId: { $exists: true }
        $rename: { "Version": "_version" }

Replace "Version" with the name of the version property on the saga data which was previously decorated with the [DocumentVersion] attribute.

Be sure to create a backup of the database prior to migrating the saga data.


Subscriptions are recreated by restarting the subscribing endpoints. Alternatively, existing subscriptions can be migrated to the new data format.

Migrating subscriptions

In the Ryan Hoffman implementation there is a single document per event type containing a collection of subscribers. In NServiceBus.Storage.MongoDB, subscriptions are individual documents. Each subscription needs to be converted into an eventsubscription document.

db.subscriptions.find().forEach(type => {
   type.Subscribers.forEach(subscription => {
       var parts = subscription.split('@');
           MessageTypeName: type._id.TypeName,
           TransportAddress: parts[0],
           Endpoint: parts[1]

Related Articles

Last modified