共用方式為


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

應用程式組態 .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。 或者,如果您使用相依性插入來解析服務,您可以參考下列步驟。

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

    將下列程式代碼新增至 Program.cs

    // Existing code in Program.cs
    // ... ...
    
    // Add Azure App Configuration services to IServiceCollection
    builder.Services.AddAzureAppConfiguration();
    
  2. 從服務集合解析 的 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();
            }
        }
    }
    

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

  1. 設定名為 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'
    
  2. 執行下列命令來建置主控台應用程式:

     dotnet build
    
  3. 建置成功完成後,請執行下列命令以於本機執行應用程式:

     dotnet run
    

    Quickstart app launch local

  4. 登入 Azure 入口網站。 選取 [所有資源],然後選取您在快速入門中建立的應用程式組態存放區執行個體。

  5. 選取 [組態總管],然後更新下列索引鍵的值:

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

    Quickstart app refresh local

    注意

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

記錄和監視

記錄會在設定重新整理時輸出,並包含從 應用程式組態 存放區擷取的索引鍵/值的詳細資訊,以及對應用程式所做的組態變更。 如果您有 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

清除資源

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

重要

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

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

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

下一步

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