migrating-from-tekmaven.md

title	component	versions	related	reviewed
Migrating from NServiceBus.Persistence.MongoDB	mongodb	[1,)	persistence/mongodb/migrating-from-sbmako	2024-05-08

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

include: migration-warning

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

Warning

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:

snippet: MongoDBTekmavenCompatibility

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

include: must-apply-conventions-for-version

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 previously decorated with the [DocumentVersion] attribute.

Warning

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

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