.NET-konfigurationsprovider

Azure App Configuration är en hanterad tjänst som hjälper utvecklare att centralisera sina programkonfigurationer enkelt och säkert. Med .NET-konfigurationsproviderbiblioteket kan du läsa in konfiguration från ett Azure App Configuration-arkiv på ett hanterat sätt. Det här klientbiblioteket lägger till ytterligare funktioner ovanpå Azure SDK för .NET.

Läs in konfiguration

Azure App Configuration .NET-konfigurationsprovider integreras med .NET-konfigurationssystemet, vilket gör det enkelt att ladda konfigurationsvärden från ditt Azure App Configuration-lager. Du kan lägga till providern under programstarten och använda den tillsammans med andra konfigurationskällor.

Om du vill använda .NET-konfigurationsprovidern installerar du paketet:

dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration

Du anropar AddAzureAppConfiguration tilläggsmetod på IConfigurationBuilder för att lägga till Azure App Configuration som en konfigurationsleverantör i din applikation.

Konfigurationsproviderbiblioteket implementerar ett kombinerat mönster för alternativ och builder-mönster för att ge ett rent, deklarativt sätt att konfigurera AzureAppConfigurationOptions. Metoden AddAzureAppConfiguration accepterar en Action<AzureAppConfigurationOptions> delegatparameter som gör att du kan konfigurera providern via ett fluent-API.

Om du vill ansluta till din Azure App Configuration store, anropar du metoden Connect på instansen AzureAppConfigurationOptions, som returnerar samma alternativobjekt för att möjliggöra metodlänkning.

Microsoft Entra-ID
Anslutningssträng

Du kan använda DefaultAzureCredential, eller någon annan implementering av tokenautentiseringsuppgifter, för att autentisera dig mot appkonfigurationslagringen. Följ anvisningarna för att tilldela dina autentiseringsuppgifter rollen App Configuration Data Reader .

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

Anmärkning

I ett ASP.NET Core-program eller en bakgrundstjänst kan du anropa AddAzureAppConfiguration på 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!");

Anmärkning

I ett ASP.NET Core-program eller en bakgrundstjänst kan du anropa AddAzureAppConfiguration på builder.Configuration.

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

Använda konfiguration

När du har lagt till Azure App Configuration-providern kan du komma åt dina konfigurationsvärden på flera sätt:

1. Direkt åtkomst

Den enklaste metoden är att hämta värden direkt från instansen IConfiguration :

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

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

2. Beroendeinmatning med IConfiguration

I tjänster eller styrenheter kan du mata in och använda IConfiguration gränssnittet direkt:

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. Alternativmönster för tydligt typad konfiguration

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

Mer information om alternativmönster i .NET finns i dokumentationen.

Hantering av JSON-innehållstyp

Du kan skapa JSON-nyckelvärden i App Configuration. När ett nyckelvärde med innehållstypen "application/json" läss kommer konfigurationsprovidern att platta ut det till enskilda inställningar i IConfiguration. Mer information finns i Använda innehållstyp för att lagra JSON-nyckelvärden i App Configuration.

Anmärkning

Från och med version 8.4.0 av Microsoft.Extensions.Configuration.AzureAppConfigurationtillåter konfigurationsprovidern kommentarer, enligt definitionen i (JSONC), i nyckelvärden med en application/json innehållstyp.

Läs in specifika nyckelvärden med hjälp av väljare

Som standard läser konfigurationsprovidern in alla nyckelvärden utan etikett från App Configuration. Du kan selektivt läsa in nyckelvärden från appkonfigurationsarkivet genom att anropa metoden på SelectAzureAppConfigurationOptions.

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

Metoden Select tar tre parametrar. Den första parametern är ett nyckelfilter som anger vilka nycklar som ska läsas in, den andra parametern är ett etikettfilter som anger vilka nyckelvärden med specifika etiketter som ska läsas in, och den tredje parametern anger en samling taggfilter som alla måste finnas på ett nyckelvärde för att läsas in.

Anmärkning

När flera Select anrop innehåller överlappande nycklar har senare anrop företräde framför tidigare.

Nyckelfilter

Parametern för nyckelfilter avgör vilka konfigurationsnycklar som ska inkluderas:

Exakt matchning: Om du använder en specifik sträng matchas endast nycklar som exakt matchar filtret.
Prefixmatchning: Om du lägger till en asterisk (*) i slutet skapas ett prefixfilter (t.ex. App:Settings:* läser in alla nycklar som börjar med "App:Settings:").
Flera nyckelval: Med ett kommatecken (,) kan du välja flera explicita nycklar (t.ex. Key1,Key2,Key3).
Reserverade tecken: Tecknen asterisk (*), kommatecken (,) och omvänt snedstreck (\) är reserverade och måste vara undantagna med ett omvänt snedstreck när de används i nyckelnamn (t.ex. returnerar nyckelfiltret a\\b\,\*c* alla nyckelvärden vars nyckel börjar med a\b,*c.).

Anmärkning

Du kan inte kombinera jokerteckenprefixmatchning med kommaavgränsade filter i samma Select anrop. Till exempel abc*,def stöds inte, men du kan göra separata Select anrop med abc* och def.

Etikettfilter

Parametern för etikettfilter väljer nyckelvärden med en specifik etikett. Om inget specifikt anges, används den inbyggda LabelFilter.Null.

Anmärkning

Tecknen asterisk (*) och kommatecken (,), stöds inte för etikettfilter. Omvänt snedstreck (\) är reserverat och måste föregås av ett annat omvänt snedstreck (\).

Filter för taggar

Parametern taggfilter väljer nyckelvärden med specifika taggar. Ett nyckelvärde läses bara in om alla taggar och motsvarande värden anges i filtren. Om du vill ange ett null-värde för en tagg kan den inbyggda TagValue.Null användas.

Anmärkning

Tecknen asterisk (*), kommatecken (,) och omvänt snedstreck (\) är reserverade och måste vara undantagna med ett omvänt snedstreck när de används i ett taggfilter.

Trimma prefix från nycklar

När du läser in konfigurationsvärden med specifika prefix kan du använda TrimKeyPrefix metoden för att ta bort dessa prefix från nycklarna i konfigurationen. Detta skapar renare konfigurationsnycklar i ditt program samtidigt som du bibehåller organisationen i App Configuration-lagret.

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

Om appkonfigurationsarkivet till exempel innehåller en nyckel med namnet TestApp:Settings:Message kommer det att vara tillgängligt i din applikation som Settings:Message efter att prefixet TestApp: har trimmats.

Mappning av konfigurationsinställning

När du läser in nyckelvärden från Azure App Configuration hämtar providern dem först som ConfigurationSetting objekt innan de läggs till i .NET-konfigurationssystemet. Med API:et Map kan du transformera de här inställningarna under den här pipelinen, vilket ger dig kontroll över hur konfigurationer visas i ditt program.

Metoden Map accepterar en ombudsfunktion som tar emot ett ConfigurationSetting objekt, gör att du kan ändra den och returnerar en ValueTask<ConfigurationSetting>. Detta är särskilt användbart för nyckelnamntransformeringar eller värdeformatering baserat på körningsvillkor.

I följande exempel visas hur du använder API:et Map för att ersätta dubbla understreck (__) med kolon (:) i konfigurationsnycklar. Den här omvandlingen bevarar den hierarkiska struktur som förväntas av .NET-konfigurationen när nycklar behöver använda alternativa tecken i App Configuration:

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

Tips/Råd

Åtgärden Map tillämpas på alla konfigurationsinställningar som hämtats från App Configuration, så se till att omvandlingslogik hanterar alla möjliga nyckelformat korrekt.

Uppdatering av konfiguration

Genom att konfigurera uppdatering kan programmet hämta de senaste värdena från App Configuration Store utan att behöva starta om. Du kan anropa ConfigureRefresh metoden för att konfigurera nyckel/värde-uppdateringen.

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 I metoden anropar RegisterAll du metoden för att instruera appkonfigurationsprovidern att läsa in konfigurationen igen när den identifierar en ändring i något av de valda nyckelvärdena (de som börjar med TestApp: och som inte har någon etikett).

Du kan lägga till ett anrop till SetRefreshInterval metoden för att ange den minsta tiden mellan konfigurationsuppdateringarna. Om det inte anges är standarduppdateringsintervallet 30 sekunder.

Utlös uppdatering

För att utlösa uppdatering måste du anropa TryRefreshAsync metoden för IConfigurationRefresher. Azure App Configuration innehåller flera mönster för implementering beroende på din programarkitektur.

1. Beroendeinmatning

För program som använder beroendeinmatning (inklusive ASP.NET Core- och bakgrundstjänster) registrerar du uppdateringstjänsten:

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 lägger till tjänsten i DI-containern, vilket ger dig åtkomst till uppdateringarna av alla Azure App Configuration-källor i programmets konfiguration.

ASP.NET Core-applikationer

För ASP.NET Core-program kan du använda Microsoft.Azure.AppConfiguration.AspNetCore paketet för att uppnå en konfigurationsuppdatering som drivs av begäran med ett inbyggt mellanprogram.

dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore

När du har registrerat tjänsten ska du anropa UseAzureAppConfiguration och lägga till AzureAppConfigurationRefreshMiddleware i programpipelinen, så att konfigurationen automatiskt uppdateras för inkommande begäranden.

...

// 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 letar automatiskt efter konfigurationsändringar vid det konfigurerade uppdateringsintervallet. Den här metoden är effektiv eftersom den bara uppdateras när båda villkoren uppfylls: en HTTP-begäran tas emot och uppdateringsintervallet har förflutit.

Bakgrundstjänster

För bakgrundstjänster kan du mata in IConfigurationRefresherProvider tjänsten och uppdatera var och en av de registrerade uppdateringarna manuellt.

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. Direkt åtkomst

För program som inte använder beroendeinmatning kan du hämta uppdateringsprogrammet direkt från alternativen:

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

Anmärkning

Även om uppdateringsanropet misslyckas av någon anledning fortsätter programmet att använda den cachelagrade konfigurationen. Ett annat försök görs efter en kort period baserat på din appaktivitet. Att anropa uppdatering är en no-op innan det konfigurerade uppdateringsintervallet förflutit, så prestandapåverkan är minimal även om den anropas ofta.

Uppdatera sentinelnyckeln

En sentinel-nyckel är en nyckel som du uppdaterar när du har slutfört ändringen av alla andra nycklar. Konfigurationsprovidern övervakar sentinel-nyckeln i stället för alla valda nyckelvärden. När en ändring identifieras uppdaterar appen alla konfigurationsvärden.

Den här metoden är användbar när du uppdaterar flera nyckelvärden. Genom att uppdatera sentinel-nyckeln först när alla andra konfigurationsändringar har slutförts säkerställer du att ditt program bara läser in konfigurationen en gång till, vilket upprätthåller konsekvens.

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

Viktigt!

Nyckelvärden registreras inte automatiskt för uppdateringsövervakning. Du måste uttryckligen anropa ConfigureRefresh och sedan registrera nycklar med hjälp av RegisterAll metoden (för att övervaka alla inlästa nycklar) eller Register metoden (för att övervaka en enskild nyckel).

Mer information om uppdateringskonfiguration finns i Självstudie: Använda dynamisk konfiguration i en ASP.NET Core-app.

Funktionsflagga

Funktionsflaggor i Azure App Configuration är ett modernt sätt att styra funktionstillgängligheten i dina program. Till skillnad från vanliga konfigurationsvärden måste funktionsflaggor uttryckligen läsas in med hjälp av UseFeatureFlags metoden. Du kan konfigurera på FeatureFlagOptions för att läsa in specifika funktionsflaggor med hjälp av väljare och ange uppdateringsintervall för funktionsflaggan.

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

Inuti UseFeatureFlags-metoden anropar du Select-metoden för att selektivt läsa in funktionsflaggor. Du kan använda nyckelfilter, etikettfilter och taggfilter för att välja de funktionsflaggor som du vill läsa in. Om ingen Select-metod anropas, laddar UseFeatureFlags som standard in alla funktionsflaggor utan etikett.

Till skillnad från nyckelvärden registreras funktionsflaggor automatiskt för uppdatering utan explicit ConfigureRefresh anrop. Du kan ange den minsta tiden mellan uppdateringar av funktionsflaggor med hjälp av SetRefreshInterval metoden. Standardintervallet för uppdatering är 30 sekunder.

Funktionshantering

Funktionshanteringsbiblioteket är ett sätt att utveckla och exponera programfunktioner baserat på funktionsflaggor. Funktionshanteringsbiblioteket är utformat för att fungera tillsammans med konfigurationsproviderbiblioteket. Installera Microsoft.FeatureManagement-paketet:

dotnet add package Microsoft.FeatureManagement

Du kan anropa AddFeatureManagement för att registrera IVariantFeatureManager och relaterade tjänster i DI-containern. Den här registreringen gör funktionsflaggan tillgänglig i hela programmet via beroendeinmatning.

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

Följande exempel visar hur du använder funktionshanterarens tjänst via beroendeinmatning:

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

Mer information om hur du använder funktionshanteringsbiblioteket finns i snabbstarten för funktionsflaggan.

Key Vault-referens

Azure App Configuration har stöd för att referera till hemligheter som lagras i Azure Key Vault. I App Configuration kan du skapa nycklar som mappar till hemligheter som lagras i Key Vault. Hemligheterna lagras säkert i Key Vault, men kan nås som alla andra konfigurationer när de har lästs in.

Konfigurationsproviderbiblioteket hämtar Key Vault-referenser, precis som för andra nycklar som lagras i App Configuration. Eftersom klienten identifierar nycklarna som Key Vault-referenser har de en unik innehållstyp och klienten ansluter till Key Vault för att hämta sina värden för ditt program.

Ansluta till Key Vault

Du måste anropa ConfigureKeyVault metoden för att konfigurera hur du ansluter till Key Vault. Azure App Configuration-providern erbjuder flera sätt att autentisera och komma åt dina Key Vault-hemligheter.

1. Registrera `SecretClient` instans

Du kan registrera angivna SecretClient instanser för att hantera nyckelvalvreferenser för hemligheter från associerade nyckelvalv.

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. Använd autentiseringsuppgifter

Du kan ange de autentiseringsuppgifter som används för att autentisera till nyckelvalv som inte har någon registrerad 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. Använd anpassad hemlighetslösare

Du kan också anropa SetSecretResolver för att lägga till en anpassad hemlighetslösare som används när ingen registrerad SecretClient är tillgänglig eller om den angivna autentiseringsuppgiften inte kan autentiseras till Key Vault. Den här metoden accepterar en delegatfunktion som löser en Key Vault-URI till ett hemligt värde. I följande exempel visas hur du använder en hemlig lösning som hämtar en hemlighet från miljövariabler under utveckling och använder återställningsvärden när den inte hämtar hemligheten från 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");
                }
            });
        });
});

Anmärkning

När du löser Key Vault-referenser följer providern den här ordningen:

Registrerade SecretClient instanser
Standardautentiseringsuppgifter
Anpassad hemlighetslösare

Viktigt!

Om ditt program läser in nyckelvärden som innehåller Key Vault-referenser utan korrekt Key Vault-konfiguration genereras ett undantag vid start. Kontrollera att du har konfigurerat key vault-åtkomst eller hemlig lösning korrekt.

Tips/Råd

Du kan använda en anpassad hemlighetslösare för att hantera fall där Key Vault-referenser oavsiktligt läggs till i appkonfigurationsarkivet. Matcharen kan tillhandahålla ersättningsvärden, logga varningar eller hantera avsaknaden av korrekta autentiseringsuppgifter på ett smidigt sätt för att få åtkomst till Key Vault, i stället för att slänga undantag.

Hemlig uppdatering av Key Vault

Med Azure App Configuration kan du konfigurera hemliga uppdateringsintervall oberoende av konfigurationsuppdateringscykeln. Detta är viktigt för säkerheten eftersom även om Key Vault-referens-URI:n i App Configuration förblir oförändrad, kan den underliggande hemligheten i Key Vault roteras som en del av dina säkerhetsrutiner.

Konfigurera metoden för att säkerställa att programmet alltid använder de senaste hemliga värdena SetSecretRefreshInterval . Detta tvingar providern att hämta nya hemliga värden från Key Vault när:

Programmet anropar IConfigurationRefresher.TryRefreshAsync
Det konfigurerade uppdateringsintervallet för hemligheten har förflutit

Den här mekanismen fungerar även när inga ändringar identifieras i appkonfigurationsarkivet, vilket säkerställer att programmet förblir synkroniserat med roterade hemligheter.

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

Mer information om hur du använder Key Vault-referens finns i Självstudie: Använda Key Vault-referenser i en ASP.NET Core-app.

Ögonblicksbild

Ögonblicksbild är en namngiven, oföränderlig delmängd av ett appkonfigurationsarkivs nyckelvärden. De nyckelvärden som utgör en ögonblicksbild väljs under skapandetiden genom användning av nyckel- och etikettfilter. När en ögonblicksbild har skapats kommer nyckelvärdena inom garanterat att förbli oförändrade.

Du kan anropa SelectSnapshot för att läsa in nyckelvärden från en ögonblicksbild.

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

Information om hur du använder ögonblicksbilder finns i Skapa och använda ögonblicksbilder.

Referens för ögonblicksbild

En referens för ögonblicksbilder är en konfigurationsinställning som refererar till en ögonblicksbild i samma App Configuration Store. När den läses in löser providern den och lägger till alla nyckelvärden från ögonblicksbilden. Med hjälp av referenserna för ögonblicksbilder kan du växla mellan ögonblicksbilder vid körning, till skillnad från SelectSnapshot("..."), vilket kräver kodändringar och/eller omstarter för att växla till en ny ögonblicksbild.

Anmärkning

Om du vill använda referenserna för ögonblicksbilder använder du version 8.4.0 eller senare av Microsoft.Extensions.Configuration.AzureAppConfiguration.

Startförsök igen

Konfigurationsinläsning är en kritisk operation under programstarten. För att säkerställa tillförlitlighet implementerar Azure App Configuration-providern en robust återförsöksmekanism under den första konfigurationsbelastningen. Detta skyddar ditt program från tillfälliga nätverksproblem som annars kan förhindra lyckad start.

Du kan anpassa det här beteendet med hjälp av ConfigureStartupOptions metoden:

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

Geo-replikering

Information om hur du använder geo-replikering finns i Aktivera geo-replikering.

Distribuerad spårning

Azure App Configuration .NET-providern innehåller inbyggt stöd för distribuerad spårning, så att du kan övervaka och felsöka konfigurationsåtgärder i hela programmet. Providern exponerar ett ActivitySource med namnet "Microsoft.Extensions.Configuration.AzureAppConfiguration" som initierar Activity för nyckelåtgärder som att ladda in konfiguration och uppdatering av konfigurationen.

I följande exempel visas hur du konfigurerar OpenTelemetry för att samla in och övervaka distribuerade spårningar som genereras av konfigurationsprovidern:

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

Mer information om OpenTelemetry i .NET finns i OpenTelemetry .NET-dokumentationen.

Hälsokontroll

Azure App Configuration .NET-providern stöder .NET-apphälsokontroller. För att aktivera hälsokontroller kan du anropa AddAzureAppConfiguration()-metoden på IHealthChecksBuilder, vilket kommer att lägga till en IHealthCheck med ett standardregistreringsnamn av "Microsoft.Extensions.Configuration.AzureAppConfiguration".

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

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

.NET-providern betraktas som felaktig när det senaste inläsnings- eller uppdateringsförsöket misslyckades.

Mer information om hälsokontroller i .NET finns i dokumentationen för .NET-hälsoövervakning.

Nästa steg

Om du vill lära dig hur du använder .NET-konfigurationsprovidern fortsätter du till följande handledning.

Aktivera dynamisk konfiguration i en ASP.NET webbapp

Feedback

Var den här sidan till hjälp?

Last updated on 2025-09-22

Dela via

.NET-konfigurationsprovider

Läs in konfiguration

Använda konfiguration

1. Direkt åtkomst

2. Beroendeinmatning med IConfiguration

3. Alternativmönster för tydligt typad konfiguration

Hantering av JSON-innehållstyp

Läs in specifika nyckelvärden med hjälp av väljare

Nyckelfilter

Etikettfilter

Filter för taggar

Trimma prefix från nycklar

Mappning av konfigurationsinställning

Uppdatering av konfiguration

Utlös uppdatering

1. Beroendeinmatning

ASP.NET Core-applikationer

Bakgrundstjänster

2. Direkt åtkomst

Uppdatera sentinelnyckeln

Funktionsflagga

Funktionshantering

Key Vault-referens

Ansluta till Key Vault

1. Registrera SecretClient instans

2. Använd autentiseringsuppgifter

3. Använd anpassad hemlighetslösare

Hemlig uppdatering av Key Vault

Ögonblicksbild

Referens för ögonblicksbild

Startförsök igen

Geo-replikering

Distribuerad spårning

Hälsokontroll

Nästa steg

Feedback

Ytterligare resurser

1. Registrera `SecretClient` instans