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

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

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

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

必要條件

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

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

開啟 Program.cs，並更新 AddAzureAppConfiguration 您在快速入門期間新增的方法。您可以使用 Microsoft Entra ID (建議) 或連接字串連線至應用程式組態。下列代碼段示範如何使用 Microsoft Entra ID。

您可以使用 DefaultAzureCredential 來向應用程式組態存放區進行驗證。完成必要條件中所列的快速入門後，您即已為認證指派應用程式組態資料讀者角色。
```
// Load configuration from Azure App Configuration
builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())
           // Load all keys that start with `TestApp:` and have no label.
           .Select("TestApp:*", LabelFilter.Null)
           // Reload configuration if any selected key-values have changed.
           .ConfigureRefresh(refreshOptions =>
               refreshOptions.RegisterAll());
});
```
Select 方法可用來載入索引鍵名稱是以 TestApp: 開頭且「沒有標籤」的所有索引鍵/值。您可以多次呼叫 Select 方法，以載入具有不同前置詞或標籤的設定。如果您與多個應用程式共用一個應用程式組態存放區，此方法有助於只載入與您目前應用程式相關的設定，而不是從存放區載入所有內容。

在 ConfigureRefresh 方法內，您可以呼叫 RegisterAll 方法，指示應用程式組態提供者在偵測到任何選取的索引鍵/值 (開頭為 TestApp: 且沒有標籤的項目) 有所變更時重新載入整個設定。如需監視組態變更的詳細資訊，請參閱設定重新整理的最佳做法。

提示

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

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

使用下列程式碼更新 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
// ... ...

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

使用下列程式碼更新 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
// ... ...

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

由請求驅動的設定重新整理

設定重新整理是由對您 Web 應用程式的連入要求所觸發。如果您的應用程式閒置，則不會發生重新整理。當您的應用程式處於作用中狀態時，應用程式設定中間件會監視您在 ConfigureRefresh 呼叫中註冊以重新整理的任何密鑰。中介軟體會針對對應用程式的每個傳入要求觸發。不過，中間件只會在您設定的重新整理間隔通過時，傳送要求來檢查應用程式組態中的值。

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

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

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

鑰匙值

TestApp:設定:背景顏色綠色

TestApp：設置：FontColor 淺灰色

TestApp：設定：訊息 Azure 應用程式設定的值 - 現在可以即時更新了！
重新整理瀏覽器數次。當重新整理間隔在 30 秒之後經過時，頁面會顯示已更新的內容。

鑰匙	值
TestApp:設定:背景顏色	綠色
TestApp：設置：FontColor	淺灰色
TestApp：設定：訊息	Azure 應用程式設定的值 - 現在可以即時更新了！

記錄和監視

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

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

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

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

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

"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 受控服務識別來簡化對應用程式組態的存取，請繼續進行下一個教學課程。

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

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-21