Align Azure Cosmos DB emulator with GA vnext-latest image by guanzhousongmicrosoft · Pull Request #18161 · microsoft/aspire

guanzhousongmicrosoft · 2026-06-12T15:44:52Z

Description

#18158 (merged) bumped the Azure Cosmos DB Linux-based (vNext) emulator image
tag to the GA vnext-latest. This PR completes the GA alignment of the Aspire
integration: it updates the integration's internal naming and docs from
"preview" to "vNext", fixes emulator environment-variable inconsistencies, and
adds comprehensive test coverage for the emulator surface.

What changes for users:

WithDataVolume() on the vNext emulator no longer emits the
AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE environment variable. That
variable is only honored by the classic (Windows) emulator; the vNext emulator
persists implicitly when a volume is mounted at /data, so setting it was a
no-op. It is still emitted for the classic emulator.
The in-container Data Explorer is now opt-in on the vNext emulator:
RunAsPreviewEmulator() sets ENABLE_EXPLORER=false by default, and
WithDataExplorer() re-enables it (ENABLE_EXPLORER=true). Previously the
explorer ran unconditionally (the GA image defaults it on), which also made the
emulator's /ready readiness probe wait on the explorer even when it was never
exposed (the probe is ready = postgres && gateway && (explorer || !ENABLE_EXPLORER)).
RunAsPreviewEmulator() continues to pull the GA vnext-latest image (from
Update Cosmos DB preview emulator tag to vnext-latest #18158). The public API and call site are unchanged.

Implementation details:

Internal naming aligned with the GA image: IsPreviewEmulator ->
IsVNextEmulator, useVNextPreview -> useVNext, parameter
isPreviewEmulator -> isVNext, plus comments, XML doc descriptions, and
NotSupportedException messages updated from "preview" to "Linux-based (vNext)".
CreateCosmosClient was extracted from a static local into an internal static
method so its branches can be unit-tested directly.
The public RunAsPreviewEmulator method and the
[Experimental("ASPIRECOSMOSDB001")] attribute are intentionally kept to avoid
a breaking API-surface change.

This change was validated against the GA emulator source: the gateway advertises
endpoints from GATEWAY_PUBLIC_ENDPOINT, and Aspire neutralizes the dynamic
host-port mapping by setting LimitToEndpoint = true for emulator connection
strings in the hosting seeding client and both the Cosmos and EF Core Cosmos
client integrations. The configured ports (gateway 8081, health /ready on
8080, Data Explorer 1234), PROTOCOL/EXPLORER_PROTOCOL/CERT_PATH/CERT_SECRET/NODE_EXTRA_CA_CERTS
env vars, and the /data persistence path all match the GA image.

User-facing usage

// Pulls mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest
var cosmos = builder.AddAzureCosmosDB("cosmos")
                    .RunAsPreviewEmulator(emulator =>
                    {
                        emulator.WithDataVolume();    // persists to /data
                        emulator.WithDataExplorer();  // opt-in: ENABLE_EXPLORER=true, exposes port 1234
                    });

Testing

Added comprehensive unit coverage for the emulator surface in
AzureCosmosDBExtensionsTests (141 Cosmos tests pass; build is clean, 0 warnings,
0 errors):

Default image tags (vnext-latest / stable); publish-mode no-op for both RunAsEmulator and RunAsPreviewEmulator.
WithDataVolume vNext (/data, no persistence env) vs classic (/tmp/cosmos/appdata + env), and a custom volume name.
WithPartitionCount happy path, boundary values (1/250), out-of-range throw, and vNext NotSupportedException.
WithDataExplorer opt-in (ENABLE_EXPLORER=true), default/custom host port, non-vNext throw, HTTPS endpoint flip, and the Data Explorer display-text URL callback.
vNext health endpoint (emulatorhealth/8080, ExcludeReferenceEndpoint, /ready, DetailsOnly URL) and classic health-check registration + factory guard.
Event-driven paths: OnConnectionStringAvailable initializes the client; OnResourceReady throws when the client is uninitialized.
CreateCosmosClient all three branches (emulator connection string → Gateway/LimitToEndpoint, non-emulator, absolute URI).
HTTPS certificate config callback (asserting PROTOCOL/EXPLORER_PROTOCOL/CERT_PATH/CERT_SECRET values, with/without password) and the certificate-trust callback (NODE_EXTRA_CA_CERTS).
vNext URL-based connection string (no DisableServerCertificateValidation) and classic connection string.

Coverage note: every emulator code path reachable without a live container is
now unit-tested. The only uncovered code is the OnResourceReady happy-path
body (ReadAccountAsync + database/container creation), which requires a live
emulator and is exercised by the functional tests that are currently skipped
(flaky #5820 / ActiveIssue #7178 / Docker-gated), plus defensive argument/null
guards and copy-paste defensive branches shared across Aspire integrations.

Fixes # (issue)

Checklist

Is this feature complete?
- Yes. Ready to ship.
- No. Follow-up changes expected.
Are you including unit tests for the changes and scenario tests if relevant?
- Yes
- No
Did you add public API?
- Yes
  - If yes, did you have an API Review for it?
    - Yes
    - No
  - Did you add <remarks /> and <code /> elements on your triple slash comments?
    - Yes
    - No
- No
Does the change make any security assumptions or guarantees?
- Yes
  - If yes, have you done a threat model and had a security review?
    - Yes
    - No
- No

github-actions · 2026-06-12T15:45:05Z

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 18161

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 18161"

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR renames the internal "preview emulator" concept to "vNext emulator" throughout the Azure Cosmos DB hosting code, and updates the container image tag from vnext-preview to vnext-latest. It also refines the WithDataVolume behavior to conditionally set the persistence environment variable only for the classic emulator, and adds explicit ENABLE_EXPLORER environment variable support for the vNext Data Explorer.

Changes:

Renamed IsPreviewEmulator → IsVNextEmulator, TagVNextPreview → TagVNextLatest, and useVNextPreview → useVNext across the codebase, updating the image tag from vnext-preview to vnext-latest.
Updated WithDataVolume so the AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE env var is only set for the classic emulator (not vNext), and added explicit ENABLE_EXPLORER=true to WithDataExplorer.
Added comprehensive unit tests covering the new emulator image tags, data volume paths, partition count validation, data explorer, and connection string format.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
`src/Aspire.Hosting.Azure.CosmosDB/CosmosDBEmulatorContainerImageTags.cs`	Rename constant and tag value from `vnext-preview` to `vnext-latest`
`src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBResource.cs`	Rename `IsPreviewEmulator` to `IsVNextEmulator` with updated doc
`src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs`	Rename parameters, update conditional logic for data volume and data explorer
`src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBEmulatorConnectionString.cs`	Rename parameter from `isPreviewEmulator` to `isVNext`
`.agents/skills/update-container-images/UpdateImageTags.cs`	Update unversioned tag check to `vnext-latest`
`.agents/skills/update-container-images/SKILL.md`	Update documentation for the new tag name
`tests/Aspire.Hosting.Azure.Tests/AzureCosmosDBExtensionsTests.cs`	Add tests for vNext emulator behaviors

The vNext (Linux-based) Cosmos DB emulator is GA and the image tag is vnext-latest, so the 'preview' terminology was misleading. Rename internal members IsPreviewEmulator -> IsVNextEmulator, useVNextPreview -> useVNext, and the isPreviewEmulator parameter -> isVNext, and update internal comments, XML doc descriptions, and NotSupportedException messages accordingly. The public RunAsPreviewEmulator API and the [Experimental] ASPIRECOSMOSDB001 attribute are intentionally left unchanged to avoid a breaking API-surface change. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com>

Two consistency fixes surfaced while validating against the GA vnext-latest emulator source: - WithDataVolume no longer sets AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE for the vNext emulator. That variable is only honored by the classic emulator; the vNext emulator persists implicitly when a volume is mounted at /data, so setting it was a no-op. - WithDataExplorer now sets ENABLE_EXPLORER=true explicitly instead of relying on the image's default remaining true. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com>

…orer, and vNext connection string Locks in the behavior aligned with the GA vnext-latest image: default image tags (vnext-latest for the vNext emulator, stable for classic), data volume path/persistence env var per emulator, WithPartitionCount guards, WithDataExplorer custom port + ENABLE_EXPLORER, and the URL-based vNext connection string format. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com>

The GA vnext-latest image defaults ENABLE_EXPLORER=true, which runs an otherwise-unused Node Data Explorer process and, because the readiness probe is 'ready = postgres && gateway && (explorer || !ENABLE_EXPLORER)', makes /ready wait on the explorer even when it is never exposed to the host. Set ENABLE_EXPLORER=false as a baseline on the vNext emulator; WithDataExplorer re-enables it (environment callbacks are last-write-wins). This makes the explorer opt-in - matching Aspire only exposing port 1234 when WithDataExplorer is called - avoids an unused process, and decouples readiness from the explorer. Adds tests for the default/opt-in/classic ENABLE_EXPLORER states and applies minor test polish (TryGetValue for clearer failures, shared CosmosConstants.EmulatorAccountKey, symmetric IsReadOnly assertion). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com>

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Covers the WithCertificateTrustConfiguration callback that sets NODE_EXTRA_CA_CERTS so the vNext emulator's Node-based Data Explorer trusts the Aspire-managed certificate bundle. This was the last unit-coverable emulator code path not already exercised; the remaining uncovered paths (OnConnectionStringAvailable/OnResourceReady/CreateCosmosClient) require a live emulator container and are covered only by the skipped functional tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com>

Extracts CreateCosmosClient from a static local into an internal static method so its three branches (absolute-URI/token-credential, emulator connection string with Gateway+LimitToEndpoint, and non-emulator) can be unit-tested directly. Adds tests for: the vNext health endpoint (emulatorhealth/8080, ExcludeReferenceEndpoint, health check), classic health-check annotation, WithDataVolume custom name, WithPartitionCount boundary values (1/250), WithDataExplorer default port, OnResourceReady throwing when the client is uninitialized (ResourceReadyEvent), OnConnectionStringAvailable initializing the client (ConnectionStringAvailableEvent), and CreateCosmosClient branches. Also strengthens the HTTPS cert callback tests to assert values (PROTOCOL/EXPLORER_PROTOCOL/CERT_PATH) rather than only key presence. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com>

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

Adds: explicit publish-mode no-op tests for RunAsEmulator/RunAsPreviewEmulator (the early return was already covered cross-file by AzureRunAsEmulatorModeTests, but a local test makes it explicit); a health-check factory guard test (the classic emulator CosmosClient factory throws 'CosmosClient is not initialized.' until the connection string is available); and URL display-callback tests for the vNext health endpoint (DisplayLocation=DetailsOnly) and the Data Explorer (DisplayText='Data Explorer'). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com>

Per Copilot review on microsoft#18161: clarify that 'postgres' in the readiness-probe formula refers to the vNext emulator's internal PostgreSQL storage engine, and document that 1234 is the emulator's fixed internal Data Explorer port (vs the configurable host port) in the Data Explorer tests. Comment-only changes; no behavior change. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com>

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

github-actions · 2026-06-12T21:36:13Z

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

Copilot AI review requested due to automatic review settings June 12, 2026 15:44

Copilot AI reviewed Jun 12, 2026

View reviewed changes

Comment thread tests/Aspire.Hosting.Azure.Tests/AzureCosmosDBExtensionsTests.cs

guanzhousongmicrosoft and others added 3 commits June 12, 2026 11:54

guanzhousongmicrosoft force-pushed the cosmos-emulator-add-tests branch from b342687 to 96c63eb Compare June 12, 2026 15:55

github-actions Bot mentioned this pull request Jun 12, 2026

[repo-pulse] 📊 Repo Pulse — Daily Activity Dashboard #16404

Open

Copilot AI review requested due to automatic review settings June 12, 2026 17:18

Copilot AI reviewed Jun 12, 2026

View reviewed changes

guanzhousongmicrosoft and others added 2 commits June 12, 2026 13:30

Copilot AI review requested due to automatic review settings June 12, 2026 18:21

Copilot AI reviewed Jun 12, 2026

View reviewed changes

Comment thread src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs Outdated

guanzhousongmicrosoft and others added 2 commits June 12, 2026 14:42

Copilot AI review requested due to automatic review settings June 12, 2026 20:41

Copilot AI reviewed Jun 12, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Align Azure Cosmos DB emulator with GA vnext-latest image#18161

Align Azure Cosmos DB emulator with GA vnext-latest image#18161
guanzhousongmicrosoft wants to merge 8 commits into
microsoft:mainfrom
guanzhousongmicrosoft:cosmos-emulator-add-tests

guanzhousongmicrosoft commented Jun 12, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 12, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

github-actions Bot commented Jun 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

guanzhousongmicrosoft commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

User-facing usage

Testing

Checklist

Uh oh!

github-actions Bot commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

github-actions Bot commented Jun 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

guanzhousongmicrosoft commented Jun 12, 2026 •

edited

Loading

github-actions Bot commented Jun 12, 2026 •

edited

Loading