Zprostředkovatel konfigurace .NET

Azure App Configuration je spravovaná služba, která vývojářům pomáhá jednoduše a bezpečně centralizovat konfigurace aplikací. Knihovna zprostředkovatele konfigurace .NET umožňuje načítat konfiguraci ze služby Azure App Configuration Store spravovaným způsobem. Tato klientská knihovna přidává k sadě Azure SDK pro .NET další funkce .

Konfigurace načtení

Zprostředkovatel konfigurace azure App Configuration .NET se integruje s konfiguračním systémem .NET a usnadňuje načítání hodnot konfigurace z úložiště Azure App Configuration. Zprostředkovatele můžete přidat při spuštění aplikace a použít ho společně s dalšími zdroji konfigurace.

Pokud chcete použít zprostředkovatele konfigurace .NET, nainstalujte balíček:

dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration

Zavoláte metodu rozšíření na AddAzureAppConfiguration, abyste přidali IConfigurationBuilder jako poskytovatele konfigurace vaší aplikace.

Knihovna zprostředkovatele konfigurace implementuje kombinaci vzorů Možnosti a Builder, což poskytuje přehledný a deklarativní způsob konfigurace AzureAppConfigurationOptions. Metoda AddAzureAppConfiguration přijímá parametr delegáta Action<AzureAppConfigurationOptions> , který umožňuje nakonfigurovat poskytovatele prostřednictvím rozhraní FLUENT API.

Pokud se chcete připojit k úložišti Azure App Configuration, zavolejte metodu Connect na instanci AzureAppConfigurationOptions, která vrací stejný objekt možností pro povolení řetězení metod.

Microsoft Entra ID
Připojovací řetězec

K ověření vaší služby App Configuration Store můžete použít DefaultAzureCredential, nebo jakoukoli jinou implementaci přihlašovacích údajů tokenu. Postupujte podle pokynů, aby vaše přihlašovací údaje byly přiřazeny k roli Čtenář dat konfigurace aplikace.

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!");

Poznámka:

V aplikaci ASP.NET Core nebo v běžící službě na pozadí můžete volat AddAzureAppConfiguration na 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!");

Poznámka:

V aplikaci ASP.NET Core nebo v běžící službě na pozadí můžete volat AddAzureAppConfiguration na builder.Configuration.

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

Využití konfigurace

Po přidání zprostředkovatele Azure App Configuration můžete k hodnotám konfigurace přistupovat několika způsoby:

1. Přímý přístup

Nejjednodušším přístupem je načíst hodnoty přímo z IConfiguration instance:

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

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

2. Injektáž závislostí s IConfiguration

Ve službách nebo řadičích můžete přímo vložit a používat IConfiguration rozhraní.

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. Vzor možností pro konfiguraci silného typu

// 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"));

Další informace o vzorech možností v .NET najdete v dokumentaci.

Zpracování typu obsahu JSON

Hodnoty klíčů JSON můžete vytvořit v App Configuration. Při čtení klíč-hodnoty s typem "application/json" obsahu zprostředkovatel konfigurace tuto hodnotu zploští do jednotlivých nastavení uvnitř IConfiguration. Další informace najdete v tématu Použití typu obsahu k ukládání hodnot klíčů JSON v App Configuration.

Poznámka:

Počínaje verzí 8.4.0Microsoft.Extensions.Configuration.AzureAppConfigurationumožňuje poskytovatel konfigurace komentáře definované v jsonC (key-values) s typem application/json obsahu.

Načtení konkrétních hodnot klíče pomocí selektorů

Ve výchozím nastavení poskytovatel konfigurace načte všechny hodnoty klíče bez popisku z App Configuration. Můžete vybraně načíst hodnoty klíče z úložiště konfigurace aplikace pomocí volání metody Select na 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" })
});

Metoda Select přebírá tři parametry. Prvním parametrem je filtr klíčů, který určuje, které klíče se mají načíst, druhý parametr je filtr popisku, který určuje hodnoty klíčů s konkrétními popisky, které se mají načíst, a třetí parametr určuje kolekci filtrů značek, které musí být k načtení k dispozici u hodnoty klíče.

Poznámka:

Pokud více Select volání zahrnuje překrývající se klíče, mají pozdější volání přednost před dřívějšími voláními.

Filtr klíčů

Parametr filtru klíčů určuje, které konfigurační klíče mají zahrnovat:

Přesná shoda: Použití konkrétního řetězce odpovídá pouze klíčům, které přesně odpovídají filtru.
Shoda předpony: Přidání hvězdičky (*) na konci vytvoří filtr předpony (např.: App:Settings:* načte všechny klíče začínající na "App:Settings:").
Výběr více klíčů: Použití čárky (,) umožňuje výběr více explicitních klíčů (např Key1,Key2,Key3. ).
Rezervované znaky: Znaky hvězdička (*), čárka (,) a zpětné lomítko (\) jsou rezervované a musí být uchvácené zpětným lomítkem při použití v názvech klíčů (např. filtr a\\b\,\*c* klíčů vrátí všechny hodnoty klíče, jejichž klíč začíná a\b,*cna .).

Poznámka:

Ve stejném Select volání nelze kombinovat porovnávání předpon pomocí zástupných znaků s filtry oddělenými čárkou. Například není podporováno abc*,def , ale můžete provádět samostatná Select volání s abc* a def.

Filtr štítků

Parametr filtru štítků vybere klíčové hodnoty s konkrétním štítkem. Pokud není zadaný, použije se předdefinovaný.LabelFilter.Null

Poznámka:

Pro filtr popisků se nepodporují znaky hvězdičky (*) a čárky (,). Znak zpětného lomítka (\) je vyhrazen a musí být uchvácený pomocí jiného zpětného lomítka (\).

Filtry značek

Parametr pro filtrování vybírá hodnoty klíčů s konkrétními značkami. Hodnota klíče se načte pouze v případě, že obsahuje všechny značky a odpovídající hodnoty zadané ve filtrech. Pokud chcete zadat hodnotu null pro značku, můžete použít integrovanou TagValue.Null hodnotu.

Poznámka:

Znaky hvězdička (), čárka (*,) a zpětné lomítko (\) jsou vyhrazeny a musí být uchvácené zpětným lomítkem při použití ve filtru značek.

Oříznutí předpony z klíčů

Při načítání hodnot konfigurace s konkrétními předponami můžete pomocí TrimKeyPrefix metody odebrat tyto předpony z klíčů v konfiguraci. Tím se ve vaší aplikaci vytvoří čistější konfigurační klíče při zachování organizovanosti ve vašem úložišti konfigurace aplikací.

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

Pokud například úložiště App Configuration obsahuje klíč s názvem TestApp:Settings:Message, bude v aplikaci přístupný jako Settings:Message po oříznutí předpony TestApp: .

Mapování nastavení konfigurace

Při načítání hodnot klíčů ze služby Azure App Configuration je zprostředkovatel nejprve načte jako ConfigurationSetting objekty před jejich přidáním do konfiguračního systému .NET. Rozhraní Map API vám umožňuje transformovat tato nastavení během tohoto procesu, a tím mít kontrolu nad tím, jak se konfigurace zobrazují ve vaší aplikaci.

Metoda Map přijímá funkci delegáta, která přijímá ConfigurationSetting objekt, umožňuje jej upravit a vrací .ValueTask<ConfigurationSetting> To je užitečné zejména pro transformace názvů klíčů nebo formátování hodnot na základě podmínek za běhu.

Následující příklad ukazuje použití Map rozhraní API k nahrazení dvojitých podtržítek (__) dvojtečkami (:) v konfiguračních klíčích. Tato transformace zachovává hierarchickou strukturu očekávanou konfigurací .NET, pokud klíče potřebují použít alternativní znaky v Konfiguraci aplikace:

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);
        });
});

Návod

Operace Map se použije na všechna nastavení konfigurace načtená z Konfigurace aplikace, takže se ujistěte, že logika transformace zpracovává všechny možné formáty klíčů správně.

Aktualizace konfigurace

Konfigurace aktualizace umožňuje aplikaci načíst nejnovější hodnoty z App Configuration Storu, aniž by se museli restartovat. Můžete použít metodu ConfigureRefresh k nastavení obnovení hodnoty klíčů.

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 Uvnitř metody zavoláte metoduRegisterAll, která zprostředkovateli konfigurace aplikace dá pokyn, aby znovu načítal konfiguraci, kdykoli zjistí změnu v některé z vybraných hodnot klíčů (ty, které začínají testAppem: a nemají žádný popisek).

Do metody můžete přidat volání SetRefreshInterval , které určuje minimální čas mezi aktualizacemi konfigurace. Pokud není nastavený, výchozí interval aktualizace je 30 sekund.

Aktivace aktualizace

Chcete-li aktivovat aktualizaci, je třeba volat TryRefreshAsync metodu IConfigurationRefresher. Azure App Configuration poskytuje několik vzorů implementace v závislosti na architektuře vaší aplikace.

1. Injektáž závislostí

Pro aplikace využívající injektáž závislostí (včetně ASP.NET Core a služeb na pozadí) zaregistrujte službu refresheru:

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 přidá službu do kontejneru DI, který poskytuje přístup k aktualizačním nástrojům všech zdrojů Azure App Configuration v konfiguraci aplikace.

aplikace ASP.NET Core

U aplikací ASP.NET Core můžete pomocí Microsoft.Azure.AppConfiguration.AspNetCore balíčku dosáhnout aktualizace konfigurace řízené požadavkem pomocí integrovaného middlewaru.

dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore

Po zaregistrování služby zavolejte UseAzureAppConfiguration aby se do kanálu vaší aplikace přidala komponenta, která automaticky aktualizuje konfiguraci při příchozích požadavcích.

...

// 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();
...

Automaticky AzureAppConfigurationRefreshMiddleware kontroluje změny konfigurace v nakonfigurovaném intervalu aktualizace. Tento přístup je efektivní, protože se aktualizuje pouze při splnění obou podmínek: přijímá se požadavek HTTP a uplynul interval aktualizace.

Služby na pozadí

U služeb běžících na pozadí můžete injektovat službu IConfigurationRefresherProvider a ručně obnovit každý z registrovaných aktualizátorů.

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. Přímý přístup

U aplikací, které nepoužívají injekci závislostí, můžete obnovovací mechanismus získat přímo z volby.

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"]);

Poznámka:

I když volání aktualizace z nějakého důvodu selže, bude vaše aplikace dál používat konfiguraci uloženou v mezipaměti. Další pokus se provede po krátké době na základě vaší aktivity v aplikaci. Volání aktualizace je no-op před uplynutím nakonfigurovaného intervalu aktualizace, takže jeho dopad na výkon je minimální, i když se volá často.

Aktualizace klíče sentinel

Klíč sentinelu je klíč, který aktualizujete po dokončení změny všech ostatních klíčů. Poskytovatel konfigurace monitoruje klíč sentinelu místo všech vybraných klíčových hodnot. Když se zjistí změna, aplikace aktualizuje všechny konfigurační hodnoty.

Tento přístup je užitečný při aktualizaci více hodnot klíče. Aktualizací klíče sentinelu až po dokončení všech ostatních změn konfigurace zajistíte, že vaše aplikace znovu načte konfiguraci jen jednou a zachová konzistenci.

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);
        });
});

Důležité

Hodnoty klíčů nejsou automaticky registrovány pro monitorování aktualizací. Musíte explicitně volat ConfigureRefresh a registrovat klíče pomocí RegisterAll metody (pro monitorování všech načtených klíčů) nebo Register metody (pro monitorování jednotlivého klíče).

Další informace o konfiguraci aktualizace najdete v kurzu: Použití dynamické konfigurace v aplikaci ASP.NET Core.

Příznak funkce

Příznaky funkcí v Azure App Configuration poskytují moderní způsob řízení dostupnosti funkcí ve vašich aplikacích. Na rozdíl od běžných konfiguračních hodnot musí být příznaky funkcí explicitně načteny pomocí UseFeatureFlags metody. Můžete konfigurovat FeatureFlagOptions, aby načetla konkrétní příznaky funkcionalit pomocí selektorů a nastavit interval aktualizace příznaků funkcionalit.

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));
        });
});

Uvnitř metody UseFeatureFlags zavoláte metodu Select, která selektivně načte flagy funkcí. K výběru příznaků funkcí, které chcete načíst, můžete použít filtr klíčů, filtr popisků a filtry značek . Pokud není volána žádná Select metoda, UseFeatureFlags načte všechny příznaky funkcí bez popisku ve výchozím nastavení.

Na rozdíl od hodnot klíčů se feature flagy automaticky registrují pro aktualizaci bez nutnosti výslovného ConfigureRefresh volání. Můžete zadat minimální čas mezi aktualizacemi příznaků funkce prostřednictvím SetRefreshInterval metody. Výchozí interval aktualizace je 30 sekund.

Správa funkcí

Knihovna pro správu funkcí poskytuje způsob, jak vyvíjet a zveřejňovat funkce aplikace na základě příznaků funkcí. Knihovna pro správu funkcí je navržená tak, aby fungovala ve spojení s knihovnou zprostředkovatele konfigurace. Nainstalujte balíček Microsoft.FeatureManagement:

dotnet add package Microsoft.FeatureManagement

Můžete zavolat AddFeatureManagement pro registraci IVariantFeatureManager a souvisejících služeb v kontejneru DI. Tato registrace zpřístupňuje funkci feature flag v celé aplikaci prostřednictvím dependency injection.

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();

Následující příklad demonstrující použití služby správce funkcí prostřednictvím injektáže závislostí:

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");
    }
}

Další informace o tom, jak používat knihovnu pro správu funkcí, najdete v rychlém startu s příznakem funkce.

Referenční informace ke službě Key Vault

konfigurace Aplikace Azure podporuje odkazování na tajné kódy uložené ve službě Azure Key Vault. V App Configuration můžete vytvořit klíče, které se mapuje na tajné kódy uložené ve službě Key Vault. Tajné kódy jsou bezpečně uložené ve službě Key Vault, ale po načtení se k nim dají přistupovat stejně jako k jakékoli jiné konfiguraci.

Knihovna zprostředkovatele konfigurace načítá odkazy na službu Key Vault stejně jako u všech dalších klíčů uložených v App Configuration. Protože klient rozpoznává klíče jako reference ke službě Key Vault, mají jedinečný typ obsahu a klient se připojuje ke službě Key Vault, aby získal jejich hodnoty pro vaši aplikaci.

Připojení ke službě Key Vault

K nakonfigurování připojení ke službě Key Vault je potřeba volat metodu ConfigureKeyVault . Poskytovatel azure App Configuration nabízí několik způsobů ověřování a přístupu k tajným kódům služby Key Vault.

1. Registrace `SecretClient` instance

Můžete zaregistrovat určené SecretClient instance, aby bylo možné řešit odkazy na trezor klíčů pro přístup k tajným informacím z přidruženého trezoru klíčů.

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. Použití přihlašovacích údajů

Můžete nastavit přihlašovací údaje použité k ověření v trezorech klíčů, které nemají zaregistrované 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. Použití vlastního překladače tajných kódů

Můžete také zavolat SetSecretResolver, abyste přidali vlastní překladač tajemství, který se použije, když není k dispozici žádný zaregistrovaný SecretClient nebo pokud se zadané přihlašovací údaje nepodaří ověřit ve službě Key Vault. Tato metoda přijímá funkci delegáta, která překládá identifikátor URI služby Key Vault na hodnotu tajného kódu. Následující příklad ukazuje použití překladače tajných kódů, který načte tajný klíč z proměnných prostředí ve vývoji a používá náhradní hodnoty v případě, že se nepodaří získat tajný kód ze služby 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");
                }
            });
        });
});

Poznámka:

Při řešení odkazů služby Key Vault poskytovatel používá toto pořadí:

Registrované SecretClient instance
Výchozí přihlašovací údaje
Překladač vlastních tajných kódů

Důležité

Pokud vaše aplikace načte hodnoty klíčů obsahující odkazy služby Key Vault bez správné konfigurace služby Key Vault, při spuštění se vyvolá výjimka . Ujistěte se, že jste správně nakonfigurovali přístup ke službě Key Vault nebo překladač tajných kódů.

Návod

Pomocí vlastního řešitele tajemství můžete zpracovávat případy, kdy se do App Configuration úložiště omylem přidají odkazy služby Key Vault. Řešitel může poskytnout náhradní hodnoty, protokolovat upozornění nebo citlivě zpracovat chybějící příslušné přihlašovací údaje pro přístup ke službě Key Vault místo vyvolání výjimek.

Aktualizace tajných kódů služby Key Vault

Azure App Configuration umožňuje konfigurovat intervaly aktualizace tajných kódů nezávisle na cyklu aktualizace konfigurace. To je důležité pro zabezpečení, protože zatímco referenční identifikátor URI služby Key Vault v konfiguraci aplikace zůstává beze změny, může se v rámci vašich postupů zabezpečení obměňovat základní tajný klíč ve službě Key Vault.

Pokud chcete zajistit, aby vaše aplikace vždy používala nejaktuálnější hodnoty tajných kódů, nakonfigurujte metodu SetSecretRefreshInterval . Zprostředkovatel tak vynutí načtení čerstvých tajných hodnot ze služby Key Vault v těchto případech:

Vaše aplikace volá IConfigurationRefresher.TryRefreshAsync
Nakonfigurovaný interval aktualizace tajného kódu uplynul.

Tento mechanismus funguje i v případě, že se v úložišti konfigurace aplikace nezjistí žádné změny, takže vaše aplikace zůstane synchronizovaná s rotujícími tajemstvími.

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());
});

Další informace o tom, jak používat referenční informace ke službě Key Vault, najdete v kurzu: Použití odkazů služby Key Vault v aplikaci ASP.NET Core.

Snímek

Snímek je pojmenovaná, neměnná podmnožina klíčů a hodnot v úložišti App Configuration. Hodnoty klíčů, které tvoří snímek, se vyberou během vytváření prostřednictvím filtrů klíčů a popisků. Po vytvoření snímku se zaručuje, že hodnoty klíče v rámci zůstanou beze změny.

Můžete zavolat SelectSnapshot a načíst páry klíč-hodnota ze snímku.

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");
});

Informace o používání snímků najdete v tématu Vytvoření a použití snímků.

Referenční informace ke snímkům

Odkaz na snímek je nastavení konfigurace, které odkazuje na snímek v témže App Configuration store. Když je načten, zprostředkovatel to vyřeší a přidá všechny dvojice klíč-hodnota z daného snímku. Použití odkazů na snímky umožňuje přepínání mezi snímky za běhu, na rozdíl od SelectSnapshot("..."), které vyžadují změny kódu nebo restartování pro přepnutí na nový snímek.

Poznámka:

Pokud chcete použít odkazy na snímky, použijte verzi 8.4.0 nebo novější verze Microsoft.Extensions.Configuration.AzureAppConfiguration.

Opakovaný pokus o spuštění

Načítání konfigurace je kritická operace během spouštění aplikace. Kvůli zajištění spolehlivosti implementuje poskytovatel azure App Configuration robustní mechanismus opakování během počátečního zatížení konfigurace. To pomáhá chránit vaši aplikaci před přechodnými problémy se sítí, které by jinak mohly bránit úspěšnému spuštění.

Toto chování můžete přizpůsobit pomocí ConfigureStartupOptions metody:

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);
        });
});

Geografická replikace

Informace o použití geografické replikace najdete v tématu Povolení geografické replikace.

Distribuované trasování

Poskytovatel .NET služby Azure App Configuration zahrnuje integrovanou podporu distribuovaného trasování, která umožňuje monitorovat a řešit potíže s operacemi konfigurace v rámci vaší aplikace. Zprostředkovatel zveřejňuje ActivitySource pojmenovaný "Microsoft.Extensions.Configuration.AzureAppConfiguration", který se spouští Activity pro klíčové operace, jako je načítání konfigurace a aktualizace konfigurace.

Následující příklad ukazuje, jak nakonfigurovat OpenTelemetry pro zachycení a monitorování distribuovaných trasování vygenerovaných poskytovatelem konfigurace:

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

Další informace o OpenTelemetry v .NET naleznete v dokumentaci k OpenTelemetry .NET.

Kontrola stavu

Poskytovatel .NET azure App Configuration podporuje kontroly stavu aplikací .NET. Chcete-li povolit kontroly stavu, můžete volat AddAzureAppConfiguration() metodu IHealthChecksBuilderIHealthCheck , která přidá s výchozím názvem "Microsoft.Extensions.Configuration.AzureAppConfiguration"registrace .

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

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

Poskytovatel .NET bude po selhání posledního pokusu o načtení nebo aktualizaci považován za chybný.

Další informace o kontrolách stavu v .NET najdete v dokumentaci k monitorování stavu .NET.

Další kroky

Pokud chcete zjistit, jak používat zprostředkovatele konfigurace .NET, pokračujte následujícím kurzem.

Povolení dynamické konfigurace ve webové aplikaci ASP.NET

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-08-20

Sdílet prostřednictvím

Zprostředkovatel konfigurace .NET

Konfigurace načtení

Využití konfigurace

1. Přímý přístup

2. Injektáž závislostí s IConfiguration

3. Vzor možností pro konfiguraci silného typu

Zpracování typu obsahu JSON

Načtení konkrétních hodnot klíče pomocí selektorů

Filtr klíčů

Filtr štítků

Filtry značek

Oříznutí předpony z klíčů

Mapování nastavení konfigurace

Aktualizace konfigurace

Aktivace aktualizace

1. Injektáž závislostí

aplikace ASP.NET Core

Služby na pozadí

2. Přímý přístup

Aktualizace klíče sentinel

Příznak funkce

Správa funkcí

Referenční informace ke službě Key Vault

Připojení ke službě Key Vault

1. Registrace SecretClient instance

2. Použití přihlašovacích údajů

3. Použití vlastního překladače tajných kódů

Aktualizace tajných kódů služby Key Vault

Snímek

Referenční informace ke snímkům

Opakovaný pokus o spuštění

Geografická replikace

Distribuované trasování

Kontrola stavu

Další kroky

Váš názor

Další materiály

1. Registrace `SecretClient` instance