Aspire.Microsoft.Azure.Cosmos

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 AddAzureCosmosDB extension method to register a CosmosClient for use via the dependency injection container. The method takes a connection name parameter.

builder.AddAzureCosmosDB("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.AddAzureCosmosDB():

builder.AddAzureCosmosDB("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 AzureCosmosDBSettings.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 AzureCosmosDBSettings 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": {
          "Tracing": true,
        }
      }
    }
  }
}

Use inline delegates

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

    builder.AddAzureCosmosDB("cosmosConnectionName", settings => settings.Tracing = false);

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

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

AppHost extensions

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

dotnet add package Aspire.Hosting.Azure

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

var cosmosdb = builder.AddAzureCosmosDB("cdb").AddDatabase("cosmosdb");

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

The AddAzureCosmosDB method will 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.AddAzureCosmosDB("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").UseEmulator();

When the AppHost starts up a local container running the Azure CosmosDB will also be started. Inside the project that uses CosmosDB you can specify that you want to ignore the server certificate, so you don't need to manually download and install it:

// Service code
builder.AddCosmosDB("cosmos", (settings) =>
{
    settings.IgnoreEmulatorCertificate = true;
});

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