.NET Aspire Azure 应用配置集成

2025-05-20

包含： - Client 集成

Azure 应用配置提供一项服务，用于集中管理应用程序设置和功能标志。新式程序，尤其是在云端运行的程序，通常具有多个事实上已分发的组件。跨这些组件分散配置设置可能导致应用程序部署过程中出现难以解决的错误。通过 .NET AspireAzure 应用配置集成，可以连接到现有的应用配置实例或从应用主机创建新的实例。

托管集成

应用 .NET AspireAzure 配置托管集成将应用配置资源建模为 AzureAppConfigurationResource 类型。要访问此类型和 API 用于表示资源，请在应用主机项目中添加 📦Aspire.Hosting.Azure.AppConfiguration NuGet 包。

.NETCLI（命令行界面）
包引用

dotnet add package Aspire.Hosting.Azure.AppConfiguration

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

有关详细信息，请参阅 dotnet 添加包或管理 .NET 应用程序中的包依赖性。

添加 Azure 应用配置资源

在应用主机项目中，调用 AddAzureAppConfiguration 添加并返回 Azure 应用配置资源生成器。

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

向应用主机添加一个 AzureAppConfigurationResource 时，它会公开其他有用的 API。

重要

调用 AddAzureAppConfiguration时，它会隐式调用 AddAzureProvisioning(IDistributedApplicationBuilder)，这增加了在应用启动期间动态生成 Azure 资源的支持。应用程序必须配置相应的订阅和位置。有关详细信息，请参阅本地预配：配置。

由预配生成的 Bicep

如果你不熟悉 Bicep，它是一种领域专用语言，用于定义 Azure 资源。使用 .NET.NET Aspire，您不需要手动编写 Bicep，预配 API 会为您自动生成 Bicep。发布应用时，生成的 Bicep 文件将会与清单文件一同输出。添加 Azure 应用配置资源时，将生成以下 Bicep：

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

resource config 'Microsoft.AppConfiguration/configurationStores@2024-05-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

Bicep 模块用于预配 Azure 应用配置资源。此外，在单独的模块中为 Azure 资源创建角色分配：

@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-05-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
}

生成的 Bicep 作为起点，受 C# 中资源配置基础设施更改的影响。直接对 Bicep 文件进行自定义的更改会被覆盖，因此需要通过 C# 预配 API 进行更改，以确保它们在生成的文件中得到反映。

自定义预配基础结构

所有 .NET AspireAzure 资源都是 AzureProvisioningResource 类型的子类。此类型提供了一种流畅的 API，可以通过 Azure API 来配置 ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) 资源，从而实现对生成的 Bicep 的自定义。例如，可以配置 sku、清除保护等。以下示例演示如何自定义 Azure 应用配置资源：

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

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

前面的代码：

将调用与 ConfigureInfrastructure API 链接起来：
- infra 参数是 AzureResourceInfrastructure 类型的实例。
- 通过调用 GetProvisionableResources() 方法检索可预配资源。
- 单个 AppConfigurationStore 已被检索。
- AppConfigurationStore.SkuName 被分配给 Free。
- 将一个标签添加到应用配置存储区，键为 ExampleKey，值为 Example value。

还有更多配置选项可用于自定义 Azure 应用配置资源。有关详细信息，请参阅 Azure.Provisioning.AppConfiguration。有关详细信息，请参阅 Azure。预配自定义。

使用现有的 Azure 应用配置资源

你可能有一个现有的 Azure 应用配置存储需要连接。如果要使用现有的 Azure 应用配置存储区，可以通过调用 AsExisting 该方法来执行此作。此方法接受配置存储和资源组名称作为参数，并使用它连接到现有的 Azure 应用配置存储资源。

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

有关详细信息，请参阅使用现有 Azure 资源。

连接到现有的 Azure 应用配置存储

使用 *AsExisting API 的替代方法可改为添加连接字符串，其中应用主机使用配置解析连接信息。若要将连接添加到现有 Azure 应用配置存储区，请调用 AddConnectionString 以下方法：

var builder = DistributedApplication.CreateBuilder(args);

var config = builder.AddConnectionString("config");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(config);

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

注释

连接字符串用于表示各种连接信息，包括数据库连接、消息代理、终结点 URI 和其他服务。在 .NET.NET Aspire 名词中，术语“连接字符串”用于表示任何类型的连接信息。

连接字符串是在应用主机的配置中配置的，通常在部分下的 ConnectionStrings下。应用主机将此连接字符串作为环境变量注入到所有依赖资源中，例如：

{
    "ConnectionStrings": {
        "config": "https://{store_name}.azconfig.io"
    }
}

依赖资源可以通过调用 GetConnectionString 方法并传递连接名称作为参数来访问注入的连接字符串，在本例中为 "config"。 GetConnectionString API 是 IConfiguration.GetSection("ConnectionStrings")[name]的简称。

Client 集成

若要开始使用.NET AspireAzure应用配置客户端集成，请在客户端消费项目中安装📦AspireMicrosoft.Extensions.Configuration.AzureAppConfiguration NuGet 包，该项目是使用应用配置客户端的应用程序的项目。应用配置客户端集成注册了一个 CosmosClient 实例，您可以使用该实例与应用配置进行交互。

.NETCLI（命令行界面）
包引用

dotnet add package Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration

<PackageReference Include="Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration"
                  Version="*" />

在客户端使用项目的Program.cs文件中，调用任何IHostApplicationBuilder上的AddAzureAppConfiguration扩展方法，以注册必要的服务，从而将应用配置值通过Azure流入IConfiguration实例，以便通过依赖注入容器使用。该方法采用连接名称参数。

builder.AddAzureAppConfiguration(connectionName: "config");

小窍门

参数 connectionName 必须与在应用主机项目中添加应用配置资源时使用的名称匹配。换句话说，在应用主机中调用 AddAzureAppConfiguration 并提供名称 config 时，应在客户端项目中调用 AddAzureAppConfiguration 时使用相同的名称。有关详细信息，请参阅 “添加 Azure 应用配置”资源。

然后，可以使用依赖项注入检索 IConfiguration 实例。例如，若要从示例服务检索客户端：

public class ExampleService(IConfiguration configuration)
{
    private readonly string _someValue = configuration["SomeKey"];
}

使用功能标志

若要使用功能标志，请安装 📦 Microsoft.FeatureManagement NuGet 包：

.NETCLI（命令行界面）
包引用

dotnet add package Microsoft.FeatureManagement

<PackageReference Include="Microsoft.FeatureManagement"
                  Version="*" />

默认情况下，应用配置不会加载功能标志。要加载功能标志，请在调用builder.AddAzureAppConfiguration时传递Action<AzureAppConfigurationOptions> configureOptions委托。

builder.AddAzureAppConfiguration(
    "config",
    configureOptions: options => options.UseFeatureFlags());

// Register feature management services
builder.Services.AddFeatureManagement();

然后可以使用IFeatureManager来评估应用中的功能标志。请考虑以下示例 ASP.NET Core 最小 API 应用：

using Microsoft.Extensions.Hosting;
using Microsoft.FeatureManagement;

var builder = WebApplication.CreateBuilder(args);

builder.AddAzureAppConfiguration(
    "config",
    configureOptions: options => options.UseFeatureFlags());

// Register feature management services
builder.Services.AddFeatureManagement();

var app = builder.Build();

app.MapGet("/", async (IFeatureManager featureManager) =>
{
    if (await featureManager.IsEnabledAsync("NewFeature"))
    {
        return Results.Ok("New feature is enabled!");
    }

    return Results.Ok("Using standard implementation.");
});

app.Run();

有关详细信息，请参阅 .NET 功能管理。

配置

.NET Aspire Azure应用配置库提供了多个选项，用于根据项目的要求和约定配置Azure应用配置连接。提供应用配置终结点是必须的，可以在 AzureAppConfigurationSettings.Endpoint 中指定或使用连接字符串。

使用连接字符串

使用 ConnectionStrings 配置部分中的连接字符串时，可以在调用 builder.AddAzureAppConfiguration()时提供连接字符串的名称：

builder.AddAzureAppConfiguration("config");

然后，从ConnectionStrings配置部分检索到应用配置终结点。应用配置存储 URI 同 AzureAppConfigurationSettings.Credential 属性一起使用，以建立连接。如果未配置凭据，则使用 DefaultAzureCredential。

{
  "ConnectionStrings": {
    "config": "https://{store_name}.azconfig.io"
  }
}

使用配置提供器

.NET Aspire Azure应用配置库支持 Microsoft.Extensions.Configuration。它使用 AzureAppConfigurationSettings 键来从配置中加载 Aspire:Microsoft:Extensions:Configuration:AzureAppConfiguration。 appsettings.json 配置某些选项的示例：

{
  "Aspire": {
    "Microsoft": {
      "Extensions": {
        "Configuration": {
          "AzureAppConfiguration": {
            "Endpoint": "YOUR_APPCONFIGURATION_ENDPOINT_URI"
          }
        }
      }
    }
  }
}

有关完整的应用配置客户端集成 JSON 架构，请参阅 ./ConfigurationSchema.json。

使用内联委托功能

还可以传递 Action<AzureAppConfigurationSettings> configureSettings 委托来设置部分或全部内联选项，例如，通过代码设置应用配置终结点：

builder.AddAzureAppConfiguration(
    "config",
    configureSettings: settings => settings.Endpoint = "http://YOUR_URI");

可观测性和遥测

.NET .NET Aspire 集成会自动设置日志记录、跟踪和指标等配置，这些配置有时称为 可观测性的基础支柱。有关集成可观测性和遥测的详细信息，请参阅 .NET.NET Aspire 集成概述。根据支持服务，某些集成可能仅支持其中一些功能。例如，某些集成支持日志记录和跟踪，但不支持指标。还可以使用 “配置” 部分中介绍的技术禁用遥测功能。

伐木业

.NET Aspire Azure应用配置集成使用以下日志类别：

Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh

追踪

.NET Aspire Azure应用配置集成不使用任何活动源，因此没有可用的跟踪。

指标

.NET Aspire Azure应用配置集成目前不支持指标。

通过