教程：在 ASP.NET Web 应用程序 (.NET Framework) 中使用动态配置

2025-04-22

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

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

设置 ASP.NET Web 应用程序，使其能够更新配置以响应应用程序配置存储区中的更改。
将请求中的最新配置注入到您的应用程序中。

先决条件

具有活动订阅的 Azure 帐户。免费创建一个。
应用程序配置存储区。创建存储区。
Visual Studio
.NET Framework 4.7.2 或更高版本

添加键值

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

密钥	价值
TestApp：Settings：BackgroundColor	白
TestApp：Settings：FontColor	黑色
TestApp：Settings：FontSize	40
TestApp：Settings：Message	Azure 应用配置的数据

创建 ASP.NET Web 应用程序

启动 Visual Studio 并选择“创建新项目”。
从项目模板列表中选择带有 C# 的 ASP.NET Web 应用程序 (.NET Framework)，然后按“下一步” 。
在配置新项目中，输入项目名称。在“Framework”下，选择“.NET Framework 4.7.2”或更高版本。按“创建”。
在“创建新的 ASP.NET Web 应用程序”中，选择“Web Forms” 。按“创建”。

从应用配置重载数据

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

打开 Global.asax.cs 文件并添加以下命名空间。

Microsoft Entra ID（推荐）
连接字符串

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

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

将以下静态成员变量添加到 Global 类。

public static IConfiguration Configuration;
private static IConfigurationRefresher _configurationRefresher;

将 Application_Start 方法添加到 Global 类。如果方法已存在，则向其添加以下代码。

Microsoft Entra ID（推荐）
连接字符串

protected void Application_Start(object sender, EventArgs e)
{
    ConfigurationBuilder 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(new TimeSpan(0, 5, 0));
               });
        _configurationRefresher = options.GetRefresher();
    });

    Configuration = builder.Build();
}

protected void Application_Start(object sender, EventArgs e)
{
    ConfigurationBuilder 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(new TimeSpan(0, 5, 0));
               });
        _configurationRefresher = options.GetRefresher();
    });

    Configuration = builder.Build();
}

Application_Start 方法在向 Web 应用程序发出第一个请求时被调用。它在应用程序的生命周期内仅调用一次。因此，它是初始化 IConfiguration 对象并从应用程序配置加载数据的好地方。

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

SetRefreshInterval 方法指定在向应用配置发出新请求以检查配置是否发生任何更改之前必须经过的最短时间。在此示例中，替代默认的过期时间（30 秒），改为指定一个 5 分钟的时间。这会减少对应用程序配置存储发出的潜在请求数。

将 Application_BeginRequest 方法添加到 Global 类。如果方法已存在，则向其添加以下代码。
```
protected void Application_BeginRequest(object sender, EventArgs e)
{
    _ = _configurationRefresher.TryRefreshAsync();
}
```
单独调用 ConfigureRefresh 方法不会自动刷新配置。在每个请求开始时调用 TryRefreshAsync 方法以发出刷新信号。此设计可确保应用程序仅在主动接收请求时向应用程序配置发送请求。

在配置的刷新间隔过去之前调用 TryRefreshAsync 是一个空操作，因此它的性能影响很小。向应用程序配置发出请求时，由于无需等待任务，因此将异步刷新配置，而不会阻止当前请求的执行。当前请求可能无法获得更新的配置值，但后续请求会获得。

如果调用 TryRefreshAsync 因任何原因而失败，应用程序也将继续使用缓存的配置。当配置的刷新间隔再次过去，并且应用程序的新请求再次触发 TryRefreshAsync 调用时，将进行另一次尝试。

使用最新的配置数据

打开 Default.aspx 并将其内容替换为以下标记。确保 Inherits 属性与应用程序的命名空间和类名匹配。

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Default.aspx.cs" Inherits="WebFormApp.Default" %>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title>Azure App Configuration Web Forms Demo</title>
</head>
<body id="body" runat="server">
    <form id="form1" runat="server">
        <div style="text-align: center">
            <asp:Label ID="message" runat="server" />
        </div>
    </form>
</body>
</html>

打开 Default.aspx.cs 并使用以下代码更新它。

using System;
using System.Web.UI.WebControls;

namespace WebFormApp
{
    public partial class Default : System.Web.UI.Page
    {
        protected void Page_Load(object sender, EventArgs e)
        {
            // Read configuration from the IConfiguration object loaded from Azure App Configuration
            string messageText = Global.Configuration["TestApp:Settings:Message"] ?? "Please add the key \"TestApp:Settings:Message\" in your Azure App Configuration store.";
            string messageFontSize = Global.Configuration["TestApp:Settings:FontSize"] ?? "20";
            string messageFontColor = Global.Configuration["TestApp:Settings:FontColor"] ?? "Black";
            string backgroundColor = Global.Configuration["TestApp:Settings:BackgroundColor"] ?? "White";

            message.Text = messageText;
            message.Font.Size = FontUnit.Point(int.Parse(messageFontSize));
            message.ForeColor = System.Drawing.Color.FromName(messageFontColor);
            body.Attributes["bgcolor"] = backgroundColor;
        }
    }
}

生成并运行应用程序

设置环境变量。
- 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”生成并运行 Web 应用程序。
在 Azure 门户中，导航到应用程序配置存储区的“配置资源管理器”，并更新以下键的值。

密钥价值

TestApp：Settings：BackgroundColor 绿色

TestApp：Settings：FontColor LightGray

TestApp：Settings：Message Azure 应用配置中的数据 - 现可实时更新！
刷新浏览器页面，查看新的配置设置。可能需要多次刷新才能反映更改，或者将刷新间隔更改为小于 5 分钟。

密钥	价值
TestApp：Settings：BackgroundColor	绿色
TestApp：Settings：FontColor	LightGray
TestApp：Settings：Message	Azure 应用配置中的数据 - 现可实时更新！

注释

本教程中使用的示例代码可从 Azure 应用程序配置 GitHub 存储库下载。

清理资源

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

重要

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

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

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

后续步骤

在本教程中，你使得 ASP.NET Web Forms 应用程序能够从应用程序配置中动态刷新配置设置。要了解如何在 .NET Framework 应用中启用动态配置，请继续阅读下一教程：

在 .NET Framework 应用中实现动态配置

若要了解如何使用 Azure 托管标识来简化对应用程序配置的访问，请继续学习下一篇教程：

托管标识集成

通过