Migrating from NServiceBus.MongoDB

Component: MongoDB Persistence
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.

This package was designed to be fully compatible with the community NServiceBus.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. It is recommended to upgrade endpoints to NServiceBus Version 7 before migrating to the NServiceBus.Storage.MongoDB package.

Saga data class changes

Saga data classes no longer need to implement IHaveDocumentVersion. If the saga data class extends ContainMongoSagaData, it no longer needs to do so. In cases where IHaveDocumentVersion has been explicitly implemented by the saga data class, the DocumentVersion and ETag properties may be safely removed from saga data class implementations.

- class MySagaData : IContainSagaData, IHaveDocumentVersion
+ class MySagaData : IContainSagaData
	public Guid Id { get; set; }
	public string OriginatingMessageId { get; set; }
	public string Originator { get; set; }
-       public int DocumentVersion { get; set; }
-       public int ETag { get; set; }

If the ETag property is not removed, it will no longer be updated by the persister.

Saga data compatibility mode

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

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

The VersionElementName value must match the element name used for the DocumentVersion property from the community persister.

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

In addition, the collection naming convention for sagas must be configured to match the one used by NServiceBus.MongoDB, type => type.Name, as demonstrated in the above snippet.


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

Migrating subscriptions

In the Carlos Sandoval implementation subscriptions are stored in the collection named Subscription. Each document maps to an event type containing a set of subscribers using the type Subscriber from the NServiceBus package.

The following migration script iterates through the documents and insert each subscriber value as a new document.

db.subscription.find().forEach(type => {
   type.Subscribers.forEach(subscription => {
           MessageTypeName: type._id.TypeName,
           TransportAddress: subscription.TransportAddress,
           Endpoint: subscription.Endpoint

Related Articles

Last modified