Uniphar.Cosmos.Extensions 3.0.0

cosmos-extensions

NuGet package repository for Cosmos Extensions

Purpose

This library is intended for provisioning Az Cosmos Database(s) and container(s).

Setup your project to use Cosmos Extension package

When using this NuGet package you need to setup a few things in your project

appsettings.json

Add this to structure to your appsettings.json with the appropriate values needed in your solution. Note that this contains examples from PIMS API. They are here to illustrate example values.

  "StoreOptions": {
    "DatabaseName": "pims-api",
    "DatabaseThroughput": <provisioned database throughput in RUs>,
    "Containers": [
      {
        "InstanceName": "responsePayloadContainer",
        "PartitionKey": "/partition",
        "DefaultTimeToLive": "128.0:0:0.0"
      },
      {
        "InstanceName": "auditContainer",
        "PartitionKey": "/partition"
      },
      {
        "InstanceName": "sequenceContainer",
        "PartitionKey": "/id",
        "IndexingMode": "None"
      },
      //...more containers to be defined with potential settings 
      {
        "InstanceName": "<name of container>",
        "PartitionKey": "<name of partition key>",
        "ContainerThroughput": <provisioned database throughput in RUs>,
        "DefaultTimeToLive" :"128.0:0:0.0"
        "IndexingMode": "<indexing mode value>"
        "CompositeIndexes": [
          {
            "Paths": [
              {
                "Path": "/path1",
                "Order": "Ascending"
              },
              {
                "Path": "/path2",
                "Order": "Ascending"
              }
            ]
          }
        ]
      }
    ]
  }

NOTE: Worth noting on the settings.

• DatabaseName: NAme of the database to be checked/created. Mandatory.
• DatabaseThroughput: integer, if undefined (null) it will default to 400; it will provision database with auto scaling as Manual throughput has been dismissed.
• Containers:InstanceName: string, name of container. Mandatory.
• Containers:PartitionKey: string, if undefined (null), it will default to partioning by /partition Be aware that partitionKey in appsettings will need to define a name preceeded with a forwards slash
• Containers:ContainerThroughput: integer, if undefined (null) it will default to 400
• DefaultTimeToLiveAsTimeSpan: Optional TimeSpan defining for how long data should be retained; if undefined (null) we implement it to default to -1 (items don’t expire by default). The example shows TTL defined as 128 days, zero days, zero mintues and zero seconds
• IndexingMode: Optional If undefined (null), it will default to IndexingMode.Consistent. If required, then use one of these enumerated values (with capitalisation!!!): None, Lazy, Consistent.
• CompositeIndexes: Optional The set of composite indexes to add to the parent container.

Composite Indexes

See here for more details about composite indexes.

Program.cs

Add the following to Program.cs

• Add this to bind the above configuration section to class StoreOptions. That will ensure we can DI it into the where ever we need to make the call.

builder.Services.Configure<StoreOptions>(
    builder.Configuration.GetSection(nameof(StoreOptions)));

• Register a singleton instance of a CosmosExtension

builder.Services.AddSingleton<CosmosExtension>();

• Register a singleton instance of CosmosClient (MS recommendation) by adding this line

builder.Services.AddSingleton(CosmosClientExtension.CreateCosmosClient(builder.Configuration["Cosmos:ConnectionString"]));

NOTE: Cosmos Client connestionstring is defined in KeyVault.

CosmosInitialiser.cs (or other file responsible of Cosmos Initialisation)

Whatever file responsible for initialising cosmos database and containers (called from StartupBackgroundService.cs) has a method ExecuteAsync(CancellationToken stoppingToken). That method can be simplified to this

public async Task ExecuteAsync(CancellationToken stoppingToken)
{
    _logger.LogInformation("Creating Cosmos Database And Containers");
    
    await _cosmosExtension.ExecuteAsync(stoppingToken);
}

Create extended class of StoreOptions

Some APIs may have additional logic that is specific to the solutions. You can then create a class extension that inherits from StoreOptions. This is particular valid for PIMS API. You would create something like this.

    public class ExtendedStoreOptions : StoreOptions
    {
        /// <summary>
        /// Disable the account processing check
        /// </summary>
        /// <remarks>
        /// If set to true all account processing checks will return true
        /// Used to disable routing of requests to legacy pims system
        /// </remarks>
        public bool DisableAccountCheck { get; set; } = false;
    }

Your appsettings.json would look like this then (based on PIMS API as an example)

  "ExtendedStoreOptions": {
    "DatabaseName": "<name of database>",
    "DatabaseThroughput": <provisioned database throughput in RUs>,
    "DisableAccountCheck": true, // < --- this is the extra field from the above example
    "Containers": [
      {
        "InstanceName": "<name of container>",
        "PartitionKey": "<name of partition key>",
        "ContainerThroughput": <provisioned database throughput in RUs>,
        "DefaultTimeToLiveInSeconds" : "128.0:0:0.0"
      },
      //...more containers to be defined
    ]
  }

Your program.cs would then need to bind the config section like this

builder.Services.Configure<ExtendedStoreOptions>(
    builder.Configuration.GetSection(nameof(ExtendedStoreOptions)));

Likewise you;ll need to update Store.cs to reflect using ExtendedStoreOptions instead.

Customize Json Serializer

The cosmos extension library supports the ability to customize the json serializer that the cosmos SDK uses for serializing and deserializing documents to and from a container.

There are two serializer customization options:

• SystemTextCosmosSerializer
  • Uses JsonObjectSerializer for serialization
• NewtonsoftJsonCosmosSerializer
  • Uses JsonSerializer for serialization

Using SystemTextCosmosSerializer

var cosmosClient = new CosmosClient("<cosmosDBConnectionString>",
    new CosmosClientOptions
    {
        Serializer = new SystemTextCosmosSerializer(new JsonSerializerOptions
        {
            // Update your JSON Serializer options here.
        })
    });

Using NewtonsoftJsonCosmosSerializer

var cosmosClient = new CosmosClient("<cosmosDBConnectionString>",
    new CosmosClientOptions
    {
        Serializer = new NewtonsoftJsonCosmosSerializer(new JsonSerializerSettings
        {
            // Update your JSON Serializer options here.
        })
    });