Migrating from NServiceBus.Persistence.MongoDB

Component: MongoDB Persistence
NuGet Package NServiceBus.Storage.MongoDB (2-pre)
Target NServiceBus Version: 7.x
This page targets a pre-release version and is subject to change prior to the final release.

This 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.


Use the following compatibility 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.

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

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