.NET Aspire Azure Container Registry integration (Preview)

Includes: Hosting integration only — Client integration not included

Azure Container Registry (ACR) 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 NuGet package.

dotnet add package Aspire.Hosting.Azure.ContainerRegistry

<PackageReference Include="Aspire.Hosting.Azure.ContainerRegistry"
                  Version="*" />

For more information, see dotnet add package or Manage package dependencies in .NET applications.

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:

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();

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.

Provisioning-generated Bicep

If you're new to Bicep, 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:

@description('The ___location for the resource(s) to be deployed.')
param ___location string = resourceGroup().___location

resource my_acr 'Microsoft.ContainerRegistry/registries@2023-07-01' = {
  name: take('myacr${uniqueString(resourceGroup().id)}', 50)
  ___location: ___location
  sku: {
    name: 'Basic'
  }
  tags: {
    'aspire-resource-name': 'my-acr'
  }
}

output name string = my_acr.name

output loginServer string = my_acr.properties.loginServer

The preceding Bicep provisions an Azure Container Registry resource. Additionally, the added Azure Container App environment resource is also generated:

@description('The ___location for the resource(s) to be deployed.')
param ___location string = resourceGroup().___location

param userPrincipalId string

param tags object = { }

param my_acr_outputs_name string

resource env_mi 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
  name: take('env_mi-${uniqueString(resourceGroup().id)}', 128)
  ___location: ___location
  tags: tags
}

resource my_acr 'Microsoft.ContainerRegistry/registries@2023-07-01' existing = {
  name: my_acr_outputs_name
}

resource my_acr_env_mi_AcrPull 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(my_acr.id, env_mi.id, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7f951dda-4ed3-4680-a7ca-43fe172d538d'))
  properties: {
    principalId: env_mi.properties.principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7f951dda-4ed3-4680-a7ca-43fe172d538d')
    principalType: 'ServicePrincipal'
  }
  scope: my_acr
}

resource env_law 'Microsoft.OperationalInsights/workspaces@2023-09-01' = {
  name: take('envlaw-${uniqueString(resourceGroup().id)}', 63)
  ___location: ___location
  properties: {
    sku: {
      name: 'PerGB2018'
    }
  }
  tags: tags
}

resource env 'Microsoft.App/managedEnvironments@2024-03-01' = {
  name: take('env${uniqueString(resourceGroup().id)}', 24)
  ___location: ___location
  properties: {
    appLogsConfiguration: {
      destination: 'log-analytics'
      logAnalyticsConfiguration: {
        customerId: env_law.properties.customerId
        sharedKey: env_law.listKeys().primarySharedKey
      }
    }
    workloadProfiles: [
      {
        name: 'consumption'
        workloadProfileType: 'Consumption'
      }
    ]
  }
  tags: tags
}

resource aspireDashboard 'Microsoft.App/managedEnvironments/dotNetComponents@2024-10-02-preview' = {
  name: 'aspire-dashboard'
  properties: {
    componentType: 'AspireDashboard'
  }
  parent: env
}

resource env_Contributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(env.id, userPrincipalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c'))
  properties: {
    principalId: userPrincipalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c')
  }
  scope: env
}

output MANAGED_IDENTITY_NAME string = env_mi.name

output MANAGED_IDENTITY_PRINCIPAL_ID string = env_mi.properties.principalId

output AZURE_LOG_ANALYTICS_WORKSPACE_NAME string = env_law.name

output AZURE_LOG_ANALYTICS_WORKSPACE_ID string = env_law.id

output AZURE_CONTAINER_REGISTRY_NAME string = my_acr_outputs_name

output AZURE_CONTAINER_REGISTRY_ENDPOINT string = my_acr.properties.loginServer

output AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID string = env_mi.id

output AZURE_CONTAINER_APPS_ENVIRONMENT_NAME string = env.name

output AZURE_CONTAINER_APPS_ENVIRONMENT_ID string = env.id

output AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN string = env.properties.defaultDomain

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 PublishAsExisting method with the registry name and resource group:

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();

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.

builder.AddProject("api", "../Api/Api.csproj")
       .WithRoleAssignments(acr, ContainerRegistryBuiltInRole.AcrPush);

See also

• Azure Container Registry documentation
• .NET Aspire Azure integrations overview