Using a different image for Aspire CosmosDB emulator

Readme.md

How to use a different emulator container image with Aspire & Cosmos DB.

The RunAsEmulator function mostly serves as a wrapper around adding the container image and port with a specific "emulator" name so it can be replaced by that call and whatever emulator is being used.

Steps:

1. Instead of RunAsEmulator(), instead specify the local client and add the ConatinerImageAnnotation (ref)
2. Update Registry, Image, and Tag to the Emulator image you'd like to use
3. Ensure you've done a docker pull on that image
4. Allow dev-certs in dotnet with the command:

   dotnet dev-certs https --trust

Program.cs

var builder = DistributedApplication.CreateBuilder(args);

var database = builder.AddAzureCosmosDB("cosmos").AddDatabase("iotdb")
                      //.RunAsEmulator()
                      .WithEndpoint(name: "emulator", targetPort: 8080)
                      .WithAnnotation(new ContainerImageAnnotation
                      {
                          Registry = "<registry name>",
                          Image = "<image name>",
                          Tag = "<tag>"
                      });

var apiService = builder.AddProject<Projects.AspireWithCosmos_ApiService>("apiservice")
    .WithReference(database);

builder.AddProject<Projects.AspireWithCosmos_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithReference(apiService);

builder.Build().Run();

Here's our implementation for the vnext-preview tag that includes PROTOCOL = https so the generated connection string remains correct and avoids SSL errors when clients try to use https/ssl on an http endpoint.

var cosmosdb = builder.AddAzureCosmosDB("CosmosDb")
    .AddDatabase("database")
    .RunAsEmulator(opt => _ = opt
        .WithAnnotation(new ContainerImageAnnotation
        {
            Registry = "mcr.microsoft.com",
            Image = "cosmosdb/linux/azure-cosmos-emulator",
            Tag = "vnext-preview" // 👈 use this for ARM64 support, that is, Apple Silicon and Windows ARM
        })
        // 👇 REQUIRED: VNext emulator defaults to http, so set it to https otherwise the scheme in the connection string will be wrong;
        // clients will fail with SSL errors, and healthchecks will always fail so if you .WaitFor(..) then the dependent resource will never start
        .WithEnvironment("PROTOCOL", "https")
        .WithHttpsEndpoint(targetPort: 1234, port: 1234) // 👈 optional, gives you a convenient link in the Aspire dashboard to get to the Data Explorer
        // .WithDataVolume() // 👈 optional, for persistent data
        // .WithLifetime(ContainerLifetime.Persistent)  // 👈 optional, to avoid the long time a new container takes to start
    );

See https://learn.microsoft.com/en-au/azure/cosmos-db/emulator-linux#docker-commands for details of the env vars you can set on the docker container for configuring the vnext-preview emulator's behaviour.