Aspire Azure 应用配置集成

包含： 托管集成 —&— Client 集成

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

托管集成

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

dotnet add package Aspire.Hosting.Azure.AppConfiguration

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

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

添加 Azure 应用配置资源

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

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

向 AppHost 添加 a AzureAppConfigurationResource 时，它会公开其他有用的 API。

预配生成的 Bicep

如果你不熟悉 Bicep，它是一种领域专用语言，用于定义 Azure 资源。 使用 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-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

上述 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-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
}

生成的 Bicep 是一个起点，并受到 C# 中预配基础结构变化的影响。 对 Bicep 文件进行的自定义将直接被覆盖，因此请通过 C# 预配 API 进行更改，以确保它们反映在生成的文件中。

自定义预配基础结构

所有 AspireAzure 资源都是 AzureProvisioningResource 类型的子类。 这类型通过提供用于配置 Azure 资源的流畅 API 来允许自定义生成的 Bicep - ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API。 例如，你可以配置 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.Provisioning 自定义。

使用现有的 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 的替代方法可改为添加连接字符串，其中 AppHost 使用配置解析连接信息。 若要将连接添加到现有 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...

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

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

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

添加 Azure 应用配置模拟器资源

Microsoft为希望对Azure应用配置服务进行本地轻量实现以便编码和测试的Azure开发人员提供Azure应用配置模拟器。 在 Aspire 中添加资源时，可以通过调用 RunAsEmulator 方法来使用此模拟器。

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Azure应用配置模拟器未在本地计算机上安装。 相反，可以将其作为容器进行访问 Aspire 。 该方法 RunAsEmulator 在 AppHost 开始使用 azure-app-configuration/app-configuration-emulator 映像时创建并启动容器。 有关详细信息，请参阅 容器资源生命周期。

配置 Azure 应用配置模拟器容器

容器资源可以使用各种配置。 例如，可以配置容器的端口、环境变量、 生存期等。

配置 Azure 应用配置仿真器的主机端口

默认情况下， Aspire 为模拟器容器分配随机主机端口。 如果要使用特定端口，请对方法提供的 RunAsEmulator 容器资源生成器进行链式调用，如以下示例所示：

var builder = DistributedApplication.CreateBuilder(args);

var appConfig = builder.AddAzureAppConfiguration("config")
                     .RunAsEmulator(
                         emulator =>
                         {
                             emulator.WithHostPort(28000);
                         });

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

前面的代码将仿真器容器的端点配置为在端口 28000 上侦听。

使用持久性生命周期配置 Azure 应用配置仿真器

若要配置具有持久生存期的模拟器容器，请在模拟器容器资源上调用 WithLifetime 该方法并传递 ContainerLifetime.Persistent：

var builder = DistributedApplication.CreateBuilder(args);

var appConfig = builder.AddAzureAppConfiguration("config")
                     .RunAsEmulator(
                         emulator =>
                         {
                             emulator.WithLifetime(ContainerLifetime.Persistent);
                         });

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

有关详细信息，请参阅 容器资源生存期。

使用数据卷配置 Azure 应用配置模拟器

若要向 Azure 应用配置模拟器资源添加数据卷，请在该模拟器资源上调用 WithDataVolume 方法。

var builder = DistributedApplication.CreateBuilder(args);

var appConfig = builder.AddAzureAppConfiguration("config")
                       .RunAsEmulator(
                           emulator =>
                           {
                               emulator.WithDataVolume();
                           });

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

数据卷用于在容器的生命周期之外保留模拟器数据。 数据卷挂载在模拟器容器的/data路径中，且如果未提供name参数，则其名称会根据应用程序和资源名称自动生成。 有关数据卷的详细信息，以及为什么首选它们而不是绑定装载的详细信息，请参阅 Docker 文档：卷。

配置Azure应用配置模拟器，使用绑定挂载数据

若要将数据绑定装载添加到 Azure 应用配置模拟器资源，请调用 WithDataBindMount 方法。

var builder = DistributedApplication.CreateBuilder(args);

var appConfig = builder.AddAzureAppConfiguration("config")
                       .RunAsEmulator(
                           emulator =>
                           {
                               emulator.WithDataBindMount("../Emulator/Data");
                           });

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

数据绑定装载依赖于主机的文件系统在容器重启时保留模拟器数据。 数据绑定装载装载在 ../Emulator/Data 主机上相对于仿真器容器中的 AppHost 目录 （IDistributedApplicationBuilder.AppHostDirectory） 的路径上装载。 有关数据绑定装载的详细信息，请参阅 Docker 文档：绑定装载。

Client 集成

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

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

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

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

builder.AddAzureAppConfiguration(connectionName: "config");

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

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

使用功能标志

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

dotnet add package Microsoft.FeatureManagement

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

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

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 功能管理。

配置

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

使用连接字符串

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

builder.AddAzureAppConfiguration("config");

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

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

使用配置提供器

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

可观测性和遥测

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

伐木业

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

• Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh

跟踪

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

指标

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

另请参阅

• Azure 应用配置文档
• Aspire 集成概述
• Aspire Azure 集成概述
• Aspire GitHub 存储库