Get started with the Azure Cosmos DB integrations

Azure Cosmos DB is a fully managed NoSQL database service for modern app development. The Aspire Azure Cosmos DB integration enables you to connect to existing Cosmos DB instances or create new instances with the Azure Cosmos DB emulator.

In this introduction, you'll see how to install and use the Aspire Azure Cosmos DB integrations in a simple configuration. If you already have this knowledge, see Azure Cosmos DB Hosting integration and Azure Cosmos DB Client integration for full reference details.

Set up hosting integration

To begin, install the Aspire Azure Cosmos DB Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Azure Cosmos DB resources from your Aspire hosting projects:

dotnet add package Aspire.Hosting.Azure.CosmosDB

Next, in the AppHost project, create an Azure Cosmos DB resource and pass it to the consuming client projects:

var builder = DistributedApplication.CreateBuilder(args);
  
var cosmos = builder.AddAzureCosmosDB("cosmos-db");
var db = cosmos.AddCosmosDatabase("db");
  
builder.AddProject<Projects.ExampleProject>("api")
    .WithReference(db);
  
// After adding all resources, run the app...
  
builder.Build().Run();

The preceding code adds an Azure Cosmos DB resource named cosmos-db with a database named db. The database is then referenced by the api project.

Set up client integration

To get started with the Aspire Microsoft Entity Framework Core Cosmos DB client integration, install the client integration package in the client-consuming project:

dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos

In the Program.cs file of your client-consuming project, call the AddCosmosDbContext extension method to register a DbContext for use via the dependency injection container:

builder.AddCosmosDbContext<MyDbContext>("cosmos-db");

Use injected Azure Cosmos DB properties

In the AppHost, when you used the WithReference method to pass an Azure Cosmos DB resource to a consuming client project, Aspire injects several configuration properties that you can use in the consuming project.

Aspire exposes each property as an environment variable named [RESOURCE]_[PROPERTY]. For instance, the Uri property of a resource called db becomes DB_URI.

Use the GetValue() method to obtain these environment variables in consuming projects:

string cosmosUri = builder.Configuration.GetValue<string>("DB_URI");
string databaseName = builder.Configuration.GetValue<string>("DB_DATABASENAME");

Use Azure Cosmos DB resources in client code

You can then retrieve the DbContext instance using dependency injection. For example, to retrieve the client from a service:

public class ExampleService(MyDbContext context)
{
    // Use context...
}

Continue learning

For more information on how the Azure Cosmos DB integrations work, see: