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

2025-08-04

应用程序配置中的数据可在 .NET Framework 应用中加载为应用设置。有关详细信息，请参阅此快速入门。但是，根据 .NET Framework 的设计，只能在应用重启时刷新应用设置。应用程序配置 .NET 提供程序是一个 .NET Standard 库。它支持动态缓存和刷新配置，而无需重启应用。本教程演示如何在 .NET Framework 控制台应用中实现动态配置更新。

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

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

先决条件

具有活动订阅的 Azure 帐户。创建试用版订阅。
应用配置存储区，如创建存储区的教程所示。
Visual Studio
.NET Framework 4.7.2 或更高版本

添加键值

将以下键值添加到应用程序配置存储区，并让“标签”和“内容类型”保留默认值。有关如何使用 Azure 门户或 CLI 将键值添加到存储区的详细信息，请转到创建键值。

密钥	值
TestApp：Settings：Message	Azure 应用配置的数据

创建 .NET Framework 控制台应用

启动 Visual Studio 并选择“创建新项目”。
在“创建新项目”中，按“控制台”项目类型进行筛选，然后从项目模板列表中选择“控制台应用(.NET Framework)”，语言为 C# 。按“下一步”。
在配置新项目中，输入项目名称。在“Framework”下，选择“.NET Framework 4.7.2”或更高版本。按“创建”。

从应用配置重载数据

右键单击项目，然后选择“管理 NuGet 包” 。在“浏览”选项卡中，搜索以下 NuGet 包的最新版本并将其添加到项目中。
- Microsoft Entra ID （建议）
- 连接字符串
- Microsoft.Extensions.Configuration.AzureAppConfiguration
- Azure.Identity
- Microsoft.Extensions.Configuration.AzureAppConfiguration

打开“Program.cs”并添加以下命名空间。

Microsoft Entra ID （建议）
连接字符串

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

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

添加两个变量来存储与配置相关的对象。

private static IConfiguration _configuration;
private static IConfigurationRefresher _refresher;

更新 Main 方法，以便能用指定的刷新选项连接到应用配置。使用 Microsoft Entra ID（建议）或连接字符串连接到应用配置。

Microsoft Entra ID （建议）
连接字符串

使用 DefaultAzureCredential 向应用程序配置存储区进行身份验证。请按照说明向凭据分配“应用程序配置数据读者”角色。运行应用程序前，请务必留出足够的时间让权限生效。

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

static void Main(string[] args)
{
    var builder = new ConfigurationBuilder();
    builder.AddAzureAppConfiguration(options =>
    {
        string endpoint = Environment.GetEnvironmentVariable("Endpoint"); 
        options.Connect(new Uri(endpoint), new DefaultAzureCredential())
               // Load all keys that start with `TestApp:` and have no label.
               .Select("TestApp:*")
               // Reload configuration if any selected key-values have changed.
               .ConfigureRefresh(refresh =>
               {
                   refresh.RegisterAll()
                          .SetRefreshInterval(TimeSpan.FromSeconds(10));
               });

        _refresher = options.GetRefresher();
    });

    _configuration = builder.Build();
    PrintMessage().Wait();
}

// The rest of existing code in Program.cs
// ... ...

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

static void Main(string[] args)
{
    var builder = new ConfigurationBuilder();
    builder.AddAzureAppConfiguration(options =>
    {
        options.Connect(Environment.GetEnvironmentVariable("ConnectionString"))
               // Load all keys that start with `TestApp:` and have no label.
               .Select("TestApp:*")
               // Reload configuration if any selected key-values have changed.
               .ConfigureRefresh(refresh =>
               {
                   refresh.RegisterAll()
                          .SetRefreshInterval(TimeSpan.FromSeconds(10));
               });

        _refresher = options.GetRefresher();
    });

    _configuration = builder.Build();
    PrintMessage().Wait();
}
// The rest of existing code in Program.cs
// ... ...

在 ConfigureRefresh 方法中，调用 RegisterAll 该方法以指示应用配置提供程序在检测到任何所选键值（以 TestApp 开头且没有标签）发生更改时重新加载整个配置。有关监视配置更改的详细信息，请参阅配置刷新的最佳做法。

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

添加一个名为 PrintMessage() 的方法，该方法触发针对应用程序配置中配置数据的刷新操作。
```
private static async Task PrintMessage()
{
    Console.WriteLine(_configuration["TestApp:Settings:Message"] ?? "Hello world!");

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

    await _refresher.TryRefreshAsync();
    Console.WriteLine(_configuration["TestApp:Settings:Message"] ?? "Hello world!");
}
```
单独调用 ConfigureRefresh 方法不会自动刷新配置。从接口 TryRefreshAsync 调用 IConfigurationRefresher 方法以触发刷新。此设计旨在避免请求发送到应用配置（即使应用程序处于空闲状态）。你可在你认为应用程序处于活动状态的位置包含 TryRefreshAsync 调用。例如，可以是在处理传入消息、订单或复杂任务迭代时。如果应用程序始终处于活动状态，则也可以是在计时器中。在此示例中，按 Enter 键时会调用 TryRefreshAsync。请注意，即使调用 TryRefreshAsync 因任何原因而失败，应用程序也将继续使用缓存的配置。一旦配置的刷新间隔结束并由您的应用程序活动再次触发TryRefreshAsync调用，将会进行新的尝试。在配置的刷新间隔过去之前调用 TryRefreshAsync 是一个空操作，因此即使频繁调用，它的性能影响也很小。

在本地生成并运行应用

设置环境变量。
- Microsoft Entra ID （建议）
- 连接字符串
将名为 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>'
```
将名为 ConnectionString 的环境变量设置为 Azure 门户中存储 Access 设置下找到的只读密钥连接字符串。

如果使用 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>'
```
重启 Visual Studio 以便使所做更改生效。
按 Ctrl+F5 生成并运行控制台应用。
在 Azure 门户中，导航到应用程序配置存储区的“配置资源管理器”，并更新以下键的值。

密钥值

TestApp：Settings：Message Azure 应用配置的数据 - 已更新
回到运行中的应用程序，按 Enter 键触发刷新，并在命令提示符或 PowerShell 窗口中打印更新的值。

注意

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