教學課程：在 ASP.NET Web 應用程式 (.NET Framework) 中使用動態設定

發行項
04/09/2024

來自應用程式組態的資料可以在 .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 應用程式組態的資料
TestApp:Settings:Sentinel	v1

建立 ASP.NET Web 應用程式

啟動 Visual Studio 並選取 [建立新專案]。
從專案範本清單中選取配有 C# 的 [ASP.NET Web 應用程式 (.NET Framework)]，然後按下 [下一步]。
在 [設定您的新專案] 中，輸入專案名稱。在 [架構] 下，選取 [.NET Framework 4.7.2] 或更新版本。按下 [建立]。
在 [建立新的 ASP.NET Web 應用程式] 中，選取 [Web Form]。按下 [建立]。

從應用程式設定重新載入資料

以滑鼠右鍵按一下專案，然後選取 [管理 NuGet 套件]。在 [瀏覽] 索引標籤中，搜尋下列 NuGet 套件最新版本，並新增至您的專案。

Microsoft.Extensions.Configuration.AzureAppConfiguration

開啟 Global.asax.cs 檔案並新增下列命名空間。

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

將下列靜態成員變數新增至 Global 類別。

public static IConfiguration Configuration;
private static IConfigurationRefresher _configurationRefresher;

將 Application_Start 方法新增至 Global 類別。如果該方法已經存在，請將下列程式碼新增至其中。
```
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:*")
                // Configure to reload configuration if the registered key 'TestApp:Settings:Sentinel' is modified.
                .ConfigureRefresh(refresh => 
                {
                    refresh.Register("TestApp:Settings:Sentinel", refreshAll:true)
                           .SetCacheExpiration(new TimeSpan(0, 5, 0));
                });
        _configurationRefresher = options.GetRefresher();
    });

    Configuration = builder.Build();
}
```
將會在第一次要求 Web 應用程式時呼叫 Application_Start 方法。在該應用程式的生命週期中，其方法只會被呼叫一次。因此，其為進行初始化 IConfiguration 物件並從應用程式組態載入資料合適的位置。

在 ConfigureRefresh 方法中，將會註冊應用程式組態存放區內的金鑰以進行變更監視。 Register 方法的 refreshAll 參數表示當註冊金鑰變更時，應該重新整理所有設定值。在此範例中，TestApp:Settings:Sentinel 金鑰是您完成所有其他金鑰變更之後才更新的 Sentinel 金鑰。偵測到變更時，您的應用程式會重新整理所有設定值。與監視所有金鑰的變更相比，此方法有助於確保應用程式中組態的一致性。

對應用程式組態提出新要求檢查任何設定變更之前，SetCacheExpiration 方法會指定在此之前所須經過的最短時間間隔。在此範例中，您會覆寫 30 秒的預設到期時間，並改為指定 5 分鐘的到期時間。其會減少對應用程式組態存放區提出要求的潛在數目。
將 Application_BeginRequest 方法新增至 Global 類別。如果該方法已經存在，請將下列程式碼新增至其中。
```
protected void Application_BeginRequest(object sender, EventArgs e)
{
    _ = _configurationRefresher.TryRefreshAsync();
}
```
單獨呼叫 ConfigureRefresh 方法並不會導致設定自動進行重新整理。您會在每個要求一開始呼叫 TryRefreshAsync 方法來發出重新整理的訊號。此設計可確保您的應用程式只會在主動接收要求時，將要求傳送至應用程式組態。

在設定的快取到期時間結束之前呼叫 TryRefreshAsync，系統不會執行任何作業，因此其對效能的影響極少。當對應用程式組態提出要求時，由於您未等候工作，會以非同步方式重新整理組態，而不會封鎖執行目前的要求。目前的要求可能不會取得更新組態值，但後續的要求將會取得。

若呼叫 TryRefreshAsync 時因任何原因而導致失敗，您的應用程式仍會繼續使用快取設定。當設定快取的到期時間再次結束，且對於應用程式的新要求觸發 TryRefreshAsync 呼叫時，系統將會再進行另一次嘗試。

使用最新的設定資料

開啟 [Default.aspx]，並以下列標記取代其內容。請確定繼承屬性符合您應用程式的命名空間和類別名稱。

<%@ 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;
        }
    }
}

建立和執行應用程式

將名為 ConnectionString 的環境變數設定為在您建立應用程式組態存放區時取得的唯讀金鑰連接字串。

如果您使用 Windows 命令提示字元，請執行下列命令：
```
setx ConnectionString "connection-string-of-your-app-configuration-store"
```
如果您使用 Windows PowerShell，請執行下列命令：
```
$Env:ConnectionString = "connection-string-of-your-app-configuration-store"
```
重新啟動 Visual Studio，以讓變更生效。
按下 [Ctrl+F5] 以組建並執行 Web 應用程式。

在 Azure 入口網站中，流覽至應用程式組態存放區的 [組態總管]，並更新下列金鑰的值。請記得，最後要更新 Sentinel 金鑰 TestApp:Settings:Sentinel。

機碼	值
TestApp:Settings:BackgroundColor	綠色
TestApp:Settings:FontColor	LightGray
TestApp:Settings:Message	Azure 應用程式組態的資料 - 現在可以即時更新了！
TestApp:Settings:Sentinel	v2

重新整理瀏覽器頁面，以查看新的組態設定。您可能需要進行重新整理超過一次，才能反映變更，或將您的快取到期時間變更為少於 5 分鐘。

注意

本教學課程中使用的範例程式碼，可從 Azure 應用程式組態 GitHub 存放庫中下載取得。

清除資源

如果您不想繼續使用本文中建立的資源，請刪除在此處建立的資源群組，以避免產生費用。

重要

刪除資源群組是無法回復的動作。資源群組和其中的所有資源都將被永久刪除。請確定您不會誤刪錯誤的資源群組或資源。如果您是在包含需保留其他資源的資源群組內部，建立本文的資源，則可以從每個資源各自的窗格中個別刪除每個資源，而不必刪除整個資源群組。

登入 Azure 入口網站，然後選取 [資源群組]。
在 [依名稱篩選] 方塊中，輸入您資源群組的名稱。
在結果清單中，選取資源群組名稱以查看概觀。
選取 [刪除資源群組]。
系統將會要求您確認是否刪除資源群組。輸入您資源群組的名稱以進行確認，然後選取 [刪除]。

不久後，系統便會刪除該資源群組及其所有的資源。

下一步

在本教學課程中，您已啟用 ASP.NET Web Forms 應用程式，以動態方式從應用程式組態重新整理組態設定。若要了解如何在 .NET Framework 應用程式啟用動態設定，請繼續進行下一個教學課程：

啟用 .NET Framework 應用程式中的動態設定

如需了解如何使用 Azure 受控識別簡化存取應用程式組態，請繼續進行下一個教學課程：

受控識別整合