Add ACR hosting integration content.

docs/azure/container-registry-integration.md

@@ -0,0 +1,114 @@
+---
+title: Azure Container Registry integration (Preview)
+description: Learn how to integrate Azure Container Registry with .NET Aspire for secure container image management.
+ms.date: 05/09/2025
+---
+
+# .NET Aspire Azure Container Registry integration (Preview)
+
+[!INCLUDE [includes-hosting](../includes/includes-hosting.md)]
+
+> [!IMPORTANT]
+> The .NET Aspire Azure Functions integration is currently in preview and is subject to change.
+
+[Azure Container Registry (ACR)](/azure/container-registry) is a managed Docker container registry service that simplifies the storage, management, and deployment of container images. The .NET Aspire integration allows you to provision or reference an existing Azure Container Registry and seamlessly integrate it with your app's compute environments.
+
+## Overview
+
+.NET Aspire apps often build and run container images locally but require secure registries for staging and production environments. The Azure Container Registry integration provides the following capabilities:
+
+- Provision or reference an existing Azure Container Registry.
+- Attach the registry to any compute-environment resource (for example, Azure Container Apps, Docker, Kubernetes) to ensure proper credential flow.
+- Grant fine-grained ACR role assignments to other Azure resources.
+
+## Supported scenarios
+
+The Azure Container Registry integration supports the following scenarios:
+
+- **Provisioning a new registry**: Automatically create a new Azure Container Registry for your app.
+- **Referencing an existing registry**: Use an existing Azure Container Registry by providing its name and resource group.
+- **Credential management**: Automatically flow credentials to compute environments for secure image pulls.
+- **Role assignments**: Assign specific roles (for example, `AcrPush`) to enable services to push images to the registry.
+
+## Hosting integration
+
+The Azure Container Registry integration is part of the .NET Aspire hosting model. It allows you to define and manage your app's resources in a declarative manner. The integration is available in the [📦 Aspire.Hosting.Azure.ContainerRegistry](https://www.nuget.org/packages/Aspire.Hosting.Azure.ContainerRegistry) NuGet package.
+
+### [.NET CLI](#tab/dotnet-cli)
+
+```dotnetcli
+dotnet add package Aspire.Hosting.Azure.ContainerRegistry
+```
+
+### [PackageReference](#tab/package-reference)
+
+```xml
+<PackageReference Include="Aspire.Hosting.Azure.ContainerRegistry"
+                  Version="*" />
+```
+
+---
+
+For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-package) or [Manage package dependencies in .NET applications](/dotnet/core/tools/dependencies).
+
+### Provision a new container registry
+
+The following example demonstrates how to provision a new Azure Container Registry and attach it to a container app environment:
+
+:::code source="snippets/acr//AspireAcr.AppHost/AspireAcr.AppHost/Program.cs":::
+
+The preceding code:
+
+- Creates a new Azure Container Registry named `my-acr`.
+- Attaches the registry to an Azure Container Apps environment named `env`.
+- Optionally grants the `AcrPush` role to a project resource named `api`, allowing it to push images to the registry.
+
+For more information, see [Configure Azure Container Apps environments](configure-aca-environments.md).
+
+> [!IMPORTANT]
+> When you call `AddAzureContainerRegistry` or `AddAzureContainerAppEnvironment`, they implicitly call the idempotent <xref:Aspire.Hosting.AzureProvisionerExtensions.AddAzureProvisioning*>—which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see [Local provisioning: Configuration](local-provisioning.md#configuration).
+
+#### Provisioning-generated Bicep
+
+If you're new to [Bicep](/azure/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With .NET Aspire, you don't need to write Bicep by-hand, instead the provisioning APIs generate Bicep for you. When you publish your app, the generated Bicep is output alongside the manifest file. When you add an Azure Container Registry resource, the following Bicep is generated:
+
+:::code language="bicep" source="snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/my-acr.module.bicep":::
+
+The preceding Bicep provisions an Azure Container Registry resource. Additionally, the added Azure Container App environment resource is also generated:
+
+:::code language="bicep" source="snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/env.module.bicep":::
+
+The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in C#. Customizations to the Bicep file directly are overwritten, so make changes through the C# provisioning APIs to ensure they're reflected in the generated files.
+
+### Reference an existing container registry
+
+To reference an existing Azure Container Registry, use the <xref:Aspire.Hosting.ExistingAzureResourceExtensions.PublishAsExisting*> method with the registry name and resource group:
+
+:::code source="snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/Program.Existing.cs" id="existing":::
+
+The preceding code:
+
+- References an existing Azure Container Registry named `my-acr` in the specified resource group.
+- Attaches the registry to an Azure Container Apps environment named `env`.
+- 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.
+
+### Key features
+
+**Automatic credential flow**
+
+When you attach an Azure Container Registry to a compute environment, Aspire automatically ensures that the correct credentials are available for secure image pulls.
+
+**Fine-grained role assignments**
+
+You can assign specific roles to Azure resources to control access to the container registry. For example, the `AcrPush` role allows a service to push images to the registry.
+
+```csharp
+builder.AddProject("api", "../Api/Api.csproj")
+       .WithRoleAssignments(acr, ContainerRegistryBuiltInRole.AcrPush);
+```
+
+## See also
+
+- [Azure Container Registry documentation](/azure/container-registry)
+- [.NET Aspire Azure integrations overview](integrations-overview.md)

docs/azure/integrations-overview.md

@@ -1,7 +1,7 @@
 ---
 title: Azure integrations overview
 description: Overview of the Azure integrations available in the .NET Aspire.
-ms.date: 04/10/2025
+ms.date: 05/09/2025
 uid: dotnet/aspire/integrations/azure-overview
 ---
 
@@ -323,6 +323,9 @@ The preceding code:
 
 To configure the Azure Container App environment, see [Configure Azure Container Apps environments](configure-aca-environments.md). For more information, see <xref:Azure.Provisioning.AppContainers.ContainerApp> and <xref:Aspire.Hosting.AzureProvisioningResourceExtensions.AsProvisioningParameter*>.
 
+> [!TIP]
+> If you're working with Azure Container Apps, you might also be interested in the [.NET Aspire Azure Container Registry integration](container-registry-integration.md).
+
 ## Infrastructure as code
 
 The Azure SDK for .NET provides the [📦 Azure.Provisioning](https://www.nuget.org/packages/Azure.Provisioning) NuGet package and a suite of service-specific [Azure provisioning packages](https://www.nuget.org/packages?q=owner%3A+azure-sdk+description%3A+declarative+resource+provisioning&sortby=relevance). These Azure provisioning libraries make it easy to declaratively specify Azure infrastructure natively in .NET. Their APIs enable you to write object-oriented infrastructure in C#, resulting in Bicep. [Bicep is a domain-specific language (DSL)](/azure/azure-resource-manager/bicep/overview) for deploying Azure resources declaratively.

docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/AspireAcr.AppHost.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <Sdk Name="Aspire.AppHost.Sdk" Version="9.2.0" />
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsAspireHost>true</IsAspireHost>
+    <UserSecretsId>4a4b5271-16e5-49fd-a7a1-ff2849aefc25</UserSecretsId>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.3.0-preview.1.25251.14" />
+    <PackageReference Include="Aspire.Hosting.Azure.AppContainers" Version="9.3.0-preview.1.25251.14" />
+    <PackageReference Include="Aspire.Hosting.Azure.ContainerRegistry" Version="9.3.0-preview.1.25251.14" />
+  </ItemGroup>
+
+</Project>

docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/Program.Existing.cs

@@ -0,0 +1,24 @@
+using Azure.Provisioning.ContainerRegistry;
+
+internal static partial class Program
+{
+    internal static void ReferenceExisting(string[] args)
+    {
+        // <existing>
+        var builder = DistributedApplication.CreateBuilder(args);
+
+        var registryName = builder.AddParameter("registryName");
+        var rgName = builder.AddParameter("rgName");
+
+        // Add (or reference) the registry
+        var acr = builder.AddAzureContainerRegistry("my-acr")
+                         .PublishAsExisting(registryName, rgName);
+
+        // Wire an environment to that registry
+        builder.AddAzureContainerAppEnvironment("env")
+               .WithAzureContainerRegistry(acr);
+
+        builder.Build().Run();
+        // </existing>
+    }
+}

docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/Program.cs

@@ -0,0 +1,12 @@
+using Azure.Provisioning.ContainerRegistry;
+
+var builder = DistributedApplication.CreateBuilder(args);
+
+// Add (or reference) the registry
+var acr = builder.AddAzureContainerRegistry("my-acr");
+
+// Wire an environment to that registry
+builder.AddAzureContainerAppEnvironment("env")
+       .WithAzureContainerRegistry(acr);
+
+builder.Build().Run();

docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/Properties/launchSettings.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "https://localhost:17190;http://localhost:15027",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development",
+        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21284",
+        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22130"
+      }
+    },
+    "http": {
+        "commandName": "Project",
+        "dotnetRunMessages": true,
+        "launchBrowser": true,
+        "applicationUrl": "http://localhost:15027",
+        "environmentVariables": {
+            "ASPNETCORE_ENVIRONMENT": "Development",
+            "DOTNET_ENVIRONMENT": "Development",
+            "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19098",
+            "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20225"
+        }
+    },
+    "generate-manifest": {
+        "commandName": "Project",
+        "launchBrowser": false,
+        "dotnetRunMessages": true,
+        "commandLineArgs": "--publisher manifest --output-path aspire-manifest.json",
+    }
+  }
+}

docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/api-identity.module.bicep

@@ -0,0 +1,15 @@
+@description('The location for the resource(s) to be deployed.')
+param location string = resourceGroup().location
+
+resource api_identity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
+  name: take('api_identity-${uniqueString(resourceGroup().id)}', 128)
+  location: location
+}
+
+output id string = api_identity.id
+
+output clientId string = api_identity.properties.clientId
+
+output principalId string = api_identity.properties.principalId
+
+output principalName string = api_identity.name

docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/api-roles-my-acr.module.bicep

@@ -0,0 +1,20 @@
+@description('The location for the resource(s) to be deployed.')
+param location string = resourceGroup().location
+
+param my_acr_outputs_name string
+
+param principalId string
+
+resource my_acr 'Microsoft.ContainerRegistry/registries@2023-07-01' existing = {
+  name: my_acr_outputs_name
+}
+
+resource my_acr_AcrPush 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
+  name: guid(my_acr.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8311e382-0749-4cb8-b61a-304f252e45ec'))
+  properties: {
+    principalId: principalId
+    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8311e382-0749-4cb8-b61a-304f252e45ec')
+    principalType: 'ServicePrincipal'
+  }
+  scope: my_acr
+}

docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/api.module.bicep

@@ -0,0 +1,84 @@
+@description('The location for the resource(s) to be deployed.')
+param location string = resourceGroup().location
+
+param api_identity_outputs_id string
+
+param api_identity_outputs_clientid string
+
+param api_containerport string
+
+param env_outputs_azure_container_apps_environment_default_domain string
+
+param env_outputs_azure_container_apps_environment_id string
+
+param env_outputs_azure_container_registry_endpoint string
+
+param env_outputs_azure_container_registry_managed_identity_id string
+
+param api_containerimage string
+
+resource api 'Microsoft.App/containerApps@2024-03-01' = {
+  name: 'api'
+  location: location
+  properties: {
+    configuration: {
+      activeRevisionsMode: 'Single'
+      ingress: {
+        external: false
+        targetPort: api_containerport
+        transport: 'http'
+      }
+      registries: [
+        {
+          server: env_outputs_azure_container_registry_endpoint
+          identity: env_outputs_azure_container_registry_managed_identity_id
+        }
+      ]
+    }
+    environmentId: env_outputs_azure_container_apps_environment_id
+    template: {
+      containers: [
+        {
+          image: api_containerimage
+          name: 'api'
+          env: [
+            {
+              name: 'OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES'
+              value: 'true'
+            }
+            {
+              name: 'OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES'
+              value: 'true'
+            }
+            {
+              name: 'OTEL_DOTNET_EXPERIMENTAL_OTLP_RETRY'
+              value: 'in_memory'
+            }
+            {
+              name: 'ASPNETCORE_FORWARDEDHEADERS_ENABLED'
+              value: 'true'
+            }
+            {
+              name: 'HTTP_PORTS'
+              value: api_containerport
+            }
+            {
+              name: 'AZURE_CLIENT_ID'
+              value: api_identity_outputs_clientid
+            }
+          ]
+        }
+      ]
+      scale: {
+        minReplicas: 1
+      }
+    }
+  }
+  identity: {
+    type: 'UserAssigned'
+    userAssignedIdentities: {
+      '${api_identity_outputs_id}': { }
+      '${env_outputs_azure_container_registry_managed_identity_id}': { }
+    }
+  }
+}