Run Azure Cosmos DB on local PC

In this exercise, I focused on only one Azure resource: Azure Cosmos DB. My goal was simple: run Cosmos locally, connect a console client project to it through .NET Aspire, create database/container automatically, and write a test item end-to-end.

How it looks like

This is the Data Explorer emulator with a item

This is the ASPIRE project

How I wired Cosmos in Aspire AppHost

In AzureEmulators/AppHost.cs, I added Cosmos DB as a preview emulator and enabled Data Explorer. Then I defined:

Database: CosmosDatabase1
Container: CosmosEntriesContainer1 with partition key /id
Client project reference: cosmosClient1 with WithReference(container) and WaitFor(container)

     
#pragma warning disable ASPIRECOSMOSDB001
    var cosmos = builder.AddAzureCosmosDB("cosmos-db1")
        .RunAsPreviewEmulator(emulator =>
        {            emulator.WithDataExplorer();
        });
    var dbCosmos = cosmos.AddCosmosDatabase("CosmosDatabase1");
    var container = dbCosmos.AddContainer("CosmosEntriesContainer1", "/id");

    var csm = builder
        .AddProject<Projects.CosmosClient>("cosmosClient1")
        .WithReference(container)
        .WaitFor(container)
        ;

What my CosmosClient project does

In CosmosClient/Program.cs, I implemented a small startup flow to validate connectivity and prove writes work.

I scan environment variables and pick the Cosmos connection string.
I fail fast if the connection string is missing.
I create a Cosmos client configured for local emulator-friendly access:
- ConnectionMode = Gateway
- LimitToEndpoint = true
I call CreateDatabaseIfNotExistsAsync("CosmosDatabase1").
I call CreateContainerIfNotExistsAsync("CosmosEntriesContainer1", "/id").
I insert one item with a generated GUID id and name "Andrei Ignat".

Code from my console client project

     
using Azure.Core;
using Microsoft.Azure.Cosmos;
using Microsoft.Azure.Cosmos.Fluent;
using System.Collections;
using System.Net;

Console.WriteLine("Hello, Cosmos Client!");
string connectionStringCosmos = "";
foreach (var item in Environment.GetEnvironmentVariables().Cast<DictionaryEntry>())
{
    if(item.Key?.ToString()?.Contains("Cosmos") == true)
    {
        Console.WriteLine($"{item.Key}: {item.Value}");
        connectionStringCosmos  = item.Value?.ToString() ?? string.Empty;
    }
}
if(string.IsNullOrWhiteSpace(connectionStringCosmos))
{
    Console.WriteLine("Cosmos connection string is not set in environment variables.");
    return;
}
CosmosClientBuilder builder = new CosmosClientBuilder(connectionStringCosmos);
CosmosClient client = new CosmosClient(connectionStringCosmos, new CosmosClientOptions
{
    ConnectionMode = ConnectionMode.Gateway,
    LimitToEndpoint = true
});

Console.WriteLine("CosmosClient created successfully. Attempting to connect to database...");
DatabaseResponse response = await client.CreateDatabaseIfNotExistsAsync(
    id: "CosmosDatabase1"
);  
Database database = response.Database;
Console.WriteLine("Database created successfully. Attempting to connect to container...");
var containerResponse = await database.CreateContainerIfNotExistsAsync(
    id: "CosmosEntriesContainer1",
    partitionKeyPath: "/id"
);
var container = containerResponse.Container;

Console.WriteLine("start write item to CosmosDB");
await container.CreateItemAsync(new { id = Guid.NewGuid().ToString(), name = "Andrei Ignat" });
Console.WriteLine("verify with Explorer that I wrote the item to CosmosDB");

Output logs from my client project

Waiting for resource 'cosmos-db1' to enter the 'Running' state.
Waiting for resource 'CosmosDatabase1' to enter the 'Running' state.
Waiting for resource 'CosmosEntriesContainer1' to enter the 'Running' state.
Waiting for resource ready to execute for 'CosmosEntriesContainer1'.
Waiting for resource ready to execute for 'CosmosDatabase1'.
Waiting for resource 'cosmos-db1' to become healthy.
Waiting for resource ready to execute for 'cosmos-db1'.
Finished waiting for resource 'CosmosEntriesContainer1'.
Finished waiting for resource 'CosmosDatabase1'.
Finished waiting for resource 'cosmos-db1'.
[sys] Starting process...: Cmd = C:\Program Files\dotnet\dotnet.exe, Args = ["watch", "--non-interactive", "--no-hot-reload", "--project", "D:\\eu\\GitHub\\aspireExtensions\\src\\samples\\13.4\\AzureEmulators\\CosmosClient\\CosmosClient.csproj", "--configuration", "Debug", "--no-launch-profile"]
dotnet watch ⌚ Waiting for changes
Hello, Cosmos Client!
ConnectionStrings__CosmosEntriesContainer1: AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;AccountEndpoint=https://localhost:60173;Database=CosmosDatabase1;Container=CosmosEntriesContainer1
CosmosClient created successfully. Attempting to connect to database...
Database created successfully. Attempting to connect to container...
start write item to CosmosDB
verify with Explorer that I wrote the item to CosmosDB
dotnet watch ⌚ Exited
dotnet watch ⏳ Waiting for a file to change before restarting ...

What is achieved

I can run Cosmos DB on my local PC without provisioning a cloud resource.
I get automatic resource initialization (database + container) from code.
I proved write operations by inserting a document from the client project.
I can verify data immediately using the emulator Data Explorer UI.
I have a repeatable local dev loop for Cosmos: run, connect, create-if-missing, write, verify.