Uses the Azure Cosmos DB NoSQL database service for storage.
NServiceBus.Persistence.CosmosDB
.Persistence at a glance
For a description of each feature, see the persistence at a glance legend.
Feature | |
---|---|
Supported storage types | Sagas, Outbox |
Transactions | Using TransactionalBatch, with caveats |
Concurrency control | Optimistic concurrency, optional pessimistic concurrency |
Scripted deployment | Not supported |
Installers | Container is created by installers. |
Usage
Add a NuGet package reference to NServiceBus.
. Configure the endpoint to use the persistence through the following configuration API:
endpointConfiguration.UsePersistence<CosmosPersistence>()
.CosmosClient(new CosmosClient("ConnectionString"));
Customizing the database used
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:
endpointConfiguration.UsePersistence<CosmosPersistence>()
.CosmosClient(new CosmosClient("ConnectionString"))
.DatabaseName("DatabaseName");
Customizing the container used
Set the default container using the following configuration API:
endpointConfiguration.UsePersistence<CosmosPersistence>()
.CosmosClient(new CosmosClient("ConnectionString"))
.DefaultContainer(
containerName: "ContainerName",
partitionKeyPath: "/partition/key/path");
When installers are enabled the default container will be created if it doesn't exist. To opt-out from creating the default container either disable the installers or use
endpointConfiguration.UsePersistence<CosmosPersistence>()
.CosmosClient(new CosmosClient("ConnectionString"))
.DefaultContainer(
containerName: "ContainerName",
partitionKeyPath: "/partition/key/path")
.DisableContainerCreation();
Customizing the CosmosClient provider
In cases when the CosmosClient is configured and used via dependency injection a custom provider can be implemented
class CustomCosmosClientProvider
: IProvideCosmosClient
{
// get fully configured via DI
public CustomCosmosClientProvider(CosmosClient cosmosClient)
{
Client = cosmosClient;
}
public CosmosClient Client { get; }
}
and registered on the container
endpointConfiguration.RegisterComponents(c => c.ConfigureComponent<CustomCosmosClientProvider>(DependencyLifecycle.SingleInstance));
Provisioned throughput rate-limiting
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.
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:
endpointConfiguration.UsePersistence<CosmosPersistence>()
.CosmosClient(new CosmosClient("ConnectionString", new CosmosClientOptions
{
MaxRetryWaitTimeOnRateLimitedRequests = TimeSpan.FromSeconds(30),
MaxRetryAttemptsOnRateLimitedRequests = 9
}));
They may also be set when using a CosmosClientBuilder
via the WithThrottlingRetryOptions
method:
var cosmosClientBuilder = new CosmosClientBuilder("ConnectionString")
.WithThrottlingRetryOptions(
maxRetryWaitTimeOnThrottledRequests: TimeSpan.FromSeconds(30),
maxRetryAttemptsOnThrottledRequests: 9
);
endpointConfiguration.UsePersistence<CosmosPersistence>()
.CosmosClient(cosmosClientBuilder.Build());
Transactions
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.
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:
var outbox = endpointConfiguration.EnableOutbox();
outbox.TimeToKeepOutboxDeduplicationData(TimeSpan.FromDays(7));
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.