Azure Table Persistence

Certain features of NServiceBus require persistence to permanently store data. Among them are subscription storage, sagas, and outbox. Various storage options are available including Azure Table and Azure Cosmos DB Table API.

Azure Table Persistence stores NServiceBus data in Azure Table storage or Azure Cosmos DB using the Table API.

Persistence at a glance

For a description of each feature, see the persistence at a glance legend.

Enable Azure Table Persistence

First add a reference to the assembly that contains the Azure storage persisters, which is done by adding a NuGet package reference to NServiceBus.Persistence.AzureStorage.

var persistence = endpointConfiguration.UsePersistence<AzureStoragePersistence>();
persistence.ConnectionString("DefaultEndpointsProtocol=https;AccountName=[ACCOUNT];AccountKey=[KEY];");

Saga correlation

Azure Storage Persistence only supports a single correlation property.

To ensure that only one saga can be created for a given correlation property value, secondary indexes are used. Entities for the secondary index are stored in the same table as a saga. When a saga is completed the secondary index entity is removed as well. It's possible, but highly unlikely, that the saga's completion can leave an orphaned secondary index record. This does not impact the behavior of the persistence as it can detect orphaned records, but may leave a dangling entity in a table with a following WARN entry in logs: Removal of the secondary index entry for the following saga failed: {sagaId}.

If migrating from Version 6.2.3 or below without applying saga deduplication a DuplicatedSagaFoundException can be thrown when when creating secondary index entities. The exception message will include all the information to track down the error for example:

Sagas of type MySaga with the following identifiers 'GUID1', 'GUID2' are considered duplicates because of the violation of the Unique property CorrelationId.

Consolidate the [upgrade guide]((/persistence/upgrades/asp-saga-deduplication.md) for more instructions.

Saga concurrency

When simultaneously handling messages, conflicts may occur. See below for examples of the exceptions which are thrown. Saga concurrency explains how these conflicts are handled, and contains guidance for high-load scenarios.

Starting a saga

Example exception:

NServiceBus.Persistence.AzureStorage.RetryNeededException: This operation requires a retry as it wasn't possible to successfully process it now.

Updating or deleting saga data

Azure Table Persistence uses optimistic concurrency control when updating or deleting saga data.

Example exception:

Microsoft.WindowsAzure.Storage.StorageException: Element 0 in the batch returned an unexpected response code.

Request Information
RequestID:010c234e-3002-0145-06eb-72b85a000000
RequestDate:Tue, 24 Sep 2019 15:16:45 GMT
StatusMessage:The update condition specified in the request was not satisfied.
ErrorCode:
ErrorMessage:The update condition specified in the request was not satisfied.
RequestId:010c234e-3002-0145-06eb-72b85a000000
Time:2019-09-24T15:16:46.0746310Z

Supported saga properties' types

Azure Storage Persistence supports the same set of types as Azure Table Storage and additional types that can be serialized into JSON using Json.NET. When a saga containing a property of an unsupported type is persisted, an exception containing the following information is thrown: The property type 'the_property_name' is not supported in Windows Azure Table Storage and it cannot be serialized with JSON.NET.

Saga Correlation property restrictions

Saga correlation property values are subject to the underlying Azure Storage table PartitionKey and RowKey restrictions:

• Up to 1KB in size
• Cannot contain invalid characters