教學課程：在 .NET 背景服務中使用動態設定

2025-04-22

來自應用程式組態的數據可以載入為 .NET 應用程式中的應用程式設定。如需詳細資訊，請參閱快速入門。不過，如同 .NET 所設計，應用程式設定只能在應用程式重新啟動時重新整理。應用程式組態 .NET 提供程式庫是 .NET Standard 程式庫。其支援動態快取和重新整理設定，而不需重新開機應用程式。本教學課程說明如何在 .NET 背景服務中實作動態組態更新。

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

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

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立一個。
應用程式組態存放區。建立存放區。
.NET SDK 6.0 或更新版本 - 也可以在 Azure Cloud Shell 中使用。

新增索引鍵-值

將下列索引鍵/值新增至應用程式組態存放區，並保留標籤和內容類型的預設值。若要瞭解如何使用 Azure 入口網站或 CLI 將鍵值新增至儲存區的詳細資訊，請移至建立鍵值。

鍵	值
TestApp：設置：消息	Azure 應用程式組態的值

建立 .NET 背景服務

您可以使用 .NET 命令列介面（CLI）來建立新的 .NET 應用程式專案。使用 .NET CLI 而非 Visual Studio 的好處，在於 .NET CLI 可同時於 Windows、macOS 及 Linux 平台上取得。或者，使用 Azure Cloud Shell 中提供的預先安裝工具。

為您的專案建立新資料夾。
在新的資料夾中，執行下列命令來建立新的 .NET 背景服務專案：
```
dotnet new worker
```

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

透過執行下列命令，將參考新增至 Microsoft.Extensions.Configuration.AzureAppConfiguration NuGet 套件：
```
dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration
```
執行下列命令以還原您專案的套件：
```
dotnet restore
```

開啟 Program.cs，並新增下列陳述式：

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

使用 Microsoft Entra ID 連接到應用程式設定（建議使用），或使用連接字串。

Microsoft Entra ID (建議)
連接字串

您可以使用 DefaultAzureCredential 來向應用程式組態存放區進行驗證。請遵循指示，將認證指派給 應用程式組態數據讀取者角色。在執行應用程式之前，請務必預留足夠的時間讓許可權生效。

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

var builder = Host.CreateApplicationBuilder(args);

builder.Configuration.AddAzureAppConfiguration(options =>
{
    string endpoint = Environment.GetEnvironmentVariable("Endpoint"); 
    options.Connect(new Uri(endpoint), new DefaultAzureCredential());
        // Load all keys that start with `TestApp:` and have no label.
        .Select("TestApp:*")
        // Reload configuration if any selected key-values have changed.
        .ConfigureRefresh(refreshOptions =>
        {
            refreshOptions.RegisterAll();
        });

    // Register the refresher so that the Worker service can consume it through DI
    builder.Services.AddSingleton(options.GetRefresher());
});

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

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

var builder = Host.CreateApplicationBuilder(args);

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(Environment.GetEnvironmentVariable("ConnectionString"))
        // Load all keys that start with `TestApp:` and have no label.
        .Select("TestApp:*")
        // Reload configuration if any selected key-values have changed.
        .ConfigureRefresh(refreshOptions =>
        {
            refreshOptions.RegisterAll();
        });

    // Register the refresher so that the Worker service can consume it through DI
    builder.Services.AddSingleton(options.GetRefresher());
});

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

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

小提示

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

開啟 Worker.cs。將IConfiguration和IConfigurationRefresher注入Worker服務，並從應用程式組態中記錄配置數據。

public class Worker : BackgroundService
{
    private readonly ILogger<Worker> _logger;
    private readonly IConfiguration _configuration;
    private readonly IConfigurationRefresher _refresher;

    public Worker(ILogger<Worker> logger, IConfiguration configuration, IConfigurationRefresher refresher)
    {
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
        _configuration = configuration ?? throw new ArgumentNullException(nameof(configuration));
        _refresher = refresher ?? throw new ArgumentNullException(nameof(refresher));
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            // Intentionally not await TryRefreshAsync to avoid blocking the execution.
            _refresher.TryRefreshAsync(stoppingToken);

            if (_logger.IsEnabled(LogLevel.Information))
            {
                _logger.LogInformation(_configuration["TestApp:Settings:Message"] ?? "No data.");
            }

            await Task.Delay(TimeSpan.FromSeconds(30), stoppingToken);
        }
    }
}

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

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

設定環境變數。
- Microsoft Entra ID (建議)
- 連接字串
將名為 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>'
```
將名為 ConnectionString 的環境變數設定為應用程式組態存放區的唯讀連接字串 (在 Azure 入口網站中位於您存放區的 [存取金鑰] 底下)。

如果您使用 Windows 命令提示字元，請執行下列命令，然後重新啟動命令提示字元以讓變更生效：
```
setx ConnectionString "<connection-string-of-your-app-configuration-store>"
```
如果您使用 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：設置：消息 Azure 應用程式組態的資料 - 已更新
請稍候片刻，讓刷新間隔時間窗口結束。您會看到主控台輸出已變更。

鍵	值
TestApp：設置：消息	Azure 應用程式組態的資料 - 已更新

清除資源

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

重要

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

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

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

下一步

在本教學課程中，您已啟用 .NET 背景服務，以動態方式從應用程式組態重新整理組態設定。若要瞭解如何在 ASP.NET Web 應用程式中啟用動態設定，請繼續進行下一個教學課程：

啟用 ASP.NET Web 應用程式中的動態組態

如需了解如何使用 Azure 受控識別簡化存取應用程式組態，請繼續進行下一個教學課程：

受控識別整合