Migrating from NServiceBus.MongoDB

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

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.


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.


In the sbmako 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

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.

How Document Versioning Works

MongoDB provides no out-of-the-box concurrency controls. A common pattern for supporting concurrency is using a document version number (int) that is used as a filter for update statements:

UpdateDefinition<BsonDocument> updateDefinition = updateBuilder.Inc(versionFieldName, 1);

//Define other update operations on the document

BsonDocument modifiedDocument = await collection.FindOneAndUpdateAsync<BsonDocument>(
    filter: document => document["_id"] == documentId && document["_version"] == currentVersion,
    update: updateDefinition,
    options: new FindOneAndUpdateOptions<BsonDocument, BsonDocument> { IsUpsert = false, ReturnDocument = ReturnDocument.After });

if (modifiedDocument == null)
    //The document was not updated because the version was already incremented.

By updating the document with a filter specifying the expected current version value of the document, no update will be made if another process has incremented the version before the current process is able to. This package relies on this pattern to ensure only one process/thread can update the saga at a time.

This pattern requires an element in the BsonDocument to store the current version value. Instead of requiring the user provide this as a property of their saga data type, this package uses the MongoDB client's BSON serializer to add a version element to the serialized saga data as it is initially created and stored in the collection. When the saga data serialized BsonDocument is later fetched, the version element's current value is retrieved before deserializing to the saga data type. The current value is then retained for the lifetime of saga message processing and is used to create the update filter.

By default, the BsonDocument element is named _version. To maintain compatibility with existing saga data created by community packages this package must be configured to instead use the version element name contained in the existing saga data documents.

Related Articles

Last modified