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

项目
2025-04-23

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

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

本教程中，您将学习如何：

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

先决条件

如果没有 Azure 帐户，请在开始前创建一个免费帐户。

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

活动驱动的配置刷新

打开 Program.cs ，使用以下代码更新文件。可以使用 Microsoft Entra ID（建议）或连接字符串连接到应用程序配置。以下代码片段演示如何使用 Microsoft Entra ID。

使用 DefaultAzureCredential 向应用程序配置存储区进行身份验证。在完成先决条件中列出的快速入门时，已为凭据分配“应用程序配置数据读取者”角色。

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
using Azure.Identity;

IConfiguration _configuration = null;
IConfigurationRefresher _refresher = null;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    string endpoint = Environment.GetEnvironmentVariable("Endpoint"); 
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())            
           // Load the key-value with key "TestApp:Settings:Message" and no label
           .Select("TestApp:Settings:Message")
           // Reload configuration if any selected key-values have changed.
           .ConfigureRefresh(refresh =>
           {
               refresh.RegisterAll()
                      .SetRefreshInterval(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 该方法中，调用 RegisterAll 该方法以指示应用配置提供程序在检测到任何所选键值更改时重新加载整个配置（在本例中，只需 TestApp：Settings：Message）。有关监视配置更改的详细信息，请参阅配置刷新的最佳做法。

SetRefreshInterval 方法指定在向应用配置发出新请求以检查配置是否发生任何更改之前必须经过的最短时间。在此示例中，替代默认的过期时间（30 秒），改为指定一个 10 秒的时间用于演示目的。

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

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

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

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

将以下代码添加到 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();
        }
    }
}

在本地生成并运行应用

将名为 Endpoint 的环境变量设置为 Azure 门户中应用商店的“概述”下找到的应用程序配置存储区的终结点。

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

密钥价值

测试应用：设置：消息 Azure 应用配置中的数据 - 已更新
按 Enter 键触发刷新并在命令提示符或 PowerShell 窗口中打印更新的值。

注释

由于在为刷新作指定配置时使用 SetRefreshInterval 该方法将刷新间隔设置为 10 秒，因此仅当自上次刷新该设置以来至少经过 10 秒时，才会更新配置设置的值。

密钥	价值
测试应用：设置：消息	Azure 应用配置中的数据 - 已更新

日志记录和监视

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

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

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

可以通过指定Verbose参数在EventLevel.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.net/secrets/ExampleSecret'

注释

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

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

清理资源

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

重要

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

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

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

后续步骤

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

托管标识集成

通过