Azure App Configuration integration

Azure App Configuration provides a service to centrally manage application settings and feature flags. Modern programs, especially programs running in a cloud, generally have many components that are distributed in nature. Spreading configuration settings across these components can lead to hard-to-troubleshoot errors during an application deployment. The Aspire Azure App Configuration integration enables you to connect to existing App Configuration instances or create new instances all from your AppHost.

Hosting integration

The Aspire Azure App Configuration hosting integration models the App Configuration resource as the AzureAppConfigurationResource type. To access this type and APIs for expressing them within your AppHost project, install the 📦 Aspire.Hosting.Azure.AppConfiguration NuGet package:

Aspire CLI

Aspire CLI — Añadir paquete Aspire.Hosting.Azure.AppConfiguration

aspire add azure-appconfiguration

La CLI de Aspire es interactiva; asegúrate de seleccionar el resultado adecuado cuando se te pida:

Aspire CLI — Ejemplo de salida

Select an integration to add:

> azure-appconfiguration (Aspire.Hosting.Azure.AppConfiguration)
> Other results listed as selectable options...

Nota

Si solo hay un resultado, la CLI lo selecciona automáticamente. Aún tendrás que confirmar la versión.

apphost.cs (C# file-based app)

C# — AppHost.cs

#:package Aspire.Hosting.Azure.AppConfiguration@*

PackageReference (*.csproj)

XML — Añadir referencia de paquete Aspire.Hosting.Azure.AppConfiguration

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

Add an Azure App Configuration resource

To add an Azure App Configuration resource to your AppHost project, call the AddAzureAppConfiguration method providing a name:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var appConfig = builder.AddAzureAppConfiguration("config");

// After adding all resources, run the app...

builder.Build().Run();

When you add an AzureAppConfigurationResource to the AppHost, it exposes other useful APIs.

Precaución

When you call AddAzureAppConfiguration, it implicitly calls 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.

Provisioning-generated Bicep

If you’re new to Bicep, it’s a domain-specific language for defining Azure resources. With 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 App Configuration resource, the following Bicep is generated:

:::code language=“bicep” source=”../snippets/azure/AppHost/config/config.bicep”:::

Generated Bicep — config.bicep

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

resource config 'Microsoft.AppConfiguration/configurationStores@2024-06-01' = {
  name: take('config-${uniqueString(resourceGroup().id)}', 50)
  location: location
  properties: {
    disableLocalAuth: true
  }
  sku: {
    name: 'standard'
  }
  tags: {
    'aspire-resource-name': 'config'
  }
}

output appConfigEndpoint string = config.properties.endpoint

output name string = config.name

The preceding Bicep is a module that provisions an Azure App Configuration resource. Additionally, role assignments are created for the Azure resource in a separate module:

Generated Bicep — config-roles.bicep

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

param config_outputs_name string

param principalType string

param principalId string

resource config 'Microsoft.AppConfiguration/configurationStores@2024-06-01' existing = {
  name: config_outputs_name
}

resource config_AppConfigurationDataOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(config.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '5ae67dd6-50cb-40e7-96ff-dc2bfa4b606b'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '5ae67dd6-50cb-40e7-96ff-dc2bfa4b606b')
    principalType: principalType
  }
  scope: config
}

The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in C#. Customizations to the Bicep file directly will be overwritten, so make changes through the C# provisioning APIs to ensure they’re reflected in the generated files.

Customize provisioning infrastructure

All Aspire Azure resources are subclasses of the AzureProvisioningResource type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources—using the ConfigureInfrastructure API. For example, you can configure the sku, purge protection, and more. The following example demonstrates how to customize the Azure App Configuration resource:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureAppConfiguration("config")
    .ConfigureInfrastructure(infra =>
    {
        var appConfigStore = infra.GetProvisionableResources()
                                  .OfType<AppConfigurationStore>()
                                  .Single();

        appConfigStore.SkuName = "Free";
        appConfigStore.EnablePurgeProtection = true;
        appConfigStore.Tags.Add("ExampleKey", "Example value");
    });

The preceding code:

• Chains a call to the ConfigureInfrastructure API:
  • The infra parameter is an instance of the AzureResourceInfrastructure type.
  • The provisionable resources are retrieved by calling the GetProvisionableResources method.
  • The single AppConfigurationStore is retrieved.
  • The AppConfigurationStore.SkuName is assigned to Free.
  • A tag is added to the App Configuration store with a key of ExampleKey and a value of Example value.

There are many more configuration options available to customize the Azure App Configuration resource. For more information, see Azure.Provisioning customization.

Use existing Azure App Configuration resource

You might have an existing Azure App Configuration store that you want to connect to. If you want to use an existing Azure App Configuration store, you can do so by calling the AsExisting method. This method accepts the config store and resource group names as parameters, and uses it to connect to the existing Azure App Configuration store resource.

var builder = DistributedApplication.CreateBuilder(args);

var configName = builder.AddParameter("configName");
var configResourceGroupName = builder.AddParameter("configResourceGroupName");

var appConfig = builder.AddAzureAppConfiguration("config")
    .AsExisting(configName, configResourceGroupName);

// After adding all resources, run the app...

builder.Build().Run();

For more information, see Use existing Azure resources.

Connect to an existing Azure App Configuration instance

You might have an existing Azure App Configuration service that you want to connect to. You can chain a call to annotate that your AzureAppConfigurationResource is an existing resource:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var existingAppConfigName = builder.AddParameter("existingAppConfigName");
var existingAppConfigResourceGroup = builder.AddParameter("existingAppConfigResourceGroup");

var appConfig = builder.AddAzureAppConfiguration("app-config")
                       .AsExisting(existingAppConfigName, existingAppConfigResourceGroup);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(appConfig);

// After adding all resources, run the app...

For more information on treating Azure App Configuration resources as existing resources, see Use existing Azure resources.

Nota

Alternatively, instead of representing an Azure App Configuration resource, you can add a connection string to the AppHost. This approach is weakly-typed and doesn’t work with role assignments or infrastructure customizations.

Provisioning-generated Bicep

When you publish your app, Aspire provisioning APIs generate Bicep alongside the manifest file. Bicep is a domain-specific language for defining Azure resources. For more information, see Bicep Overview.

When you add an Azure App Configuration resource, Bicep is generated that provisions the resource. The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in C#. Customizations to the Bicep file directly will be overwritten, so make changes through the C# provisioning APIs to ensure they are reflected in the generated files.

Customize provisioning infrastructure

All Aspire Azure resources are subclasses of the AzureProvisioningResource type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources using the ConfigureInfrastructure API:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var appConfig = builder.AddAzureAppConfiguration("app-config");

appConfig.ConfigureInfrastructure(infra =>
{
    var configStore = infra.GetProvisionableResources()
                           .OfType<AppConfigurationStore>()
                           .Single();

    configStore.Sku = new AppConfigurationStoreSku
    {
        Name = "Standard"
    };
    configStore.Tags["ExampleKey"] = "Example value";
});

The preceding code:

• Chains a call to the ConfigureInfrastructure API:
  • The infra parameter is an instance of the AzureResourceInfrastructure type.
  • The provisionable resources are retrieved by calling the GetProvisionableResources method.
  • The single AppConfigurationStore resource is retrieved.
  • The Sku object has its name property set to Standard.
  • A tag is added to the App Configuration resource with a key of ExampleKey and a value of Example value.

There are many more configuration options available to customize the App Configuration resource. For more information, see Azure.Provisioning customization.

Client integration

The Aspire Azure App Configuration client integration is used to connect to an Azure App Configuration service. To get started with the Aspire Azure App Configuration client integration, install the 📦 Aspire.Azure.Data.AppConfiguration NuGet package.

.NET CLI

.NET CLI — Add Aspire.Azure.Data.AppConfiguration package

dotnet add package Aspire.Azure.Data.AppConfiguration

Program.cs (C# file-based app)

Program.cs

#:package Aspire.Azure.Data.AppConfiguration@*

PackageReference (*.csproj)

XML — Add Aspire.Azure.Data.AppConfiguration package reference

<PackageReference Include="Aspire.Azure.Data.AppConfiguration" Version="*" />

Add App Configuration client

In the Program.cs file of your client-consuming project, call the AddAzureAppConfiguration extension method to register a ConfigurationClient for use via the dependency injection container. The method takes a connection name parameter:

builder.AddAzureAppConfiguration(connectionName: "app-config");

Consejo

The connectionName parameter must match the name used when adding the App Configuration resource in the AppHost project.

After adding the ConfigurationClient, you can retrieve the client instance using dependency injection:

public class ExampleService(ConfigurationClient client)
{
    // Use client...
}

For more information, see:

• Azure.Data.AppConfiguration documentation for examples on using the ConfigurationClient.
• Dependency injection in .NET for details on dependency injection.

Add keyed App Configuration client

There might be situations where you want to register multiple ConfigurationClient instances with different connection names. To register keyed App Configuration clients, call the AddKeyedAzureAppConfiguration method:

builder.AddKeyedAzureAppConfiguration(name: "primary-config");
builder.AddKeyedAzureAppConfiguration(name: "secondary-config");

Then you can retrieve the client instances using dependency injection:

public class ExampleService(
    [KeyedService("primary-config")] ConfigurationClient primaryClient,
    [KeyedService("secondary-config")] ConfigurationClient secondaryClient)
{
    // Use clients...
}

For more information, see Keyed services in .NET.

Configuration

The Aspire Azure App Configuration library provides multiple options to configure the Azure App Configuration connection based on the requirements and conventions of your project. Either an Endpoint or a ConnectionString must be supplied.

Use a connection string

When using a connection string from the ConnectionStrings configuration section, you can provide the name of the connection string when calling AddAzureAppConfiguration:

builder.AddAzureAppConfiguration(connectionName: "app-config");

The connection information is retrieved from the ConnectionStrings configuration section. Two connection formats are supported:

• Service endpoint (recommended): Uses the service endpoint with DefaultAzureCredential.

  {
    "ConnectionStrings": {
      "app-config": "https://{account_name}.azconfig.io"
    }
  }

• Connection string: Includes an access key.

  {
    "ConnectionStrings": {
      "app-config": "Endpoint=https://{account_name}.azconfig.io;Id={id};Secret={secret}"
    }
  }

Use configuration providers

The library supports Microsoft.Extensions.Configuration. It loads settings from configuration using the Aspire:Azure:Data:AppConfiguration key:

{
  "Aspire": {
    "Azure": {
      "Data": {
        "AppConfiguration": {
          "DisableHealthChecks": true,
          "DisableTracing": false
        }
      }
    }
  }
}

Use inline delegates

You can configure settings inline:

builder.AddAzureAppConfiguration(
    "app-config",
    settings => settings.DisableHealthChecks = true);

Observability and telemetry

Aspire integrations automatically set up Logging, Tracing, and Metrics configurations.

Logging

The Aspire Azure App Configuration integration uses the following log categories:

• Azure
• Azure.Core
• Azure.Identity
• Azure.Data.AppConfiguration

Tracing

The Aspire Azure App Configuration integration will emit the following tracing activities using OpenTelemetry:

• Azure.Data.AppConfiguration.*

Metrics

The Aspire Azure App Configuration integration currently doesn’t support metrics by default due to limitations with the Azure SDK for .NET.