Azure Cosmos DB is a fully managed NoSQL database service built for fast and predictable performance, high availability, elastic scaling, global distribution, and ease of development. Redakt offers Cosmos DB integration through a NuGet package. The Redakt Cosmos DB implementation uses the default SQL API.

Installation

The Cosmos DB database module is part of the Azure provider package. Install the package with the NuGet package manager or the Package Manager Console.

PM> Install-Package Redakt.Providers.Azure

Service registration

Register Cosmos DB services in the ConfigureServices() method of your project's Startup.cs file by adding an AddCosmosDbDataStore() call to the Redakt builder instance. The order in which services are added to the Redakt builder is not important.

public void ConfigureServices(IServiceCollection services)
{
    // ... framework and other services here

    var builder = services.AddRedakt();
    builder.AddCosmosDbDataStore();  // Optionally pass Action<CosmosDbOptions> parameter.
    // ... other Redakt services
}

Configuration settings

The Cosmos DB data store is configured through the appsettings.json file. All configuration settings are required. See the example below.

{
    "Redakt": {
        "DataStore": {
            "AzureCosmosDB": {
                "EndpointUri": "<your database endpoint uri>",
                "PrimaryKey": "<your database primary key>",
                "DatabaseName": "<your database name>"
            }
        }
    }
}

Additionally, an Action<CosmosDbOptions> configuration delegate may be passed to the AddCosmosDbDataStore() call. Configuration set through this delegate takes priority and overrides values in the appsettings.json file.

Endpoint URI & Primary Key

Required. These settings are found in the Azure Portal and are used to connect to your Cosmos DB instance.


Database Name

Required. The database name in your Cosmos DB instance. Cosmos DB databases are not created automatically by Redakt. You must create a database in the Azure Portal before starting the installation of your Redakt project (see next section). Data collections (containers) will be created automatically by Redakt.

Creating a database

Redakt does not automatically create a new Cosmos DB database. Before starting your Redakt application for the first time, a Cosmos DB account and database must already have been created. You can do so in the Azure Portal, or through custom scripting.

The Redakt Cosmos DB implementation uses the default SQL API. Therefore, make sure you have selected the SQL API when creating a new Cosmos DB account. Redakt works with any of the current capacity modes, both provisioned throughput (manual or autoscale) and serverless. The amount of RU/s (request units) you need to provision will depend on the actual traffic load of your application and your cache expiration settings. In general, Redakt tries to be as efficient as possible when it comes to database requests and consumption, allowing for relatively low RU/s to be provisioned. For applications with irregular or lower amounts of traffic, the serverless capacity mode is recommended as a very cost-effective option.

Other Cosmos DB account settings should be configured according to best practices. It is highly recommended to select the same geographic Azure location for both your Cosmos DB account and your app services in order to maximize performance.

After creating your Cosmos DB account, you can create a new database in the Data Explorer blade. If you have selected the provisioned throughput capacity mode, we highly recommend provisioning throughput on the database level, as opposed to dedicated container throughput. The Redakt database will contain collections of varying size and use, and throughput can be more efficiently used when set on the database level.

When you are done with creating your Cosmos DB account and database, you can set the required configuration settings in the appsettings.json file of your application, as described above. Collections (containers) will be created automatically by Redakt within the specified database.

In this article