MongoDB v6 upgrade guide and snippets

Snippets/MongoDB/MongoDB.sln

@@ -12,6 +12,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MongoDB_5", "MongoDB_5\Mong
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MongoDB_6", "MongoDB_6\MongoDB_6.csproj", "{58940814-447D-457B-B541-1BFB51820F7F}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MongoDB_7", "MongoDB_7\MongoDB_7.csproj", "{2146CB07-4B91-40AA-B52B-69A6A6302743}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -27,6 +29,8 @@ Global
 		{D114D094-6ABB-4922-832B-ECBF8A213228}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{58940814-447D-457B-B541-1BFB51820F7F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{58940814-447D-457B-B541-1BFB51820F7F}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{2146CB07-4B91-40AA-B52B-69A6A6302743}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{2146CB07-4B91-40AA-B52B-69A6A6302743}.Debug|Any CPU.Build.0 = Debug|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

Snippets/MongoDB/MongoDB_6/CustomProvider.cs

@@ -0,0 +1,30 @@
+using Microsoft.Extensions.DependencyInjection;
+using MongoDB.Driver;
+using NServiceBus;
+using NServiceBus.Storage.MongoDB;
+
+#region MongoDBClientProvider
+
+class CustomMongoClientProvider
+    : IMongoClientProvider
+{
+    // get fully configured via DI
+    public CustomMongoClientProvider(IMongoClient mongoClient)
+    {
+        Client = mongoClient;
+    }
+    public IMongoClient Client { get; }
+}
+#endregion
+
+class CustomMongoClientProviderRegistration
+{
+    public CustomMongoClientProviderRegistration(EndpointConfiguration endpointConfiguration)
+    {
+        #region MongoDBCustomClientProviderRegistration
+
+        endpointConfiguration.RegisterComponents(c => c.AddTransient<IMongoClientProvider, CustomMongoClientProvider>());
+
+        #endregion
+    }
+}

Snippets/MongoDB/MongoDB_6/MongoDB_6.csproj

@@ -1,8 +1,8 @@
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
-    <TargetFramework>net10.0</TargetFramework>
+    <TargetFramework>net8.0</TargetFramework>
   </PropertyGroup>
   <ItemGroup>
-    <PackageReference Include="NServiceBus.Storage.MongoDB" Version="6.0.0-alpha.2" />
+    <PackageReference Include="NServiceBus.Storage.MongoDB" Version="6.*" />
   </ItemGroup>
 </Project>

Snippets/MongoDB/MongoDB_6/Usage.cs

@@ -47,8 +47,28 @@ void TimeToKeepOutboxDeduplicationData(EndpointConfiguration endpointConfigurati
     {
         #region MongoDBOutboxCleanup
 
+        var outbox = endpointConfiguration.EnableOutbox();
+        outbox.TimeToKeepOutboxDeduplicationData(TimeSpan.FromDays(30));
+
+        #endregion
+    }
+
+    void DisableReadFallback(EndpointConfiguration endpointConfiguration)
+    {
+        #region MongoDBDisableReadFallback
+
+        var outbox = endpointConfiguration.EnableOutbox();
+        outbox.DisableReadFallback();
+
+        #endregion
+    }
+
+    void DisableInstaller(EndpointConfiguration endpointConfiguration)
+    {
+        #region MongoDBDisableInstaller
+
         var persistence = endpointConfiguration.UsePersistence<MongoPersistence>();
-        persistence.TimeToKeepOutboxDeduplicationData(TimeSpan.FromDays(30));
+        persistence.DisableInstaller();
 
         #endregion
     }

Snippets/MongoDB/MongoDB_7/CustomProvider.cs

@@ -0,0 +1,30 @@
+using Microsoft.Extensions.DependencyInjection;
+using MongoDB.Driver;
+using NServiceBus;
+using NServiceBus.Storage.MongoDB;
+
+#region MongoDBClientProvider
+
+class CustomMongoClientProvider
+    : IMongoClientProvider
+{
+    // get fully configured via DI
+    public CustomMongoClientProvider(IMongoClient mongoClient)
+    {
+        Client = mongoClient;
+    }
+    public IMongoClient Client { get; }
+}
+#endregion
+
+class CustomMongoClientProviderRegistration
+{
+    public CustomMongoClientProviderRegistration(EndpointConfiguration endpointConfiguration)
+    {
+        #region MongoDBCustomClientProviderRegistration
+
+        endpointConfiguration.RegisterComponents(c => c.AddTransient<IMongoClientProvider, CustomMongoClientProvider>());
+
+        #endregion
+    }
+}

Snippets/MongoDB/MongoDB_7/DocumentVersion.cs

@@ -0,0 +1,30 @@
+using System;
+using System.Threading.Tasks;
+using MongoDB.Bson;
+using MongoDB.Driver;
+
+class DocumentVersion
+{
+    async Task UpdateWithVersion(IMongoCollection<BsonDocument> collection, string versionFieldName, UpdateDefinitionBuilder<BsonDocument> updateBuilder, int currentVersion, Guid documentId)
+    {
+        #region MongoDBUpdateWithVersion
+
+        UpdateDefinition<BsonDocument> updateDefinition = updateBuilder.Inc(versionFieldName, 1);
+        FilterDefinition<BsonDocument> filterDefinition = Builders<BsonDocument>.Filter.Eq("_id", documentId)
+            & Builders<BsonDocument>.Filter.Eq(versionFieldName, currentVersion);
+
+        //Define other update operations on the document
+
+        var modifiedDocument = await collection.FindOneAndUpdateAsync(
+            filter: filterDefinition,
+            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.
+        }
+
+        #endregion
+    }
+}

Snippets/MongoDB/MongoDB_7/MongoDB_7.csproj

@@ -0,0 +1,8 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="NServiceBus.Storage.MongoDB" Version="7.0.0-alpha.1" />
+  </ItemGroup>
+</Project>

Snippets/MongoDB/MongoDB_7/SharedTransaction.cs

@@ -0,0 +1,25 @@
+using System.Threading.Tasks;
+using NServiceBus;
+
+class SharedTransaction : IHandleMessages<MyMessage>
+{
+    #region MongoDBHandlerSharedTransaction
+
+    public Task Handle(MyMessage message, IMessageHandlerContext context)
+    {
+        var session = context.SynchronizedStorageSession.GetClientSession();
+        var collection = session.Client.GetDatabase("mydatabase").GetCollection<MyBusinessObject>("mycollection");
+        return collection.InsertOneAsync(session, new MyBusinessObject(), null, context.CancellationToken);
+    }
+
+    #endregion
+}
+
+class MyMessage
+{
+}
+
+class MyBusinessObject
+{
+}
+

Snippets/MongoDB/MongoDB_7/SharedTransactionDI.cs

@@ -0,0 +1,30 @@
+using System.Threading.Tasks;
+using NServiceBus.Storage.MongoDB;
+
+public class SharedTransactionDI
+{
+    #region MongoDBSharedTransactionDI
+    class MyService
+    {
+        IMongoSynchronizedStorageSession sharedSession;
+
+        // Resolved from DI container
+        public MyService(IMongoSynchronizedStorageSession sharedSession)
+        {
+            this.sharedSession = sharedSession;
+        }
+
+        public Task Create()
+        {
+            return sharedSession.MongoSession.Client
+                .GetDatabase("mydatabase")
+                .GetCollection<MyBusinessObject>("mycollection")
+                .InsertOneAsync(sharedSession.MongoSession, new MyBusinessObject());
+        }
+    }
+    #endregion
+
+    class MyBusinessObject
+    {
+    }
+}

Snippets/MongoDB/MongoDB_7/Usage.cs

@@ -0,0 +1,98 @@
+using System;
+using MongoDB.Driver;
+using NServiceBus;
+
+public class Usage
+{
+    Usage(EndpointConfiguration endpointConfiguration)
+    {
+        #region MongoDBUsage
+
+        endpointConfiguration.UsePersistence<MongoPersistence>();
+
+        #endregion
+    }
+
+    void MongoClient(EndpointConfiguration endpointConfiguration)
+    {
+        #region MongoDBClient
+
+        var persistence = endpointConfiguration.UsePersistence<MongoPersistence>();
+        persistence.MongoClient(new MongoClient("SharedMongoUrl"));
+
+        #endregion
+    }
+
+    void DatabaseName(EndpointConfiguration endpointConfiguration)
+    {
+        #region MongoDBDatabaseName
+
+        var persistence = endpointConfiguration.UsePersistence<MongoPersistence>();
+        persistence.DatabaseName("DatabaseName");
+
+        #endregion
+    }
+
+    void UseTransactions(EndpointConfiguration endpointConfiguration)
+    {
+        #region MongoDBDisableTransactions
+
+        var persistence = endpointConfiguration.UsePersistence<MongoPersistence>();
+        persistence.UseTransactions(false);
+
+        #endregion
+    }
+
+    void TimeToKeepOutboxDeduplicationData(EndpointConfiguration endpointConfiguration)
+    {
+        #region MongoDBOutboxCleanup
+
+        var outbox = endpointConfiguration.EnableOutbox();
+        outbox.TimeToKeepOutboxDeduplicationData(TimeSpan.FromDays(30));
+
+        #endregion
+    }
+
+    void DisableReadFallback(EndpointConfiguration endpointConfiguration)
+    {
+        #region MongoDBDisableReadFallback
+
+        var outbox = endpointConfiguration.EnableOutbox();
+        outbox.DisableReadFallback();
+
+        #endregion
+    }
+
+    void DisableInstaller(EndpointConfiguration endpointConfiguration)
+    {
+        #region MongoDBDisableInstaller
+
+        var persistence = endpointConfiguration.UsePersistence<MongoPersistence>();
+        persistence.DisableInstaller();
+
+        #endregion
+    }
+
+    void SBMakoCompatibility(EndpointConfiguration endpointConfiguration)
+    {
+        #region MongoDBSBMakoCompatibility
+
+        var persistence = endpointConfiguration.UsePersistence<MongoPersistence>();
+        var compatibility = persistence.CommunityPersistenceCompatibility();
+        compatibility.CollectionNamingConvention(type => type.Name);
+        compatibility.VersionElementName("DocumentVersion");
+
+        #endregion
+    }
+
+    void TekmavenCompatibility(EndpointConfiguration endpointConfiguration)
+    {
+        #region MongoDBTekmavenCompatibility
+
+        var persistence = endpointConfiguration.UsePersistence<MongoPersistence>();
+        var compatibility = persistence.CommunityPersistenceCompatibility();
+        compatibility.VersionElementName("Version");
+
+        #endregion
+    }
+}

menu/menu.yaml

@@ -1160,6 +1160,8 @@
       Articles:
       - Url: persistence/upgrades/mongodb-4to5
         Title: Version 4 to 5
+      - Url: persistence/upgrades/mongodb-5to6
+        Title: Version 5 to 6        
     - Title: RavenDB
       Articles:
       - Url: persistence/upgrades/ravendb-9to10

persistence/mongodb/index.md

@@ -4,6 +4,7 @@ component: mongodb
 versions: '[2,)'
 related:
 - samples/mongodb
+- samples/outbox/mongodb
 redirects:
 - persistence/mongodb-tekmaven
 - nservicebus/messaging/databus/mongodb-tekmaven
@@ -46,6 +47,8 @@ Specify the database to use for NServiceBus documents using the following config
 
 snippet: MongoDBDatabaseName
 
+partial: provider
+
 ## Transactions
 
 MongoDB [transactions](https://docs.mongodb.com/manual/core/transactions/) are enabled and required by default. This allows the persister to use pessimistic locking and to update multiple saga instances and commit them atomically during message processing.
@@ -89,21 +92,22 @@ snippet: MongoDBSharedTransactionDI
 
 The `TestableMongoSynchronizedStorageSession` class in the `NServiceBus.Testing` namespace has been provided to facilitate [testing a handler](/nservicebus/testing/) that utilizes the shared transaction feature.
 
-## Outbox 
+## Outbox
 
 ## Storage format
 
 Outbox record documents are stored in a collection called `outboxrecord`.
 
-> [!WARNING]
-> Outbox documents are not separated by endpoint name which means that it's not supported for multiple logical endpoints to share the same database since [message identities are not unique across endpoints from a processing perspective](/nservicebus/outbox/#message-identity).
+partial: outboxstorage
 
 ### Outbox cleanup
 
 When the outbox is enabled, the deduplication data is kept for seven days by default. To customize this time frame, use the following API:
 
 snippet: MongoDBOutboxCleanup
 
+partial: outboxfallback
+
 ## Saga concurrency
 
 When simultaneously handling messages, conflicts may occur. See below for examples of the exceptions which are thrown. _[Saga concurrency](/nservicebus/sagas/concurrency.md)_ explains how these conflicts are handled and contains guidance for high-load scenarios.
@@ -135,3 +139,7 @@ MongoDB.Driver.MongoCommandException: Command update failed: WriteConflict.
 ```
 
 include: saga-concurrency
+
+## Installer
+
+partial: installer

persistence/mongodb/index_installer_mongodb_[,6).partial.md

@@ -0,0 +1 @@
+Installers are not supported. Indexes are created regardless of the installer settings.

persistence/mongodb/index_installer_mongodb_[6,).partial.md

@@ -0,0 +1,5 @@
+Indexes are only created when the installers are enabled.
+
+In non-development environments, where the indexes are managed by other means (e.g. Ops Manager), it may be necessary to explicitly disable the persistence installers if [standard installers](/nservicebus/operations/installers.md) need to be used for other purposes.
+
+snippet: MongoDBDisableInstaller