.NET 組態提供者

Azure 應用程式組態是一項受控服務，可協助開發人員簡單且安全地集中管理其應用程式組態。 .NET 設定提供者連結庫可讓您以受控方式從 Azure 應用程式組態存放區載入組態。此用戶端連結庫會在適用於 .NET 的 Azure SDK 之上新增其他功能。

載入設定

Azure 應用程式組態 .NET 組態提供者會與 .NET 組態系統整合，讓您輕鬆地從 Azure 應用程式組態存放區載入組態值。您可以在應用程式啟動期間新增提供者，並與其他組態來源一起使用。

若要使用 .NET 元件提供者，請安裝套件：

dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration

您可以呼叫 AddAzureAppConfiguration 上的 IConfigurationBuilder 擴充方法，將 Azure 應用程式組態新增為應用程式的組態提供者。

配置提供程式庫實作結合 選項模式 和 建構器模式，以提供乾淨且宣告式的方法來設定 AzureAppConfigurationOptions。方法 AddAzureAppConfiguration 接受委派 Action<AzureAppConfigurationOptions> 參數，可讓您透過 Fluent API 設定提供者。

若要連線到您的 Azure 應用程式組態存放區，請在實體上Connect呼叫 AzureAppConfigurationOptions 方法，這會傳回相同的選項物件以啟用方法鏈結。

Microsoft Entra 身份識別
連接字串

您可以使用 DefaultAzureCredential或任何其他令牌認證實作，向應用程式組態存放區進行驗證。請依照指示將您的憑證指派為 應用程式設定數據讀取者 角色。

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

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
    {
        string endpoint = Environment.GetEnvironmentVariable("AppConfigurationEndpoint");
        options.Connect(new Uri(endpoint), new DefaultAzureCredential());
    });

var config = builder.Build();
Console.WriteLine(config["TestApp:Settings:Message"] ?? "Hello world!");

備註

在 ASP.NET Core 應用程式或背景服務中，您可能會在 AddAzureAppConfiguration 上呼叫 builder.Configuration。

var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddAzureAppConfiguration(options =>
    {
        string endpoint = Environment.GetEnvironmentVariable("Endpoint");
        options.Connect(new Uri(endpoint), new DefaultAzureCredential());
    });

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

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
    {
        string connectionString = Environment.GetEnvironmentVariable("ConnectionString");
        options.Connect(connectionString);
    });

var config = builder.Build();
Console.WriteLine(config["TestApp:Settings:Message"] ?? "Hello world!");

備註

在 ASP.NET Core 應用程式或背景服務中，您可能會在 AddAzureAppConfiguration 上呼叫 builder.Configuration。

var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddAzureAppConfiguration(options =>
    {
        string connectionString = Environment.GetEnvironmentVariable("ConnectionString");
        options.Connect(connectionString);
    });

取用設定

新增 Azure 應用程式組態提供者之後，您可以透過數種方式存取您的組態值：

1.直接存取

最簡單的方法是直接從 IConfiguration 實例擷取值：

// Directly get the configuration
string message = configuration["TestApp:Settings:Message"];

IConfigurationSection settingsSection = configuration.GetSection("TestApp:Settings");

2. 使用 IConfiguration 進行相依性注入

在服務或控制器中，您可以直接插入並使用 IConfiguration 介面：

public class WeatherService
{
    private readonly IConfiguration _configuration;

    public WeatherService(IConfiguration configuration)
    {
        _configuration = configuration;
    }

    public Task<WeatherForecast> GetForecastAsync()
    {
        // Access configuration values directly from the injected instance
        string apiEndpoint = _configuration["TestApp:Weather:ApiEndpoint"];

        ...

        return Task.FromResult(new WeatherForecast());
    }
}

3. 強型別設定的選項模式

// Define a strongly-typed settings class
public class Settings
{
    public string BackgroundColor { get; set; }
    public long FontSize { get; set; }
    public string FontColor { get; set; }
    public string Message { get; set; }
}

builder.Services.Configure<Settings>(builder.Configuration.GetSection("TestApp:Settings"));

如需 .NET 中選項模式的詳細資訊，請移至檔。

JSON 內容類型處理

您可以在應用程式組態中建立 JSON 索引鍵/值。當讀取具有內容類型 "application/json" 的鍵值時，設定提供者會將其扁平化為 IConfiguration 中的個別設定。如需詳細資訊，請移至使用內容類型在應用程式組態中儲存 JSON 索引鍵/值。

備註

從的 Microsoft.Extensions.Configuration.AzureAppConfiguration 版開始，組態提供者允許在具有內容類型的索引鍵/值中撰寫註解，如 (application/json) 中定義。

使用選取器載入特定索引鍵/值

根據預設，組態提供者會從應用程式組態載入不含標籤的所有索引鍵/值。您可以透過呼叫Select上的AzureAppConfigurationOptions方法，從應用程式設定存放區選擇性地載入索引鍵/值。

builder.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())
        // Load configuration values with prefix "TestApp:" and no label
        .Select("App:Settings:*")
        // Load configuration values with prefix "TestApp:" and "Prod" label
        .Select("App:Settings:*", "Prod")
        // Load configuration values with prefix "TestApp:" and "Prod" label that have the tag "Group" with value "Contoso"
        .Select("App:Settings:*", "Prod", new[] { "Group=Contoso" })
});

方法 Select 會採用三個參數。第一個參數是一個鍵篩選，指定要載入哪些鍵，第二個參數是一個標籤篩選，指定要載入特定標籤的鍵值，而第三個參數會指定所有必須存在於鍵值上的標記篩選集合以供載入。

備註

當多個 Select 呼叫包含重疊索引鍵時，後續呼叫的優先順序高於先前的呼叫。

關鍵篩選

索引鍵篩選參數會決定要包含的設定索引鍵：

完全相符：使用特定字串只會比對完全符合篩選條件的索引鍵。
前綴匹配：在結尾新增星號（*）會建立前綴篩選器（例如，App:Settings:*載入以 "App:Settings:" 開頭的所有索引鍵）。
多重索引鍵選取：使用逗號（,）允許選取多個明確索引鍵（例如， Key1,Key2,Key3）。
保留字元：星號 (*)、逗號 (,) 和反斜杠 (\) 是保留字元，必須使用反斜杠進行逸出，才能用在索引鍵名稱中（例如，索引鍵篩選 a\\b\,\*c* 會返回所有索引鍵值，其索引鍵開頭為 a\b,*c）。

備註

您無法將萬用字元前置詞比對與相同 Select 呼叫中的逗點分隔篩選結合。例如，abc*,def不支援，但您可以使用Select和abc*進行個別def呼叫。

標籤篩選

標籤篩選參數會選取具有指定標籤的索引鍵/值。如果未指定，則會使用內建的 LabelFilter.Null。

備註

標籤篩選不支援星號（*）和逗號（,）字元。反斜線 (\) 字元是保留的，且必須使用另一個反斜線 (\) 逸出。

標籤篩選

標籤篩選參數會選取具有特定標籤的索引鍵/值。只有當篩選中指定的所有標記和對應的值都符合時，才會載入鍵值。若要指定標記的 Null 值，可以使用內建TagValue.Null功能。

備註

星號 (*)、逗點 (,) 和反斜線 (\) 是保留的字元，且用於標籤篩選中時必須使用反斜線來逸出。

從索引鍵修剪前置詞

使用特定前置詞載入組態值時，您可以使用 TrimKeyPrefix 方法，從組態中的索引鍵中移除這些前置詞。這會在應用程式中建立更簡潔的設定密鑰，同時維護應用程式組態存放區中的組織。

builder.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())
        // Load configuration values with prefix "TestApp:" and trim the prefix
        .Select("TestApp:*")
        .TrimKeyPrefix("TestApp:");
});

例如，如果您的應用程式組態存放區包含名為 TestApp:Settings:Message 的索引鍵，則在修剪 Settings:Message 前置詞後，可以在您的應用程式中存取為 TestApp:。

組態設定對應

從 Azure 應用程式組態載入索引鍵/值時，提供者會先將其擷取為 ConfigurationSetting 物件，再將它們新增至 .NET 組態系統。 Map API 可讓您在此管線期間轉換這些設定，讓您控制應用程式中的組態顯示方式。

方法 Map 接受接收 ConfigurationSetting 物件的委派函式、可讓您修改它，並傳 ValueTask<ConfigurationSetting>回。這特別適用於根據運行時間條件的索引鍵名稱轉換或值格式設定。

下列範例示範使用 Map API 用冒號（__）取代設定鍵中的雙底線（:）。當索引鍵需要在應用程式組態中使用替代字元時，此轉換會保留 .NET 組態預期的階層式結構：

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .Map((setting) =>
        {
            // Transform keys from format "App__Settings__Message" to "App:Settings:Message"
            setting.Key = setting.Key.Replace("__", ":");
            
            return new ValueTask<ConfigurationSetting>(setting);
        });
});

小提示

此 Map 作業會套用至從應用程式組態擷取的所有組態設定，因此請確定您的轉換邏輯會正確處理所有可能的金鑰格式。

設定重新整理

設定重新整理可讓應用程式從應用程式組態存放區提取最新的值，而不需要重新啟動。您可以呼叫 ConfigureRefresh 方法來設定鍵值刷新。

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        // Load all keys that start with `TestApp:` and have no label
        .Select(keyFilter: "TestApp:*", labelFilter: LabelFilter.Null)
        .ConfigureRefresh(refreshOptions => {
            // Trigger full configuration refresh when any selected key changes.
            refreshOptions.RegisterAll()
            // Check for changes no more often than every 60 seconds
                .SetRefreshInterval(TimeSpan.FromSeconds(60));
        });
});

在 ConfigureRefresh 方法內，您可以呼叫 RegisterAll 方法，指示應用程式組態提供者在偵測到任何選取的索引鍵/值 (開頭為 TestApp: 且沒有標籤的項目) 有所變更時重新載入設定。

您可以新增對 SetRefreshInterval 方法的呼叫，以指定設定重新整理之間的最短時間。如果未設定，預設重新整理間隔為30秒。

觸發重新整理

若要觸發重新整理，您必須呼叫 TryRefreshAsync 的 IConfigurationRefresher 方法。 Azure 應用程式組態會根據您的應用程式架構，提供數種實作模式。

1. 相依性插入

對於使用相依性插入的應用程式（包括 ASP.NET Core 和背景服務），請註冊重新整理器服務：

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())            
           .ConfigureRefresh(refreshOptions =>
           {
                refreshOptions.RegisterAll()
                    .SetRefreshInterval(TimeSpan.FromSeconds(60));
           })
});

// Register refresher service with the DI container
builder.Services.AddAzureAppConfiguration();

builder.Services.AddAzureAppConfiguration() 將 IConfigurationRefreshProvider 服務新增至 DI 容器中，讓您可以存取應用程式設定中所有 Azure App Configuration 來源的更新工具。

ASP.NET Core 應用程式

針對 ASP.NET Core 應用程式，您可以使用 Microsoft.Azure.AppConfiguration.AspNetCore 套件，透過內建的中介軟體來達成要求驅動的配置刷新。

dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore

註冊服務之後，呼叫 UseAzureAppConfiguration 以將新增 AzureAppConfigurationRefreshMiddleware 至您的應用程式管線，以在傳入要求上自動重新整理組態：

...

// Call the AddAzureAppConfiguration to add refresher service to the DI container
builder.Services.AddAzureAppConfiguration();

var app = builder.Build();

// Call the app.UseAzureAppConfiguration() method as early as appropriate in your request pipeline so another middleware doesn't skip it
app.UseAzureAppConfiguration();

// Continue with other middleware registration
app.UseRouting();
...

在設定的重新整理的間隔，AzureAppConfigurationRefreshMiddleware 會自動檢查是否有組態變更。這種方法很有效率，因為只有在符合這兩個條件時才會重新整理：收到 HTTP 要求，而且重新整理間隔已經過時。

背景服務

針對背景服務，您可以注入IConfigurationRefresherProvider 服務，並手動刷新每個已註冊的刷新程序。

public class Worker : BackgroundService
{
    private readonly IConfiguration _configuration;
    private readonly IEnumerable<IConfigurationRefresher> _refreshers;

    public Worker(IConfiguration configuration, IConfigurationRefresherProvider refresherProvider)
    {
        _configuration = configuration;
        _refreshers = refresherProvider.Refreshers;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        foreach (IConfigurationRefresher refresher in _refreshers)
        {
            refresher.TryRefreshAsync();
        }

        ...
    }
}

2.直接存取

對於不使用相依性插入的應用程式，您可以直接從選項取得重新整理器：

IConfigurationRefresher refresher = null;
var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())            
           .ConfigureRefresh(refreshOptions =>
           {
               refreshOptions.RegisterAll();
           });

    // Store the refresher for later use
    refresher = options.GetRefresher();
});

IConfiguration config = builder.Build();

// Later in your code, trigger refresh when needed
if (refresher != null)
{
    await refresher.TryRefreshAsync()
}

Console.WriteLine(config["TestApp:Settings:Message"]);

備註

即使重新整理呼叫因任何原因而導致失敗，您的應用程式仍會繼續使用快取設定。會在短時間內根據您的應用活動再進行一次嘗試。在設定的重新整理的間隔過去之前，呼叫重新整理是不可操作的，因此即使頻繁呼叫，其對效能的影響也是最小的。

重新整理 Sentinel 索引鍵

Sentinel 索引鍵是您完成所有其他索引鍵變更之後才更新的索引鍵。設定提供者會監視 Sentinel 索引鍵，而不是所有選取的索引鍵/值。偵測到變更時，您的應用程式會重新整理所有設定值。

此方法在更新多個鍵值時很有用。只有在完成所有其他組態變更之後，才會更新 sentinel 金鑰，以確保應用程式只會重載設定一次，維持一致性。

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        // Load all keys that start with `TestApp:` and have no label
        .Select(keyFilter: "TestApp:*", labelFilter: LabelFilter.Null)
        .ConfigureRefresh(refreshOptions => {
            // Trigger full configuration refresh only if the `SentinelKey` changes.
            refreshOptions.Register("SentinelKey", refreshAll: true);
        });
});

這很重要

索引鍵/值不會自動註冊以進行重新整理監控。您必須明確呼叫 ConfigureRefresh，然後使用 RegisterAll 方法（以監控所有載入的密鑰）或 Register 方法（以監控個別密鑰）來註冊金鑰。

如需重新整理設定的詳細資訊，請移至教學課程：在 ASP.NET Core 應用程式中使用動態設定。

功能旗標

Azure 應用程式組態中的功能旗標提供新式方法來控制應用程式中的功能可用性。與一般的組態值不同，功能旗標必須使用 UseFeatureFlags 方法明確載入。您可以使用選取器設定 on FeatureFlagOptions 來載入特定功能旗標，並設定功能旗標重新整理間隔。

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .UseFeatureFlags(featureFlagOptions => {
            // Load feature flags with prefix "TestApp:" and "dev" label
            featureFlagOptions.Select("TestApp:*", "dev")
            // Check for changes no more often than every 60 seconds
                .SetRefreshInterval(TimeSpan.FromSeconds(60));
        });
});

在UseFeatureFlags方法內，您可以呼叫Select方法來選擇性地載入功能標誌。您可以使用索引鍵篩選、標籤篩選和標籤篩選來選取您要載入的功能旗標。 Select如果未呼叫任何方法，UseFeatureFlags則預設會載入不含標籤的所有功能旗標。

不同於索引鍵/值，功能旗標會自動註冊以進行重新整理，而不需要明確的 ConfigureRefresh 呼叫。您可以透過 SetRefreshInterval 方法指定功能旗標重新整理之間的最短時間。默認重新整理間隔為30秒。

功能管理

功能管理連結庫提供一種方式，可根據功能旗標來開發和公開應用程式功能。功能管理程式庫的設計目的是要與設定提供者程式庫搭配運作。安裝 Microsoft.FeatureManagement 套件：

dotnet add package Microsoft.FeatureManagement

您可以呼叫 AddFeatureManagement 來註冊 IVariantFeatureManager 及其相關服務到 DI 容器中。這個註冊可讓您透過相依性插入在整個應用程式中使用功能旗標功能。

using Microsoft.FeatureManagement;

...

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential());
    // Use feature flags
    options.UseFeatureFlags();
});

// Register feature management services
builder.Services.AddFeatureManagement();

下列範例示範如何透過相依性插入使用功能管理員服務：

public class WeatherForecastController : ControllerBase
{
    private readonly IFeatureManager _featureManager;

    public WeatherForecastController(IVariantFeatureManager featureManager)
    {
        _featureManager = featureManager;
    }

    [HttpGet]
    public async Task<IActionResult> Get()
    {
        // Check if a feature flag is enabled
        if (await _featureManager.IsEnabledAsync("WeatherForecast"))
        {
            var forecast = GenerateWeatherForecast();
            return Ok(forecast);
        }
        
        return NotFound("Weather forecast feature is not available");
    }
}

如需如何使用功能管理連結庫的詳細資訊，請移至功能旗標快速入門。

Key Vault 參考

Azure 應用程式組態支援參考儲存在 Azure Key Vault 中的祕密。在應用程式組態中，您可以建立對應至儲存在 Key Vault 中祕密的索引鍵。祕密會安全地儲存在 Key Vault 中，但可以像載入其他任何設定一樣存取。

組態提供者程式庫會擷取 Key Vault 參考，就像針對儲存在應用程式組態中的任何其他索引鍵一樣。由於用戶端會將金鑰辨識為 Key Vault 參考，因此它們具有獨特的內容類型，用戶端會連線到 Key Vault 來擷取金鑰的值以供應用程式使用。

連線到 Key Vault

您必須呼叫 ConfigureKeyVault 方法來設定如何連線到 Key Vault。 Azure 應用程式組態提供者提供多種方式來驗證和存取您的 Key Vault 秘密。

1.註冊 `SecretClient` 實例

您可以註冊指定的 SecretClient 執行個體，以用來解析相關聯索引鍵保存庫祕密的索引鍵保存庫參考。

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

...

var secretClient = new SecretClient(new Uri(vaultUri), new DefaultAzureCredential());

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())  
        .ConfigureKeyVault(kv =>
        {
            // Register a SecretClient instance
            kv.Register(secretClient);
        });
});

2.使用認證

您可以設定用來向未註冊 SecretClient 之索引鍵保存庫進行驗證的認證。

using Azure.Identity;

...

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())  
        .ConfigureKeyVault(kv =>
        {
            // Use DefaultAzureCredential to access all Key Vaults
            kv.SetCredential(new DefaultAzureCredential());
        });
});

3.使用自定義秘密解析程式

您也可以呼叫 SetSecretResolver 來新增自定義秘密解析程式，此解析程式在沒有註冊 SecretClient 可用或提供的認證無法向 Key Vault 進行驗證時使用。此方法接受將 Key Vault URI 解析為秘密值的委派函式。下列範例示範如何使用秘密解析程式，從開發中的環境變數擷取秘密，並在無法從 Key Vault 取得秘密時使用後援值。

var secretClient = new SecretClient(new Uri(vaultUri), new DefaultAzureCredential());

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())  
        .ConfigureKeyVault(kv =>
        {
            // Add a custom secret resolver function
            kv.SetSecretResolver(async (Uri secretUri) =>
            {                
                if (builder.Environment.IsDevelopment())
                {
                    return Environment.GetEnvironmentVariable("FALLBACK_SECRET_VALUE");
                }

                try 
                {
                    var secret = await secretClient.GetSecretAsync(secretName);
                    return secret.Value;
                }
                catch (Exception ex)
                {
                    logger.LogWarning($"Failed to retrieve secret from {secretUri}: {ex.Message}");
                    
                    return Environment.GetEnvironmentVariable("FALLBACK_SECRET_VALUE");
                }
            });
        });
});

備註

解析 Key Vault 參考時，提供者會遵循下列順序：

已註冊 SecretClient 的執行個體
默認認證
自訂密鑰解析器

這很重要

如果您的應用程式載入包含未經正確配置的 Key Vault 參考的金鑰值，則會在啟動時拋出例外。請確定您已正確設定 Key Vault 存取或秘密解析程式。

小提示

您可以使用自訂索引鍵解析程式來處理 Key Vault 參考意外新增至應用程式組態存放區的情況。解決程式可以提供後備值、記錄警告或有效處理缺失的正確憑證以存取 Key Vault，而不是拋出例外。

Key Vault 祕密重新整理

Azure 應用程式組態可讓您設定與設定重新整理周期無關的秘密重新整理間隔。這對安全性至關重要，因為雖然應用程式組態中的 Key Vault 參考 URI 保持不變，但 Key Vault 中的基礎秘密可能會輪替作為安全性做法的一部分。

若要確保您的應用程式一律使用最新的秘密值，請設定 SetSecretRefreshInterval 方法。這會強制提供者在下列情況下從 Key Vault 擷取新的秘密值：

您的應用程式呼叫 IConfigurationRefresher.TryRefreshAsync
該機密的設定重新整理間隔已經過期

即使在您的應用程式組態存放區中未偵測到任何變更，此機制仍能運作，以確保您的應用程式與輪替的祕密保持同步。

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .ConfigureKeyVault(kv =>
        {
            kv.SetCredential(new DefaultAzureCredential());

            // Option 1: Set refresh interval for specific secrets
            kv.SetSecretRefreshInterval("ApiKey", TimeSpan.FromHours(12)); 
            
            // Option 2: Set a global refresh interval for all secrets with no refresh interval specified
            kv.SetSecretRefreshInterval(TimeSpan.FromHours(24));
        })
        .ConfigureRefresh(refreshOptions => refreshOptions.RegisterAll());
});

如需如何使用 Key Vault 參考的詳細資訊，請移至教學課程：在 ASP.NET Core 應用程式中使用 Key Vault 參考。

快照

快照集是應用程式組態存放區索引鍵/值的不可變具名子集。建立過程中會透過索引鍵和標籤篩選條件，選擇組成快照集的索引鍵/值。建立快照集之後，其中的索引鍵/值一定會維持不變。

您可以使用 SelectSnapshot 從快照載入鍵值。

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential());
    // Select an existing snapshot by name. This adds all of the key-values and feature flags from the snapshot to this application's configuration.
    options.SelectSnapshot("SnapshotName");
});

如需使用快照集的相關信息，請移至建立和使用快照集。

快照參考

快照參考是參考相同應用程式組態存放區中快照的組態設定。載入時，提供者會解析它，並新增該快照集中的所有索引鍵/值。使用快照集參考可以在執行階段在快照之間切換，這與 SelectSnapshot("...")不同，後者需要變更程式碼和/或重新啟動才能切換到新的快照。

備註

若要使用快照參照，請使用 8.4.0 版或更新版本 Microsoft.Extensions.Configuration.AzureAppConfiguration。

啟動重試

組態載入是應用程式啟動期間的重要路徑作業。為了確保可靠性，Azure 應用程式組態提供者會在初始設定負載期間實作強固的重試機制。這有助於保護您的應用程式免於暫時性網路問題，否則可能會防止成功啟動。

您可以使用ConfigureStartupOptions方法來自訂此行為。

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .ConfigureStartupOptions(startupOptions =>
        {
            // Set the time-out for the initial configuration load
            startupOptions.Timeout = TimeSpan.FromSeconds(60);
        });
});

地理複製

如需使用異地複寫的相關資訊，請移至啟用異地復寫。

分散式追蹤

Azure 應用程式組態 .NET 提供者包含分散式追蹤的內建支援功能，可讓您針對整個應用程式內的組態作業進行監視和故障排除。提供者會公開一個名為 ActivitySource 的 "Microsoft.Extensions.Configuration.AzureAppConfiguration"，以啟動像是載入組態和重新整理組態這類關鍵作業的 Activity。

下列範例示範如何設定 OpenTelemetry 來擷取和監視組態提供者所產生的分散式追蹤：

List<Activity> exportedActivities = new();
builder.Services.AddOpenTelemetry()
    .WithTracing(traceBuilder => {
        traceBuilder.AddSource(["Microsoft.Extensions.Configuration.AzureAppConfiguration"]);
            .AddInMemoryExporter(exportedActivities)
    });

如需 .NET 中 OpenTelemetry 的詳細資訊，請參閱 OpenTelemetry .NET 檔。

健康檢查

Azure 應用程式設定 .NET 提供者支援 .NET 應用程式健康情況檢查。若要啟用健康情況檢查，您可以在 AddAzureAppConfiguration() 上呼叫 IHealthChecksBuilder 方法，這將使用預設註冊名稱 IHealthCheck 新增一個 "Microsoft.Extensions.Configuration.AzureAppConfiguration"。

builder.Configuration.AddAzureAppConfiguration(options => 
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential()));

builder.Services.AddHealthChecks()
    .AddAzureAppConfiguration();

當上次載入或重新整理嘗試失敗時，.NET 提供者會被視為狀況不良。

如需 .NET 中健康情況檢查的詳細資訊，請參閱 .NET 健康情況監視文件。

後續步驟

若要瞭解如何使用 .NET 組態提供者，請繼續進行下列教學課程。

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

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-09-22

共用方式為

.NET 組態提供者

載入設定

取用設定

1.直接存取

2. 使用 IConfiguration 進行相依性注入

3. 強型別設定的選項模式

JSON 內容類型處理

使用選取器載入特定索引鍵/值

關鍵篩選

標籤篩選

標籤篩選

從索引鍵修剪前置詞

組態設定對應

設定重新整理

觸發重新整理

1. 相依性插入

ASP.NET Core 應用程式

背景服務

2.直接存取

重新整理 Sentinel 索引鍵

功能旗標

功能管理

Key Vault 參考

連線到 Key Vault

1.註冊 SecretClient 實例

2.使用認證

3.使用自定義秘密解析程式

Key Vault 祕密重新整理

快照

快照參考

啟動重試

地理複製

分散式追蹤

健康檢查

後續步驟

意見反應

其他資源

1.註冊 `SecretClient` 實例