教學課程: 在 ASP.NET Core 應用程式中使用動態設定

發行項
04/12/2024

此教學課程說明如何在 ASP.NET Core 應用程式中啟用動態設定更新。本文會以快速入門中介紹的 Web 應用程式作為基礎。您的應用程式會利用應用程式組態提供者程式庫，以取得其內建的設定快取和重新整理功能。繼續進行之前，請先完成使用應用程式設定建立 ASP.NET Core 應用程式。

在本教學課程中，您會了解如何：

設定您的應用程式以使其在應用程式組態存放區發生變更時更新其設定。
在您的應用程式中插入最新的設定。

必要條件

完成快速入門：使用應用程式組態建立 ASP.NET Core 應用程式。

新增 Sentinel 金鑰

「Sentinel 金鑰」是您完成所有其他金鑰變更之後才更新的金鑰。您的應用程式會監視 Sentinel 金鑰。偵測到變更時，您的應用程式會重新整理所有設定值。相較於監視所有金鑰是否變更，此方法有助於確保應用程式中設定的一致性，並減少對您應用程式組態存放區提出的整體要求數目。

在 Azure 入口網站中，開啟您的應用程式組態存放區，然後選取 [組態總管] > [建立] > [索引鍵/值]。
針對 [金鑰]，請輸入 TestApp:Settings:Sentinel。針對 [值]，輸入 1。請將 [標籤] 和 [內容類型] 保留空白。
選取套用。

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

開啟 Program.cs，並更新您先前在快速入門期間新增的 AddAzureAppConfiguration 方法。

.NET 6.0+
.NET Core 3.x

// Load configuration from Azure App Configuration
builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(connectionString)
           // Load all keys that start with `TestApp:` and have no label
           .Select("TestApp:*", LabelFilter.Null)
           // Configure to reload configuration if the registered sentinel key is modified
           .ConfigureRefresh(refreshOptions =>
                refreshOptions.Register("TestApp:Settings:Sentinel", refreshAll: true));
});

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureAppConfiguration(config =>
            {
                //Retrieve the Connection String from the secrets manager
                IConfiguration settings = config.Build();
                string connectionString = settings.GetConnectionString("AppConfig");

                // Load configuration from Azure App Configuration
                config.AddAzureAppConfiguration(options =>
                {
                    options.Connect(connectionString)
                           // Load all keys that start with `TestApp:` and have no label
                           .Select("TestApp:*", LabelFilter.Null)
                           // Configure to reload configuration if the registered sentinel key is modified
                           .ConfigureRefresh(refreshOptions =>
                                refreshOptions.Register("TestApp:Settings:Sentinel", refreshAll: true));
                });
            });

            webBuilder.UseStartup<Startup>();
        });

Select 方法可用來載入索引鍵名稱是以 TestApp: 開頭且「沒有標籤」的所有索引鍵/值。您可以多次呼叫 Select 方法，以載入具有不同前置詞或標籤的設定。如果您與多個應用程式共用一個應用程式組態存放區，此方法有助於只載入與您目前應用程式相關的設定，而不是從存放區載入所有內容。

在 ConfigureRefresh 方法中，您會在應用程式組態存放區中註冊想要監視變更的索引鍵。 Register 方法的 refreshAll 參數指出如果已註冊的索引鍵變更，您透過 Select 方法指定的所有設定都會重新載入。

提示

您可以新增對 refreshOptions.SetCacheExpiration 方法的呼叫，以指定設定重新整理之間的最短時間。在此範例中，您必須使用 30 秒的預設值。如果您需要減少對應用程式組態存放區提出的要求數目，請調整為較高的值。

將 Azure 應用程式組態中介軟體新增至應用程式的服務集合。

.NET 6.0+
.NET Core 3.x

使用下列程式碼更新 Program.cs。

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

builder.Services.AddRazorPages();

// Add Azure App Configuration middleware to the container of services.
builder.Services.AddAzureAppConfiguration();

// Bind configuration "TestApp:Settings" section to the Settings object
builder.Services.Configure<Settings>(builder.Configuration.GetSection("TestApp:Settings"));

var app = builder.Build();

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

開啟 Startup.cs，並更新 ConfigureServices 方法。

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages();

    // Add Azure App Configuration middleware to the container of services.
    services.AddAzureAppConfiguration();

    // Bind configuration "TestApp:Settings" section to the Settings object
    services.Configure<Settings>(Configuration.GetSection("TestApp:Settings"));
}

呼叫 UseAzureAppConfiguration 方法。這可讓您的應用程式使用應用程式設定中介軟體來為您自動更新設定。

.NET 6.0+
.NET Core 3.x

使用下列程式碼更新 Program.cs。

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

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

// Use Azure App Configuration middleware for dynamic configuration refresh.
app.UseAzureAppConfiguration();

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

更新 Startup.cs 中的 Configure 方法。

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    // Use Azure App Configuration middleware for dynamic configuration refresh.
    app.UseAzureAppConfiguration();

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

您已設定應用程式，以在快速入門期間使用 ASP.NET Core 中的選項模式。從應用程式組態更新應用程式的底層設定時，會自動更新透過 IOptionsSnapshot<T> 取得的強類型 Settings 物件。請注意，如果想要動態設定更新，就不應該使用 IOptions<T>，因為它不會在應用程式啟動之後讀取設定資料。

要求驅動的設定重新整理

設定重新整理是由對您 Web 應用程式的連入要求所觸發。如果您的應用程式閒置，則不會發生重新整理。當您的應用程式作用中時，應用程式組態中介軟體會監視 Sentinel 金鑰，或是您在 ConfigureRefresh 呼叫中註冊以重新整理的任何其他金鑰。中介軟體會針對對應用程式的每個傳入要求觸發。不過，中介軟體只會在過了您設定的快取到期時間時，才會傳送要求來檢查應用程式設定中的值。

如果對應用程式組態的變更偵測要求失敗，您的應用程式會繼續使用快取的設定。在您的應用程式有新的傳入要求時，將會定期嘗試檢查變更。
相對於對您應用程式傳入要求的處理，系統會以非同步方式進行設定重新整理。其將不會封鎖已觸發重新整理的傳入要求或使其變慢。觸發重新整理的要求可能不會取得更新的設定值，但後續的要求將會取得新的設定值。
若要確保已觸發中介軟體，請儘早在要求管線中呼叫 app.UseAzureAppConfiguration() 方法，這樣另一個中介軟體就不會在您應用程式中加以略過。

於本機建置並執行應用程式

若要使用 .NET Core CLI 來建置應用程式，請在命令殼層中執行下列命令：
```
    dotnet build
```
建置成功完成後，請執行下列命令以在本機執行 Web 應用程式：
```
    dotnet run
```
開啟瀏覽器視窗，然後移至 dotnet run 輸出中所顯示的 URL。
登入 Azure 入口網站。選取 [所有資源]，然後選取您在快速入門中建立的應用程式組態存放區。

選取 [組態總管]，然後更新下列索引鍵的值。最後，請記得更新 Sentinel 金鑰。

機碼	值
TestApp:Settings:BackgroundColor	green
TestApp:Settings:FontColor	lightGray
TestApp:Settings:Message	Azure 應用程式設定的值 - 現在可以即時更新了！
TestApp:Settings:Sentinel	2

重新整理瀏覽器數次。當快取在 30 秒後過期後，此頁面即會顯示更新後的內容。

記錄和監視

記錄會在設定重新整理時輸出，並包含從應用程式組態存放區擷取的索引鍵值和對應用程式所做的設定變更的詳細資訊。

叫用 services.AddAzureAppConfiguration() 時，會自動新增預設 ILoggerFactory。應用程式組態提供者會使用此 ILoggerFactory 來建立 ILogger 的執行個體，以輸出這些記錄。 ASP.NET Core 預設會使用 ILogger 進行記錄，因此您不需要進行額外的程式代碼變更，即可啟用應用程式組態提供者的記錄。

記錄會以不同的記錄層級輸出。預設層級是 Information。

記錄層級	描述
偵錯	記錄會包含應用程式監視的索引鍵/值索引鍵和標籤，以取得來自應用程式組態存放區的變更。此資訊也包含索引鍵/值與應用程式已載入的內容相比是否有所變更。如果設定變更未如預期般發生，請啟用此層級的記錄，以針對您的應用程式進行疑難排解。
資訊	記錄包含設定重新整理期間更新的組態設定金鑰。組態設定的值會從記錄中省略，以避免洩漏敏感資料。您可以監視此層級的記錄，以確保應用程式會取得預期的設定變更。
警告	記錄包括設定重新整理期間所發生的失敗和例外狀況。可以忽略偶爾的發生，因為設定提供者會繼續使用快取的資料，並在下次嘗試重新整理設定。您可以監視此層級的記錄，以取得可能表示潛在問題的重複警告。例如，您已輪替連接字串，但忘記更新應用程式。

您可以將下列範例新增至您的 appsettings.json 檔案，以在 Debug 記錄層級啟用記錄。此範例也適用於所有其他記錄層級。

"Logging": {
    "LogLevel": {
        "Microsoft.Extensions.Configuration.AzureAppConfiguration": "Debug"
    }
}

記錄類別是 Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh，出現在每個記錄檔之前。以下是每個記錄層級的一些範例記錄:

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

info: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
    Setting updated. Key:'ExampleKey'

warn: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
    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'

使用 ILogger 是 ASP.NET 應用程式中慣用的方法，如果 ILoggerFactory 的執行個體存在，則會優先作為記錄來源。不過，如果 ILoggerFactory 無法使用，您也可以透過 .NET Core 應用程式的指示來啟用和設定記錄。如需詳細資訊，請參閱 .NET Core 和 ASP.NET Core 中的記錄。

注意

如果使用下列任何套件的 6.0.0 版或更新版本，即可使用記錄。

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

清除資源

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

重要

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

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

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

下一步

在本教學課程中，您已啟用 ASP.NET Core Web 應用程式，以動態方式從應用程式組態重新整理組態設定。若要了解如何使用 Azure 受控服務識別來簡化對應用程式組態的存取，請繼續進行下一個教學課程。

使用受控識別存取應用程式組態