From adeb4b17f5cff061ce7bce9b742c9a7d666dc3d6 Mon Sep 17 00:00:00 2001
From: Mitch Denny <mitch@mitchdeny.com>
Date: Mon, 16 Feb 2026 09:17:10 +1100
Subject: [PATCH] Add migration guidance for IAzureContainerRegistry obsolete
 breaking change

Expand the breaking change section in aspire-13-2.mdx with:
- Explanation of why the interface was deprecated
- Full before/after code examples including ManagedIdentityId
- Note about managed identity handling changes

Update azure-container-registry.mdx with:
- New section showing ContainerRegistry property access pattern
- Deprecation notice linking to the breaking changes section

Fixes #414

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../cloud/azure/azure-container-registry.mdx  | 16 +++++++++++
 .../content/docs/whats-new/aspire-13-2.mdx    | 27 ++++++++++++++-----
 2 files changed, 37 insertions(+), 6 deletions(-)

diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry.mdx
index c15e2f39..cf89eda4 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry.mdx
@@ -109,6 +109,22 @@ The preceding code:
 - Uses parameters to allow for dynamic configuration of the registry name and resource group.
 - Optionally grants the `AcrPush` role to a project resource named `api`, allowing it to push images to the registry.
 
+### Access the registry from a compute environment
+
+Compute environments such as `AzureContainerAppEnvironment` and `AzureAppServiceEnvironment` automatically provision a default Azure Container Registry. You can also specify an explicit registry with `WithAzureContainerRegistry`. In either case, access the registry through the `ContainerRegistry` property:
+
+```csharp title="C# — Access the registry from the compute environment"
+var env = builder.AddAzureContainerAppEnvironment("env");
+
+// A default registry is auto-provisioned — no need to call
+// WithAzureContainerRegistry unless you want a specific one
+var registry = env.Resource.ContainerRegistry;
+```
+
+<Aside type="caution">
+  The `IAzureContainerRegistry` interface is obsolete as of Aspire 13.2. If your code casts a compute environment to `IAzureContainerRegistry`, migrate to the `ContainerRegistry` property on `IAzureComputeEnvironmentResource` instead. For more information, see [What's new in Aspire 13.2](/whats-new/aspire-13-2/#-breaking-changes).
+</Aside>
+
 ### Key features
 
 **Automatic credential flow**
diff --git a/src/frontend/src/content/docs/whats-new/aspire-13-2.mdx b/src/frontend/src/content/docs/whats-new/aspire-13-2.mdx
index f08b3d3e..eb462c82 100644
--- a/src/frontend/src/content/docs/whats-new/aspire-13-2.mdx
+++ b/src/frontend/src/content/docs/whats-new/aspire-13-2.mdx
@@ -444,18 +444,33 @@ Some connection properties have been updated for consistency. If your polyglot a
 
 ### IAzureContainerRegistry obsolete
 
-The `IAzureContainerRegistry` interface is now obsolete. Use the `ContainerRegistry` property on compute environments instead:
+The `IAzureContainerRegistry` interface is now obsolete. Previously, accessing container registry information from a compute environment required casting the environment to `IAzureContainerRegistry`. This mixed resource identity with deployment-target concerns. In Aspire 13.2, a new `IAzureContainerRegistryResource` interface models the registry as a proper resource, and you access it through the `ContainerRegistry` property on `IAzureComputeEnvironmentResource`.
 
-```csharp title="C# — Container registry access (before)" data-disable-copy
-// Before (Aspire 13.1)
+```csharp title="C# — Before: casting to IAzureContainerRegistry" data-disable-copy
+// Aspire 13.1 — cast the compute environment
 var registry = environment as IAzureContainerRegistry;
+if (registry is not null)
+{
+    var name = registry.Name;
+    var endpoint = registry.Endpoint;
+    var managedIdentityId = registry.ManagedIdentityId;
+}
 ```
 
-```csharp title="C# — Container registry access (after)"
-// After (Aspire 13.2)
+```csharp title="C# — After: using the ContainerRegistry property"
+// Aspire 13.2 — access directly from the compute environment
 var registry = environment.ContainerRegistry;
+if (registry is not null)
+{
+    var name = registry.Name;
+    var endpoint = registry.Endpoint;
+}
 ```
 
+<Aside type="note">
+  The `ManagedIdentityId` property is no longer on the container registry interface. Managed identity is now handled at the compute environment level.
+</Aside>
+
 ### Migration from Aspire 13.1 to 13.2
 
 <Steps>
@@ -464,7 +479,7 @@ var registry = environment.ContainerRegistry;
 2. **Update your projects**: Run `aspire update` in your project directory.
 3. **Run aspire doctor**: Validate your environment with `aspire doctor`.
 4. **Review event handlers**: Check any `BeforeResourceStartedEvent` handlers for compatibility.
-5. **Update Azure container registry access**: Replace `IAzureContainerRegistry` casts with `ContainerRegistry` property access.
+5. **Update Azure container registry access**: Replace any `IAzureContainerRegistry` casts with the `ContainerRegistry` property on `IAzureComputeEnvironmentResource`. Remove any references to `ManagedIdentityId` on the registry interface.
 
 </Steps>