教程：在 .NET 应用中使用动态配置

项目
07/15/2024

应用配置 .NET 提供程序库支持按需更新配置，不需让应用程序重启。本教程演示如何在代码中实现动态配置更新。它建立在快速入门中介绍的应用之上。在继续操作之前，应先完成使用应用程序配置创建 .NET 应用。

你可以使用任何代码编辑器执行本教程中的步骤。 Visual Studio Code 是 Windows、macOS 和 Linux 平台上提供的一个卓越选项。

在本教程中，你将了解如何执行以下操作：

设置 .NET 应用，使其能够更新配置以响应应用程序配置存储中的更改。
在应用程序中使用最新配置。

先决条件

如果没有 Azure 试用版订阅，请在开始前创建 Azure 试用版订阅。

完成快速入门使用应用程序配置创建 .NET 应用。

活动驱动的配置刷新

打开 Program.cs，使用以下代码更新该文件。

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;

IConfiguration _configuration = null;
IConfigurationRefresher _refresher = null;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    options.Connect(Environment.GetEnvironmentVariable("ConnectionString"))
            .ConfigureRefresh(refresh =>
            {
                refresh.Register("TestApp:Settings:Message")
                       .SetCacheExpiration(TimeSpan.FromSeconds(10));
            });

    _refresher = options.GetRefresher();
});

_configuration = builder.Build();

Console.WriteLine(_configuration["TestApp:Settings:Message"] ?? "Hello world!");

// Wait for the user to press Enter
Console.ReadLine();

if (_refresher != null)
{
    await _refresher.TryRefreshAsync();
    Console.WriteLine(_configuration["TestApp:Settings:Message"] ?? "Hello world!");

}

在 ConfigureRefresh 方法中，应用程序配置存储中的密钥注册用于监视更改。 Register 方法具有一个可选的布尔参数 refreshAll，该参数可用于指示在注册的密钥发生更改时是否应刷新所有配置值。在此示例中，只会刷新密钥 TestApp:Settings:Message。 SetCacheExpiration 方法指定向应用程序配发出新请求以检查任何配置更改之前必须经过的最小时间。在此示例中，替代默认的过期时间（30 秒），改为指定一个 10 秒的时间用于演示目的。

单独调用 ConfigureRefresh 方法不会自动刷新配置。从接口 IConfigurationRefresher 调用 TryRefreshAsync 方法以触发刷新。此设计旨在避免请求发送到应用配置（即使应用程序处于空闲状态）。你需要在你认为应用程序处于活动状态的位置包含 TryRefreshAsync 调用。例如，可以是在处理传入消息、订单或复杂任务迭代时。如果应用程序始终处于活动状态，则也可以是在计时器中。在此示例中，每次按 Enter 键时都会调用 TryRefreshAsync。即使调用 TryRefreshAsync 因任何原因而失败，应用程序也会继续使用缓存的配置。当配置的缓存过期时间已过，并且应用程序活动再次触发 TryRefreshAsync 调用时，将进行另一次尝试。在配置的缓存过期时间过去之前调用 TryRefreshAsync 是一个空操作，因此，即使频繁调用，它的性能影响也很小。

使用依赖项注入进行配置刷新

在前面的代码中，你将手动保存 IConfigurationRefresher 实例以调用 TryRefreshAsync。或者，如果使用依赖项注入来解析服务，则可以参考以下步骤。

通过在 IServiceCollection 上调用 AddAzureAppConfiguration 来注册所需的应用程序配置服务。

将以下代码添加到 Program.cs。

// Existing code in Program.cs
// ... ...

// Add Azure App Configuration services to IServiceCollection
builder.Services.AddAzureAppConfiguration();

通过解析服务集合中 IConfigurationRefresherProvider 的实例并在每个刷新器上调用 TryRefreshAsync 来刷新配置。

class SampleConfigRefresher
{
    private readonly IEnumerable<IConfigurationRefresher> _refreshers = null;

    public SampleConfigRefresher(IConfigurationRefresherProvider refresherProvider)
    {
        _refreshers = refresherProvider.Refreshers;
    }

    public async Task RefreshConfiguration()
    {
        foreach (var refresher in _refreshers)
        {
            _ = refresher.TryRefreshAsync();
        }
    }
}

在本地生成并运行应用

设置名为“ConnectionString”的环境变量，并将其设置为应用程序配置存储区的访问密钥。如果使用 Windows 命令提示符，则请运行以下命令并重启命令提示符，这样更改才会生效：
```
 setx ConnectionString "connection-string-of-your-app-configuration-store"
```
如果使用 Windows PowerShell，请运行以下命令：
```
 $Env:ConnectionString = "connection-string-of-your-app-configuration-store"
```
如果使用 macOS 或 Linux，则请运行以下命令：
```
 export ConnectionString='connection-string-of-your-app-configuration-store'
```
运行以下命令以生成控制台应用：
```
 dotnet build
```
生成成功完成后，请运行以下命令以在本地运行应用：
```
 dotnet run
```
登录 Azure 门户。选择“所有资源”，然后选择在快速入门中创建的应用程序配置存储区实例。
选择“配置资源管理器” 并更新以下键的值：

密钥值

TestApp:Settings:Message Azure 应用配置的数据 - 已更新
按 Enter 键触发刷新并在命令提示符或 PowerShell 窗口中输出更新的值。

注意

由于在指定刷新操作的配置时已使用 SetCacheExpiration 方法将缓存过期时间设置为 10 秒，因此只有在针对该设置进行刷新并已过去至少 10 秒以后，才会更新此配置设置的值。

密钥	值
TestApp:Settings:Message	Azure 应用配置的数据 - 已更新

日志记录和监视

日志在配置刷新时输出，并包含有关从应用程序配置存储和对应用程序所做的配置更改中检索的键值的详细信息。如果有 ASP.NET Core 应用程序，请参阅以下说明，了解 ASP.NET Core 中的日志记录和监视。否则，可以按使用 Azure SDK 进行日志记录的相关说明启用日志记录。

日志在不同的事件级别输出。默认级别为 Informational。

事件级别	描述
详细	日志包括你的应用程序对应用程序配置存储中的更改监视的键值的键和标签。该信息还包括与应用程序已加载的键值相比，这些键值是否已更改。在此级别启用日志，以便在配置更改未按预期发生时对应用程序进行故障排除。
信息	日志包括配置刷新期间更新的配置设置的键。日志中省略配置设置的值，以避免泄露敏感数据。可以在此级别监视日志，以确保应用程序获取预期的配置更改。
警告	日志包括配置刷新期间发生的失败和异常。可以忽略偶尔发生的事件，因为配置提供程序将继续使用缓存的数据，并尝试下次刷新配置。可以在此级别监视日志，以查找可能指示潜在问题的重复警告。例如，你轮换了连接字符串，但忘记了更新应用程序。

可以通过指定 EventLevel.Verbose 参数在 Verbose 事件级别启用日志记录，如以下示例中所示。这些说明也适用于所有其他事件级别。此示例还仅为 Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh 类别启用日志。

using var listener = new AzureEventSourceListener((eventData, text) =>
{
    if (eventData.EventSource.Name == "Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh")
    {
        Console.WriteLine("[{1}] {0}: {2}", eventData.EventSource.Name, eventData.Level, text);
    }
}, EventLevel.Verbose);

日志记录类别是 Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh，它显示在每个日志之前。下面是每个事件级别的一些示例日志：

[Verbose] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
Key-value read from App Configuration. Change:'Modified' Key:'ExampleKey' Label:'ExampleLabel' Endpoint:'https://examplestore.azconfig.io'

[Informational] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
Setting updated. Key:'ExampleKey'

[Warning] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
A refresh operation failed while resolving a Key Vault reference.
Key vault error. ErrorCode:'SecretNotFound' Key:'ExampleKey' Label:'ExampleLabel' Etag:'6LaqgBQM9C_Do2XyZa2gAIfj_ArpT52-xWwDSLb2hDo' SecretIdentifier:'https://examplevault.vault.azure.cn/secrets/ExampleSecret'

注意

如果使用的是以下任何包的 6.0.0 或更高版本，则可以使用日志记录。

Microsoft.Extensions.Configuration.AzureAppConfiguration
Microsoft.Azure.AppConfiguration.AspNetCore
Microsoft.Azure.AppConfiguration.Functions.Worker

清理资源

如果不想继续使用本文中创建的资源，请删除此处创建的资源组以避免产生费用。

重要

删除资源组的操作不可逆。将永久删除资源组以及其中的所有资源。请确保不要意外删除错误的资源组或资源。如果在包含要保留的其他资源的资源组中创建了本文的资源，请从相应的窗格中单独删除每个资源，而不是删除该资源组。

登录到 Azure 门户，然后选择“资源组”。
在“按名称筛选”框中，输入资源组的名称。
在结果列表中，选择资源组名称以查看概述。
选择“删除资源组”。
系统会要求确认是否删除资源组。重新键入资源组的名称进行确认，然后选择“删除” 。

片刻之后，将会删除该资源组及其所有资源。

后续步骤

在本教程中，你已启用 .NET 应用，可通过应用程序配置动态刷新配置设置。若要了解如何使用 Azure 托管标识来简化对应用程序配置的访问，请继续学习下一篇教程。

托管标识集成