Migrating from NServiceBus.Persistence.MongoDB

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

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"));
persistence.DatabaseName("my-database");

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();
compatibility.VersionElementName("Version");

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

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 => {
    db[collectionName].updateMany({
        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.

Subscriptions

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('@');
       db.eventsubscription.insert({
           MessageTypeName: type._id.TypeName,
           TransportAddress: parts[0],
           Endpoint: parts[1]
       });
   });
});