Set up Azure Cosmos DB in the AppHost (EF Core)

This article is the AppHost reference for the Azure Cosmos DB hosting integration as used with the EF Core client integration. It enumerates the AppHost APIs that you use to model Cosmos DB account, database, and container resources in your AppHost project.

If you’re new to the EF Core Azure Cosmos DB integration, start with the Get started with the EF Core Azure Cosmos DB integrations guide. For how C# consuming apps register a DbContext from the resources this page exposes, see Connect to Azure Cosmos DB with EF Core.

Note

The AppHost hosting integration is shared between the direct CosmosClient integration and this EF Core integration — both use the same Aspire.Hosting.Azure.CosmosDB package and the same AddAzureCosmosDB API. The difference is in the client-side package: EF Core apps install Aspire.Microsoft.EntityFrameworkCore.Cosmos and call AddCosmosDbContext, while direct SDK apps install Aspire.Microsoft.Azure.Cosmos and call AddAzureCosmosClient. For the full AppHost reference including TypeScript examples, see Azure Cosmos DB Hosting integration.

Installation

To start building an Aspire app that uses Azure Cosmos DB, install the 📦 Aspire.Hosting.Azure.CosmosDB NuGet package in your AppHost project:

C#

Terminal

aspire add cosmosdb

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

C# — AppHost.cs

#:package Aspire.Hosting.Azure.CosmosDB@*

XML — AppHost.csproj

<PackageReference Include="Aspire.Hosting.Azure.CosmosDB" Version="*" />

TypeScript

Terminal

aspire add cosmosdb

Learn more about aspire add in the command reference.

This updates your aspire.config.json with the Azure Cosmos DB hosting integration package:

aspire.config.json

{
  "packages": {
    "Aspire.Hosting.Azure.CosmosDB": "13.3.0"
  }
}

Add Azure Cosmos DB resource

In your AppHost project, call AddAzureCosmosDB to add and return an Azure Cosmos DB resource builder:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db");

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const cosmos = await builder.addAzureCosmosDb("cosmos-db");

// After adding all resources, run the app...

Caution

When you call AddAzureCosmosDB, it implicitly calls AddAzureProvisioning — which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see Local provisioning: Configuration.

Add Azure Cosmos DB database and container resources

Aspire models parent-child relationships between Azure Cosmos DB resources. For example, a Cosmos DB account can have multiple databases, and each database can have multiple containers.

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db");
var db = cosmos.AddCosmosDatabase("db");
var container = db.AddContainer("entries", "/id");

builder.AddProject<Projects.ExampleProject>("apiservice")
    .WaitFor(container)
    .WithReference(container);

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const cosmos = await builder.addAzureCosmosDb("cosmos-db");
const db = await cosmos.addCosmosDatabase("db");
const container = await db.addContainer("entries", "/id");

await builder.addProject("apiservice", { projectPath: "../ExampleProject/ExampleProject.csproj" })
    .waitFor(container)
    .withReference(container);

// After adding all resources, run the app...

The following diagram illustrates the parent-child relationship between the Azure Cosmos DB resources:

For more information, see Databases, containers, and items in Azure Cosmos DB.

Add Azure Cosmos DB emulator resource

To run locally without an Azure subscription, chain a call to RunAsEmulator on the Cosmos DB resource builder:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db")
    .RunAsEmulator();

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const cosmos = await builder.addAzureCosmosDb("cosmos-db");
await cosmos.runAsEmulator();

// After adding all resources, run the app...

When you call RunAsEmulator, it configures your Cosmos DB resources to run locally using the Azure Cosmos DB Emulator container (mcr.microsoft.com/cosmosdb/emulator).

For the full emulator configuration reference — gateway port, data volumes, partition count, and the Linux-based preview emulator — see Azure Cosmos DB Hosting integration.

Connect to an existing Azure Cosmos DB account

You might have an existing Azure Cosmos DB account that you want to connect to. Chain a call to AsExisting to annotate that your resource is an existing resource:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var existingCosmosName = builder.AddParameter("existingCosmosName");
var existingCosmosResourceGroup = builder.AddParameter("existingCosmosResourceGroup");

var cosmosdb = builder.AddAzureCosmosDB("cosmos-db")
    .AsExisting(existingCosmosName, existingCosmosResourceGroup);

builder.AddProject<Projects.ExampleProject>()
    .WithReference(cosmosdb);

// After adding all resources, run the app...

For more information on treating Azure Cosmos DB resources as existing resources, see Use existing Azure resources.

Provisioning-generated Bicep

When you publish your app, Aspire generates Bicep for the Cosmos DB account alongside the manifest file. For the full generated Bicep and infrastructure customization reference (including ConfigureInfrastructure), see Azure Cosmos DB Hosting integration.

Hosting integration health checks

The Azure Cosmos DB hosting integration automatically adds a health check for the Cosmos DB resource. The health check verifies that the Cosmos DB is running and that a connection can be established to it.

The hosting integration relies on the 📦 AspNetCore.HealthChecks.CosmosDb NuGet package.