Skip to main content

The power of Cosmos DB comes to NServiceBus

Update: NServiceBus persistence for Cosmos DB is now 1.0. In addition to full production support, that means API stability and backporting of bugfixes. See our release announcement here.

With the recent preview release of NServiceBus.Persistence.CosmosDB, you can now use Azure Cosmos DB with NServiceBus! Backed by Cosmos DB, a fully managed, globally distributed, elastically scaled, pay-as-you-go service, your NServiceBus-based systems can benefit from guaranteed single-digit-millisecond latency with 99.999% availability. If you are already using Cosmos DB to store your business data, you no longer need to use a different storage technology to store your NServiceBus saga data.

NServiceBus.Persistence.CosmosDB provides an alternative to our other Azure native saga storage options, such as Azure Storage Persistence running on Azure Table Storage or SQL Persistence running on Azure SQL.

Using Cosmos DB with NServiceBus allows you to leverage our outbox feature, which provides incoming message idempotence, exactly-once handler processing, and guaranteed at-least-once outgoing message delivery. When your handlers also persist data using Cosmos DB you can take advantage of shared transactions to ensure all of your data, including the data stored for NServiceBus features, are committed together.

🔗Getting started is easy

To simply store saga data using Cosmos DB, this is all that’s needed:

    .CosmosClient(new CosmosClient("ConnectionString"))
        containerName: "OrderSagas",
        partitionKeyPath: "/id");

For more advanced scenarios, see our documentation.

🔗How does this compare with Azure Storage Persistence?

Our internal benchmarking has consistently shown superior performance of Cosmos DB persistence compared with Azure Storage persistence.

For a scenario of 1,000 sagas, we’ve seen a 30% performance increase using Cosmos DB over Table Storage. Combined with Microsoft’s initiative to replace its Table Storage service with Cosmos DB, the new persistence is a clear choice for customers that previously would have considered Azure Storage Persistence.

If you are already using Azure Storage Persistence, you can safely migrate by following our comprehensive migration process.

🔗Getting transactional

When something goes wrong, separately persisting your data and NServiceBus data can result in inconsistent data in your system. It is sometimes hard to detect when your data is in an inconsistent state, and it can be challenging to fix when you do detect it.

With the new persistence, we’re taking full advantage of the TransactionalBatch feature of the Cosmos DB SDK to allow you to atomically commit all of your Cosmos DB operations. This includes both operations executed in your handlers and those executed for NServiceBus features as a single unit of work for the processed message. This way you can enjoy stronger transactional guarantees than are possible with Azure Storage Persistence.

Learn how you can leverage this feature to gain additional peace of mind by signing up for our upcoming webinar, Building multi-tenant systems using NServiceBus and Cosmos DB.

🔗Before you go

User adoption is crucial during this preview phase and confirms whether Cosmos DB persistence is valuable to our customers, so give us a shout at to let us know if you’re using it.

The new package is available via NuGet and you can find documentation for the package, including samples, on our website.

Share on Twitter

About the authors

Bob Langley

Bob Langley is a developer at Particular Software with years of NServiceBus and Azure experience, which he loves to share, but he can't guarantee sub-millisecond latency unless he has had his morning tea.

Daniel Marbach

Daniel Marbach is a developer at Particular Software and longs for the days when travelling is allowed to be globally distributed again.

Sean Feldman

Sean Feldman is a solution architect at Particular Software, the makers of NServiceBus. He is also an advisor to Microsoft's Azure teams as well as an Azure MVP. With all of this work, we secretly wonder if he is elastically scaled in Azure.

Don't miss a thing. Sign up today and we'll send you an email when new posts come out.
Thank you for subscribing. We'll be in touch soon.
We collect and use this information in accordance with our privacy policy.