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

應用程式組態 .NET 提供者連結庫支持視需要更新設定，而不會造成應用程式重新啟動。本教學課程說明如何在程式碼中實作動態設定更新。其以快速入門中介紹的應用程式為基礎。您應該先完成使用應用程式組態建立 .NET 應用程式，再繼續進行。

您可以使用任何程式碼編輯器來進行本教學課程中的步驟。 Windows、macOS 及 Linux 平台上都有提供的 Visual Studio Code 是一個絕佳的選項。

在本教學課程中，您將瞭解如何：

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

先決條件

如果您沒有 Azure 帳戶，請在開始之前建立免費帳戶。

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

活動驅動設定的重新整理

開啟 Program.cs ，並使用下列程式代碼更新檔案。您可以使用 Microsoft Entra ID (建議) 或連接字串連線至應用程式組態。下列代碼段示範如何使用 Microsoft Entra ID。

您可以使用 DefaultAzureCredential 來向應用程式組態存放區進行驗證。完成必要條件中所列的快速入門後，您即已為認證指派應用程式組態資料讀者角色。

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

IConfiguration _configuration = null;
IConfigurationRefresher _refresher = null;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    string endpoint = Environment.GetEnvironmentVariable("Endpoint"); 
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())            
           // Load the key-value with key "TestApp:Settings:Message" and no label
           .Select("TestApp:Settings:Message")
           // Reload configuration if any selected key-values have changed.
           .ConfigureRefresh(refresh =>
           {
               refresh.RegisterAll()
                      .SetRefreshInterval(TimeSpan.FromSeconds(10));
           })

    _refresher = options.GetRefresher();
});

_configuration = builder.Build();

Console.WriteLine(_configuration["TestApp:Settings:Message"] ?? "Hello world!");

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

if (_refresher != null)
{
    await _refresher.TryRefreshAsync();
    Console.WriteLine(_configuration["TestApp:Settings:Message"] ?? "Hello world!");

}

在 ConfigureRefresh 方法內，您可以呼叫 RegisterAll 方法來指示應用程式組態提供者在偵測到任何所選索引鍵/值變更時重載整個組態（在此案例中，只要 TestApp：Settings：Message）。如需監視組態變更的詳細資訊，請參閱設定重新整理的最佳做法。

在傳送新的要求來檢查應用程式組態中是否有任何設定更改之前，SetRefreshInterval 方法會指定必須經過的最短時間。在此範例中，您會修改 30 秒的預設到期時間，改為 10 秒，以示範用途。

單獨呼叫 ConfigureRefresh 方法不會導致設定自動重新整理。您可以從介面 TryRefreshAsync 呼叫 IConfigurationRefresher 方法來觸發重新整理。此設計是為避免當您的應用程式閒置時，傳送要求至應用程式組態。當您認為應用程式處於活動狀態時，您需要包含 TryRefreshAsync 呼叫。例如，它可能發生在您處理收到的訊息、訂單或複雜任務的重複迭代時。如果您的應用程式隨時都在使用中，其也可以作為計時器使用。在這裡範例中，您每次按下 Enter 鍵時都會呼叫 TryRefreshAsync 。即使呼叫 TryRefreshAsync 因任何原因而失敗，您的應用程式仍會繼續使用快取的組態。當設定的重新整理間隔過後，若您的應用程式活動再次觸發 TryRefreshAsync 呼叫時，就會進行另一次嘗試。在設定的重新整理間隔過去之前，呼叫 TryRefreshAsync 是不可操作的，因此即使頻繁呼叫，其對效能的影響也是最小的。

使用依賴注入進行配置刷新

在先前的程式代碼中，您會手動儲存實例 IConfigurationRefresher 以叫用 TryRefreshAsync。或者，如果您使用依賴注入來解析您的服務，您可以參考下列步驟。

在 AddAzureAppConfiguration 上調用 IServiceCollection，來註冊必要的應用程式組態服務。

新增下列程式代碼以 Program.cs。

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

// Add Azure App Configuration services to IServiceCollection
builder.Services.AddAzureAppConfiguration();

藉由解析服務集合中的 IConfigurationRefresherProvider 執行個體，並在每個重新整理程式上叫用 TryRefreshAsync，以重新整理組態。

class SampleConfigRefresher
{
    private readonly IEnumerable<IConfigurationRefresher> _refreshers = null;

    public SampleConfigRefresher(IConfigurationRefresherProvider refresherProvider)
    {
        _refreshers = refresherProvider.Refreshers;
    }

    public async Task RefreshConfiguration()
    {
        foreach (var refresher in _refreshers)
        {
            _ = refresher.TryRefreshAsync();
        }
    }
}

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

將名為 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>'
```
執行下列命令來建置主控台應用程式：
```
 dotnet build
```
建置成功完成後，請執行下列命令以於本機執行應用程式：
```
 dotnet run
```
登入 Azure 入口網站。選取 [所有資源]，然後選取您在快速入門中建立的應用程式組態存放區實例。
選取 [組態總管]，並更新下列機碼的值：

鑰匙價值觀

TestApp：設定：訊息來自 Azure 應用程式設定的數據 - 已更新
按 Enter 鍵以觸發重新整理，並在 [命令提示字元] 或 [PowerShell] 視窗中列印更新的值。

備註

由於重新整理間隔是在指定重新整理作業的組態時使用 SetRefreshInterval 方法設定為10秒，因此只有在該設定上次重新整理之後至少經過10秒時，才會更新組態設定的值。

鑰匙	價值觀
TestApp：設定：訊息	來自 Azure 應用程式設定的數據 - 已更新

記錄和監視

記錄會在設定重新整理時輸出，並包含從應用程式組態存放區擷取的索引鍵值和對應用程式所做的設定變更的詳細資訊。如果您有 ASP.NET Core 應用程式，請參閱 ASP.NET Core 中的記錄和監視指示。否則，您可以使用使用 Azure SDK 進行記錄的指示來啟用記錄。

記錄檔會以不同的事件層級輸出。預設層級是 Informational。

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

您可以藉由指定 Verbose 參數，在 EventLevel.Verbose 事件層級啟用記錄，如下列範例所示。這些指示也適用於所有其他事件層級。此範例也僅啟用 Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh 類別的記錄。

using var listener = new AzureEventSourceListener((eventData, text) =>
{
    if (eventData.EventSource.Name == "Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh")
    {
        Console.WriteLine("[{1}] {0}: {2}", eventData.EventSource.Name, eventData.Level, text);
    }
}, EventLevel.Verbose);

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

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

[Informational] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
Setting updated. Key:'ExampleKey'

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

備註

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

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

清理資源

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

這很重要

刪除資源群組是無法回復的動作。資源群組和其中的所有資源都將被永久刪除。請確定您不會誤刪錯誤的資源群組或資源。如果您是在包含其他您想保留資源的資源群組中建立本文的資源，則應該從各自的面板中逐一刪除每個資源，而不用刪除整個資源群組。

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

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

後續步驟

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

受控識別整合

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-04-23