Add WithUniqueResourceNaming to opt into collision-free managed environment names

[mitchdenny]

Description

Multiple AddAzureContainerAppEnvironment(...) resources deployed to the same resource group generate identical managed-environment names, collapsing onto a single physical Azure environment and racing with ManagedEnvironmentOperationInProgress.

Root cause: ContainerAppManagedEnvironment inherits Azure.Provisioning's ResourceNameRequirements(1, 24, LowercaseLetters), whose sanitizer strips digits. So environments named e.g. cae1/cae2 both resolve to take('cae${uniqueString(resourceGroup().id)}', 24) — the same name in a shared resource group.

Approach: opt-in, non-breaking

Changing the managed environment name by default would rename already-deployed environments and force Azure to recreate them, which is far too dangerous to ship as a default. So the fix is opt-in, mirroring how WithCompactResourceNaming shipped:

• Default behavior is unchanged — output is byte-identical to today, so existing deployments (including single-environment apps) are completely unaffected.
• WithUniqueResourceNaming() is a new per-environment extension method that opts into digit-preserving managed environment names, so distinct resource names produce distinct environment names. Apply it to each AddAzureContainerAppEnvironment(...) that needs to coexist with others in the same resource group.

The method is marked [Experimental("ASPIREACANAMING001")]. It is implemented as a scoped fallback ResourceNamePropertyResolver, so any name resolver explicitly configured by the caller (e.g. AspireV8ResourceNamePropertyResolver) still takes precedence.

Fixes #18722

Validation

Unit tests assert the generated Bicep names: collision is preserved by default, and WithUniqueResourceNaming() produces distinct digit-preserving names. The fix was also validated with real aspire deploy runs against live Azure for both single-CAE and multi-CAE scenarios — see the detailed testing report in the PR comments. A deployment E2E test deploys two environments into one resource group and asserts Azure contains two distinct managed environments.

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

[mitchdenny]

Real Azure deployment validation for #18722

I validated this fix with real aspire deploy runs against live Azure (subscription midenn, region westus3), across a three-phase matrix covering both the single-CAE and multi-CAE scenarios. Each scenario reused one resource group across all three phases so the redeploy/rename behaviour is visible.

Test apps

Two minimal AppHosts, each attaching public-image containers to Container App Environments (no image build/push needed):

// Single
var cae1 = builder.AddAzureContainerAppEnvironment("cae1");
builder.AddContainer("web1", "mcr.microsoft.com/dotnet/samples", "aspnetapp")
    .WithHttpEndpoint(targetPort: 8080).WithComputeEnvironment(cae1);

// Multi
var cae1 = builder.AddAzureContainerAppEnvironment("cae1");
var cae2 = builder.AddAzureContainerAppEnvironment("cae2");
builder.AddContainer("web1", ...).WithComputeEnvironment(cae1);
builder.AddContainer("web2", ...).WithComputeEnvironment(cae2);

CLI: aspire 13.5.0-preview.1.26355.1. The "no-fix" baseline was produced by stashing the fix; phases 2/3 restored it. The library builds from source via in-repo project references, so each phase deploys exactly the working-tree state.

Phase 1 — no fix (reproduce the bug)

Both CAEs generate the identical managed-environment name because the Azure.Provisioning name sanitizer strips digits, so cae1/cae2 both collapse to take('cae${uniqueString(resourceGroup().id)}', 24):

cae1/cae1.bicep:42  name: take('cae${uniqueString(resourceGroup().id)}', 24)
cae2/cae2.bicep:42  name: take('cae${uniqueString(resourceGroup().id)}', 24)   ← identical

Multi (bug): deploy failed exactly as reported in the issue —

✗ provision-cae2: ManagedEnvironmentOperationInProgress: Cannot modify Container Apps
  environment caeiucdjryuegdpu because another operation is in progress.

Resulting Azure state: one managed environment (caeiucdjryuegdpu) despite two AddAzureContainerAppEnvironment(...) calls, and only web1 deployed — web2 was lost. ✅ bug reproduced.

Single (baseline): deployed fine, env caekzeq3vbgappqw, web1 attached.

Phase 2 — with fix (distinct naming)

The fix preserves digits in the name prefix, so the environments become distinct. Notably the uniqueString hash is byte-identical across runs (same RG) — the only change is the restored digit, which pinpoints the root cause:

cae1/cae1.bicep:42  name: take('cae1${uniqueString(resourceGroup().id)}', 24)
cae2/cae2.bicep:42  name: take('cae2${uniqueString(resourceGroup().id)}', 24)

Multi: both environments provisioned distinctly and web2 deployed successfully — the original ManagedEnvironmentOperationInProgress collision is gone. Because this RG already held a no-fix deployment, web1 surfaced the expected redeploy consequence:

✗ provision-web1-containerapp: ContainerAppEnvironmentMismatch: Container App 'web1'
  already exists in a different environment. To create it in ...cae1iucdjryuegdpu,
  delete it from caeiucdjryuegdpu first.

Azure state after: caeiucdjryuegdpu (old, still holds web1), cae1iucdjryuegdpu (new, empty), cae2iucdjryuegdpu (new, holds web2).

Single: same behaviour — env renamed caekzeq3vbgappqw → cae1kzeq3vbgappqw; web1 hit the same mismatch.

This is the key finding that motivates the opt-out: the default naming change is correct for new deployments, but existing deployments cannot silently migrate a container app to a renamed environment.

Phase 3 — WithSingletonResourceNaming() (pin legacy name)

Applying .WithSingletonResourceNaming() pins an environment back to the legacy cae${uniqueString(...)} name. In the multi scenario I pinned only cae1 (the one already deployed under the legacy name) and left cae2 distinct:

cae1/cae1.bicep:42  name: take('cae${uniqueString(resourceGroup().id)}', 24)   ← pinned legacy
cae2/cae2.bicep:42  name: take('cae2${uniqueString(resourceGroup().id)}', 24)  ← distinct

Multi: deploy succeeded (exit 0) — web1 matched its existing legacy env, web2 matched its distinct env, no mismatch, no collision.
Single: deploy succeeded (exit 0) — web1 redeployed cleanly against the pinned caekzeq3vbgappqw.

This confirms the opt-out lets an already-deployed environment avoid rename churn while any additional CAEs still get collision-free distinct names.

Results

Phase	Scenario	Outcome
1 no-fix	single	✅ baseline env caekzeq3vbgappqw
1 no-fix	multi	❌ ManagedEnvironmentOperationInProgress — bug reproduced, only 1 env / web2 lost
2 fix	single	env renamed cae…→cae1…; web1 mismatch (expected redeploy churn)
2 fix	multi	✅ distinct envs, web2 deploys; web1 mismatch (expected redeploy churn)
3 pin	single	✅ exit 0 — legacy name restored, clean redeploy
3 pin	multi	✅ exit 0 — cae1 pinned legacy + cae2 distinct, both apps deploy

Conclusion: the default fix eliminates the colliding-name bug for new deployments, the redeploy churn on existing deployments is real and expected (Azure won't move a container app between environments), and WithSingletonResourceNaming() is the correct, verified escape hatch for that case.

Note: the orphaned environments left behind in phase 2 (cae1kzeq3vbgappqw, cae1iucdjryuegdpu) are artifacts of the deliberate same-RG rename test, not of normal usage. Test resource groups were cleaned up after validation.

[github-actions]

🚀 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 -- 18737

Or

• Run remotely in PowerShell:

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

[Copilot]

Pull request overview

Fixes Azure Container Apps managed environment name collisions when multiple AddAzureContainerAppEnvironment(...) resources are deployed into the same resource group by explicitly setting the managed environment name (preserving digits) in the default naming path, and adds an opt-out API to preserve legacy singleton naming.

Changes:

• Explicitly sets ContainerAppManagedEnvironment.Name (non-azd, non-singleton) to include the resource name prefix to avoid collisions.
• Adds WithSingletonResourceNaming() (experimental) to preserve the pre-fix managed environment naming behavior.
• Adds unit tests that assert the generated managed environment name: expressions in emitted Bicep.

Show a summary per file

File	Description
tests/Aspire.Hosting.Azure.Tests/AzureContainerAppsTests.cs	Adds regression tests asserting distinct managed environment names by default and legacy naming when opting out.
src/Aspire.Hosting.Azure.AppContainers/AzureContainerAppExtensions.cs	Sets managed environment Name explicitly to prevent collisions; introduces WithSingletonResourceNaming() API and helper prefix builder.
src/Aspire.Hosting.Azure.AppContainers/AzureContainerAppEnvironmentResource.cs	Adds internal flag to support singleton naming opt-out behavior.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 1
• Review effort level: Low

[mitchdenny]

Root-cause analysis: why this was latent since #8606

This is not a fresh regression — it's a latent gap introduced when managed environment naming was first made resource-name-aware, which the test suite structurally couldn't catch.

Origin: PR #8606

Before #8606, the managed environment was created with a fixed literal identifier:

var containerAppEnvironment = new ContainerAppManagedEnvironment("cae")

There was only ever one environment, so its default name take('cae${uniqueString(resourceGroup().id)}', 24) was fine.

#8606 ("AddAzureContainerAppEnvironment should use the environment name as a prefix") deliberately changed it to derive the name from the resource, with the explicit intent of "allow[ing] for multiple environments to be in a single distributed application in the future":

var containerAppEnvironment = new ContainerAppManagedEnvironment(appEnvResource.GetBicepIdentifier())

Why it silently broke

#8606 only changed the bicep symbolic identifier (the cae1/cae2 module/symbol names). It never set containerAppEnvironment.Name explicitly in the default path, so the actual Azure name: property was still left to Azure.Provisioning's default. That default sanitizer keeps lowercase letters only (ContainerAppManagedEnvironment inherits ResourceNameRequirements(1, 24, LowercaseLetters)), stripping digits — so cae1 and cae2 both collapse to take('cae${uniqueString(resourceGroup().id)}', 24).

That is why it went unnoticed:

• The generated bicep looks correct — the symbols/modules are genuinely distinct (cae1, cae2).
• Only the runtime-evaluated name: expression collides, and uniqueString(resourceGroup().id) is identical within a single resource group.
• The existing MultipleAzureContainerAppEnvironmentsSupported test only snapshots the manifest; it never asserts that the two name: expressions differ. So AddAzureContainerAppEnvironment should use the environment name as a prefix #8606's own intent (multi-environment support) was silently defeated from day one.

It's the third fix in this naming-collision family

• AddAzureContainerAppEnvironment should use the environment name as a prefix #8606 — introduced resource-name prefixing intent, but only at the symbol level.
• #14442 / [AzureContainerAppEnvironment] Azure resource name contains too many static characters #14427 — WithCompactResourceNaming() fixed the sibling collision: long environment names truncating the uniqueString suffix in storage account names.
• Multiple AzureContainerAppEnvironments in one resource group generate colliding managed-environment names #18722 (this fix) — finally sets the managed environment name: explicitly, preserving digits.

Residual constraint worth noting

Because uniqueString(resourceGroup().id) is identical for environments in the same resource group, the only differentiator is the name prefix. Since the name is take('{prefix}{uniqueString}', 24) and managed-environment names cap at 24 chars, two environments whose sanitized names match in the first 24 characters would still collide. #14427 already demonstrated this truncation-collision class is real (for storage names). It's a narrow edge case (long, similar names), but the fix's correctness rests on the prefix surviving truncation.

Why the new test closes the gap

The suite previously asserted on bicep shape rather than name distinctness. The new MultipleAzureContainerAppEnvironmentsGenerateDistinctManagedEnvironmentNames test asserts the two managed-environment name: expressions differ (and encode the resource-name digit), which is exactly the assertion that was missing.

[Copilot]

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 4
• Review effort level: Medium

[github-actions]

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

[Copilot]

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 4
• Review effort level: Medium

[Copilot]

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 1
• Review effort level: Medium

[Copilot]

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 2
• Review effort level: Medium

[github-actions]

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

[Copilot]

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 0 new
• Review effort level: Low

[Copilot]

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 1
• Review effort level: Medium

[mitchdenny]

PR Testing Report

PR Information

• PR Number: Add WithUniqueResourceNaming to opt into collision-free managed environment names #18737
• Title: Opt-in unique managed-environment naming for multiple Azure Container App Environments
• Head Commit: bea856e
• Tested At: 2026-07-13T04:42:00Z

Artifact Version Verification

• Expected Commit: bea856e
• Installed Version: 13.5.0-pr.18737.gbea856eb
• Status: Verified (installed dogfood CLI version contains PR head short SHA bea856eb)

Changes Analyzed

Change Categories

• Hosting integration changes (src/Aspire.Hosting.Azure.AppContainers/)
• Test changes (tests/Aspire.Hosting.Azure.Tests/, tests/Aspire.Deployment.EndToEnd.Tests/)
• CLI / Dashboard / Template / Component / VS Code extension / CI changes

The PR adds an opt-in, non-breaking WithUniqueResourceNaming() extension method for
AddAzureContainerAppEnvironment(...). Default behavior is preserved byte-for-byte; the
opt-in computes a collision-resistant managed-environment name using Azure.Provisioning's
standard resolver algorithm (digits preserved, hyphen separator, max length 32).

Methodology

Validation targets publish-time Bicep generation, which is where the naming contract is
produced. A single-file AppHost (apphost.cs) was created from the PR hive
(13.5.0-pr.18737.gbea856eb), referencing Aspire.Hosting.Azure.AppContainers at the same
version. aspire publish was run per scenario and the generated
Microsoft.App/managedEnvironments name: expression was inspected in each environment's
.bicep module. All publishes completed successfully (exit 0).

Test Scenarios Executed

Scenario 1: Default behavior (no opt-in) — regression guard

Objective: Two environments cae1/cae2 with no opt-in must keep the legacy name (proves no breaking change; reproduces the collision).
Coverage Type: Happy path / regression guard
Status: Passed

Generated managed-environment name: in both cae1/cae1.bicep and cae2/cae2.bicep:

name: take('cae${uniqueString(resourceGroup().id)}', 24)

Both are identical — the legacy behavior is preserved exactly, and the underlying #18722
collision is reproduced when the fix is not opted into.

Scenario 2: Both environments opted in — distinct names

Objective: cae1/cae2 both call .WithUniqueResourceNaming() and must produce distinct names.
Coverage Type: Happy path (core fix)
Status: Passed

// cae1/cae1.bicep
name: take('cae1-${uniqueString(resourceGroup().id)}', 32)
// cae2/cae2.bicep
name: take('cae2-${uniqueString(resourceGroup().id)}', 32)

Digits are preserved, a hyphen separator is used, and max length is 32 — matching the
standard Azure resource naming algorithm. The collision is resolved.

Scenario 3: Hyphenated name boundary (my-cae1) opted in

Objective: Verify how a hyphenated Aspire resource name is sanitized under opt-in.
Coverage Type: Boundary
Status: Passed

// my-cae1/my-cae1.bicep
name: take('mycae1-${uniqueString(resourceGroup().id)}', 32)

The resource-name hyphen is dropped (Bicep identifier my_cae1 -> sanitizer removes the
separator), the trailing digit is preserved, and the unique-string suffix is separated by a
hyphen. Matches the documented behavior.

Scenario 4: Mixed opt-in (one on, one off) — unhappy/partial-adoption path

Objective: Confirm opt-in is per-environment and one environment opting in does not alter the other.
Coverage Type: Unhappy path / partial adoption
Status: Passed

// cae1/cae1.bicep (opted in)
name: take('cae1-${uniqueString(resourceGroup().id)}', 32)
// cae2/cae2.bicep (default)
name: take('cae${uniqueString(resourceGroup().id)}', 24)

The opted-in environment gets the distinct name; the default one retains the legacy name.
The two names differ, so no collision occurs. This confirms the opt-in is scoped to the
individual environment and does not leak across resources.

Expected Unhappy-Path Outcome: Each environment's naming is independent; a partially
adopted AppHost produces a safe, non-colliding result and never silently rewrites the
non-opted-in environment's name.

Summary

Scenario	Status	Result
1. Default (no opt-in)	Passed	Both cae${uniqueString} (24) — legacy preserved, collision reproduced
2. Both opted in	Passed	Distinct cae1-... / cae2-... (32)
3. Hyphen boundary my-cae1	Passed	mycae1-... (32)
4. Mixed opt-in	Passed	cae1-... (32) + cae${uniqueString} (24), no collision

Overall Result

PR VERIFIED

• Default path is byte-identical to shipped behavior (no breaking change, no forced
  environment re-creation on redeploy).
• Opt-in produces distinct, standard-algorithm-consistent names that resolve the Multiple AzureContainerAppEnvironments in one resource group generate colliding managed-environment names #18722
  collision.
• Opt-in is correctly scoped per environment.

Notes / Recommendations

• Validation was performed at the aspire publish Bicep-generation layer (no live Azure
  deploy in this run). The repository additionally carries live deployment E2E coverage in
  tests/Aspire.Deployment.EndToEnd.Tests/AcaCompactNamingDeploymentTests.cs.
• Follow-up (tracked separately): the polyglot fixtures under
  tests/PolyglotAppHosts/Aspire.Hosting.Azure.AppContainers/ (Go/Java/TypeScript) could be
  extended to exercise withUniqueResourceNaming() for cross-language coverage.

[Copilot]

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 1
• Review effort level: Medium

[github-actions]

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

[github-actions]

Tests selector (audit mode)

The full test matrix and all jobs still run in audit mode. The tests and jobs below are what selective CI would run under enforcement.

9 / 100 test projects · 3 jobs, from 4 changed files.

Selected test projects (9 / 100)

Aspire.Deployment.EndToEnd.Tests, Aspire.Hosting.Azure.Kubernetes.Tests, Aspire.Hosting.Azure.Tests, Aspire.Hosting.Blazor.Tests, Aspire.Hosting.CodeGeneration.TypeScript.Tests, Aspire.Hosting.Dotnet.Tests, Aspire.Hosting.Radius.Tests, Aspire.Hosting.Tests, Aspire.Playground.Tests

Selected jobs (3)

deployment-e2e, extension-e2e, typescript-api-compat

---

How these were chosen — grouped by what changed

🔧 src/Aspire.Hosting.Azure.AppContainers/AzureContainerAppEnvironmentResource.cs (changed source)
→ 1 directly: Aspire.Hosting.Azure.Tests
→ 6 via the project graph: Aspire.Hosting.Blazor.Tests (2 hops), Aspire.Hosting.CodeGeneration.TypeScript.Tests, Aspire.Hosting.Dotnet.Tests (2 hops), Aspire.Hosting.Radius.Tests (2 hops), Aspire.Hosting.Tests, Aspire.Playground.Tests (2 hops)

🧪 tests/Aspire.Hosting.Azure.Tests/AzureContainerAppsTests.cs (changed test)
→ 1 directly: Aspire.Hosting.Azure.Tests
→ 1 via the project graph: Aspire.Hosting.Azure.Kubernetes.Tests

🔧 src/Aspire.Hosting.Azure.AppContainers/AzureContainerAppExtensions.cs (changed source)
→ 1 directly: Aspire.Hosting.Azure.Tests

🧪 tests/Aspire.Deployment.EndToEnd.Tests/AcaCompactNamingDeploymentTests.cs (changed test)
→ 1 directly: Aspire.Deployment.EndToEnd.Tests

Job reasons

Job	Triggered by
deployment-e2e	• tests/Aspire.Deployment.EndToEnd.Tests/AcaCompactNamingDeploymentTests.cs • affected project Aspire.Hosting.Azure.AppContainers
extension-e2e	• src/Aspire.Hosting.Azure.AppContainers/AzureContainerAppEnvironmentResource.cs, src/Aspire.Hosting.Azure.AppContainers/AzureContainerAppExtensions.cs • affected project Aspire.Hosting.Azure.AppContainers
typescript-api-compat	affected project Aspire.Hosting.Azure.AppContainers

---

Selection computed for commit e109f1e.

[Copilot]

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 3
• Review effort level: Medium

[github-actions]

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