Aspire.Microsoft.Azure.Cosmos 8.0.2

Aspire.Microsoft.Azure.Cosmos library

Registers CosmosClient as a singleton in the DI container for connecting to Azure Cosmos DB. Enables corresponding logging and telemetry.

Getting started

Prerequisites

• Azure subscription - create one for free
• Azure Cosmos DB account - create a Cosmos DB account

Install the package

Install the .NET Aspire Microsoft Azure Cosmos DB library with NuGet:

dotnet add package Aspire.Microsoft.Azure.Cosmos

Usage example

In the Program.cs file of your project, call the AddAzureCosmosClient extension method to register a CosmosClient for use via the dependency injection container. The method takes a connection name parameter.

builder.AddAzureCosmosClient("cosmosConnectionName");

You can then retrieve the CosmosClient instance using dependency injection. For example, to retrieve the client from a Web API controller:

private readonly CosmosClient _client;

public ProductsController(CosmosClient client)
{
    _client = client;
}

See the Azure Cosmos DB documentation for examples on using the CosmosClient.

Configuration

The .NET Aspire Azure Cosmos DB library provides multiple options to configure the Azure Cosmos DB connection based on the requirements and conventions of your project. Note that either an AccountEndpoint or a ConnectionString is a required to be supplied.

Use a connection string

When using a connection string from the ConnectionStrings configuration section, you can provide the name of the connection string when calling builder.AddAzureCosmosClient():

builder.AddAzureCosmosClient("cosmosConnectionName");

And then the connection string will be retrieved from the ConnectionStrings configuration section. Two connection formats are supported:

Account Endpoint

The recommended approach is to use an AccountEndpoint, which works with the MicrosoftAzureCosmosSettings.Credential property to establish a connection. If no credential is configured, the DefaultAzureCredential is used.

{
  "ConnectionStrings": {
    "cosmosConnectionName": "https://{account_name}.documents.azure.com:443/"
  }
}

Connection string

Alternatively, an Azure Cosmos DB connection string can be used.

{
  "ConnectionStrings": {
    "cosmosConnectionName": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};"
  }
}

Use configuration providers

The .NET Aspire Microsoft Azure Cosmos DB library supports Microsoft.Extensions.Configuration. It loads the MicrosoftAzureCosmosSettings and QueueClientOptions from configuration by using the Aspire:Microsoft:Azure:Cosmos key. Example appsettings.json that configures some of the options:

{
  "Aspire": {
    "Microsoft": {
      "Azure": {
        "Cosmos": {
          "DisableTracing": false,
        }
      }
    }
  }
}

Use inline delegates

You can also pass the Action<MicrosoftAzureCosmosSettings> configureSettings delegate to set up some or all the options inline, for example to disable tracing from code:

builder.AddAzureCosmosClient("cosmosConnectionName", settings => settings.DisableTracing = true);

You can also setup the CosmosClientOptions using the optional Action<CosmosClientOptions> configureClientOptions parameter of the AddAzureCosmosClient method. For example, to set the ApplicationName "User-Agent" header suffix for all requests issues by this client:

builder.AddAzureCosmosClient("cosmosConnectionName", configureClientOptions: clientOptions => clientOptions.ApplicationName = "myapp");

AppHost extensions

In your AppHost project, install the Aspire Azure CosmosDB Hosting library with NuGet:

dotnet add package Aspire.Hosting.Azure.CosmosDB

Then, in the Program.cs file of AppHost, add a Cosmos DB connection and consume the connection using the following methods:

var cosmosdb = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureCosmosDB("cdb").AddDatabase("cosmosdb")
    : builder.AddConnectionString("cosmosdb");

var myService = builder.AddProject<Projects.MyService>()
                       .WithReference(cosmosdb);

The AddAzureCosmosDB method will add an Azure Cosmos DB resource to the builder. Or AddConnectionString can be used to read connection information from the AppHost's configuration (for example, from "user secrets") under the ConnectionStrings:cosmosdb config key. The WithReference method passes that connection information into a connection string named cosmosdb in the MyService project. In the Program.cs file of MyService, the connection can be consumed using:

builder.AddAzureCosmosClient("cosmosdb");

Emulator usage

Aspire supports the usage of the Azure Cosmos DB emulator to use the emulator, add the following to your AppHost project:

// AppHost
var cosmosdb = builder.AddAzureCosmosDB("cosmos").RunAsEmulator();

When the AppHost starts up a local container running the Azure CosmosDB will also be started:

// Service code
builder.AddAzureCosmosClient("cosmos");

Additional documentation

• https://learn.microsoft.com/azure/cosmos-db/nosql/sdk-dotnet-v3
• https://github.com/dotnet/aspire/tree/main/src/Components/README.md

Feedback & contributing

https://github.com/dotnet/aspire