This repository contains an implementation of IDistributedCache using Azure Cosmos DB that can be leveraged in ASP.NET Core as a Session State Provider.
There is also a sample on how to instantiate the provider as part of ASP.NET Core's pipeline.
This project is available on Nuget to install through any of the available package management tools.
The implementation provides two distinct options:
This option will make the provider re-use an existing CosmosClient instance, which won't be disposed when the provider is disposed.
services.AddCosmosCache((CosmosCacheOptions cacheOptions) =>
{
cacheOptions.ContainerName = Configuration["CosmosCacheContainer"];
cacheOptions.DatabaseName = Configuration["CosmosCacheDatabase"];
cacheOptions.CosmosClient = existingCosmosClient;
cacheOptions.CreateIfNotExists = true;
});
This option will make the provider maintain an internal instance of CosmosClient that will get disposed when the provider is disposed. The CosmosClient will be created using the provided CosmosBuilder.
services.AddCosmosCache((CosmosCacheOptions cacheOptions) =>
{
cacheOptions.ContainerName = Configuration["CosmosCacheContainer"];
cacheOptions.DatabaseName = Configuration["CosmosCacheDatabase"];
cacheOptions.ClientBuilder = new CosmosClientBuilder(Configuration["CosmosConnectionString"]);
cacheOptions.CreateIfNotExists = true;
});
The provider stores the state in a container within a database, both parameters are required within the CosmosCacheOptions initialization. An optional parameter, CreateIfNotExists will make sure to create the container if it does not exist with an optimized configuration for key-value storage. ContainerThroughput can be used to specify a particular Throughput on the container.
When providing an existing container and not using
CreateIfNotExists, make sure the container has time to live enabled.
Consistency in a distributed cache is important, especially when applications are deployed across multiple instances and user requests can be distributed across all of them. Azure Cosmos DB has multiple options when it comes to configuring consistency. When using it as a distributed cache provider, the following consistency levels are recommended:
- Session: Recommended only if the ASP.NET application will be using Application Request Routing Affinity. This is enabled by default when hosting your ASP.NET application in Azure App Service.
- Bounded staleness
- Strong
Using other consistency levels is not recommended as read operations could be getting a stale version of the session.
The provider executes operations on Cosmos DB based on the calls to the IDistributedCache APIs. There might be scenarios when the user wants to troubleshoot or diagnose these interactions (for example, on high latency scenarios).
The CosmosCacheOptions expose a delegate that can be configured to capture the Diagnostics from the SDK calls that are happening internally and decide to log them.
void captureDiagnostics(CosmosDiagnostics diagnostics)
{
if (diagnostics.GetClientElapsedTime() > SomePredefinedThresholdTime)
{
Console.WriteLine(diagnostics.ToString());
}
}
services.AddCosmosCache((CosmosCacheOptions cacheOptions) =>
{
cacheOptions.DiagnosticsHandler = captureDiagnostics;
/* other options */
});This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.