| title | summary | component | reviewed | related | redirects | ||||
|---|---|---|---|---|---|---|---|---|---|
Azure Cosmos DB Persistence |
How to use NServiceBus with Azure Cosmos DB |
CosmosDB |
2023-11-30 |
|
|
Uses the Azure Cosmos DB NoSQL database service for storage.
Warning
It is important to read and understand partitioning in Azure Cosmos DB before using NServiceBus.Persistence.CosmosDB.
For a description of each feature, see the persistence at a glance legend.
partial: glance
Note
The Outbox feature requires partition planning.
Add a NuGet package reference to NServiceBus.Persistence.CosmosDB. Configure the endpoint to use the persistence through the following configuration API:
snippet: CosmosDBUsage
Enables usage of Microsoft Entra ID authentication such as managed identities for Azure resources instead of the shared secret in the connection string.
Use the corresponding CosmosClient constructor overload when creating the client passed to the persistence.
By default, the persister will store records in a database named NServiceBus and use a container per endpoint using the endpoint name as to name the container.
Customize the database name using the following configuration API:
snippet: CosmosDBDatabaseName
include: defaultcontainer
Note
The transactions documentation details additional options on how to configure NServiceBus to specify the container using the incoming message headers or contents.
In cases when the CosmosClient is configured and used via dependency injection a custom provider can be implemented
snippet: CosmosDBCustomClientProvider
and registered on the container
snippet: CosmosDBCustomClientProviderRegistration
When using provisioned throughput it is possible for the CosmosDB service to rate-limit usage, resulting in "request rate too large" exceptions indicated by the 429 status code.
Warning
When using the Cosmos DB persistence with the outbox enabled, "request rate too large" errors may result in handler re-execution and/or duplicate message dispatches depending on which operation is throttled.
Note
Microsoft provides guidance on how to diagnose and troubleshoot request rate too large exceptions.
The Cosmos DB SDK provides a mechanism to automatically retry collection operations when rate-limiting occurs. Besides changing the provisioned RUs or switching to the serverless tier, those settings can be adjusted to help prevent messages from failing during spikes in message volume.
These settings may be set when initializing the CosmosClient via the CosmosClientOptions MaxRetryAttemptsOnRateLimitedRequests and MaxRetryWaitTimeOnRateLimitedRequests properties:
snippet: CosmosDBConfigureThrottlingWithClientOptions
They may also be set when using a CosmosClientBuilder via the WithThrottlingRetryOptions method:
snippet: CosmosDBConfigureThrottlingWithBuilder
The Cosmos DB persister supports using the Cosmos DB transactional batch API. However, Cosmos DB only allows operations to be batched if all operations are performed within the same logical partition key. This is due to the distributed nature of the Cosmos DB service, which does not support distributed transactions.
The transactions documentation provides additional details on how to configure NServiceBus to resolve the incoming message to a specific partition key to take advantage of this Cosmos DB feature.
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: CosmosDBOutboxCleanup
Outbox cleanup depends on the Cosmos DB time-to-live feature. Failure to remove the expired outbox records is caused by a misconfigured collection that has time-to-live disabled. Refer to the Cosmos DB documentation to configure the collection correctly.