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

發行項
03/17/2024

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

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

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

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

必要條件

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

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

活動驅動組態重新整理

開啟 Program.cs 檔案，並以下列程式碼更新該檔案。

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

IConfiguration _configuration = null;
IConfigurationRefresher _refresher = null;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    options.Connect(Environment.GetEnvironmentVariable("ConnectionString"))
            .ConfigureRefresh(refresh =>
            {
                refresh.Register("TestApp:Settings:Message")
                       .SetCacheExpiration(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，應用程式組態存放區內的密鑰會註冊以進行變更監視。 Register方法有選擇性的布爾值參數refreshAll，可用來指出如果已註冊的密鑰變更，是否應該重新整理所有組態值。在此範例中，只會重新整理 Key TestApp：設定：Message。方法SetCacheExpiration會指定在提出新要求之前必須經過的最小時間，才能應用程式組態檢查任何組態變更。在此範例中，您會覆寫預設的到期時間為 30 秒，並指定 10 秒的時間，以供示範之用。

ConfigureRefresh單獨呼叫方法並不會讓設定自動重新整理。您可以從介面IConfigurationRefresher呼叫 TryRefreshAsync 方法來觸發重新整理。即使應用程式閑置，此設計也是為了避免傳送至應用程式組態的要求。您會想要包含 TryRefreshAsync 您考慮應用程式作用中的呼叫。例如，當您處理傳入訊息、訂單或複雜工作的反覆專案時，可能是它。如果您的應用程式一直處於作用中狀態，也可能在定時器中。在這裡範例中，您每次按下 Enter 鍵時都會呼叫 TryRefreshAsync 。即使呼叫 TryRefreshAsync 因任何原因而失敗，您的應用程式仍會繼續使用快取的組態。當已設定的快取到期時間經過，且 TryRefreshAsync 呼叫再次由您的應用程式活動觸發時，就會進行另一次嘗試。在設定的快取到期時間經過之前，呼叫 TryRefreshAsync 是無作業，因此其效能影響最小，即使經常呼叫也一樣。

使用相依性插入進行設定重新整理

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

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

將下列程式代碼新增至 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();
        }
    }
}

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

設定名為 ConnectionString 的環境變數，並將其設定為應用程式組態存放區的存取金鑰。如果您使用 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'
```
執行下列命令來建置主控台應用程式：
```
 dotnet build
```
建置成功完成後，請執行下列命令以於本機執行應用程式：
```
 dotnet run
```
登入 Azure 入口網站。選取 [所有資源]，然後選取您在快速入門中建立的應用程式組態存放區執行個體。
選取 [組態總管]，然後更新下列索引鍵的值：

機碼值

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

注意

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

機碼	值
TestApp:Settings:Message	Azure 應用程式設定的值 - 已更新

記錄和監視

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

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

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

您可以藉由指定 EventLevel.Verbose 參數，在事件層級啟用記錄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 應用程式能夠從應用程式組態動態重新整理組態設定。若要了解如何使用 Azure 受控服務識別來簡化對應用程式組態的存取，請繼續進行下一個教學課程。

受控識別整合