Condividi tramite

Provider di configurazione .NET

Microsoft.Extensions.Configuration.AzureAppConfiguration

Configurazione app di Azure è un servizio gestito che consente agli sviluppatori di centralizzare le configurazioni delle loro applicazioni in modo semplice e sicuro. La libreria del provider di configurazione .NET consente di caricare la configurazione da un archivio di Configurazione app di Azure in modo gestito. Questa libreria client aggiunge funzionalità aggiuntive su Azure SDK per .NET.

Configurazione del caricamento

Il provider di configurazione .NET di Azure App Configuration si integra con il sistema di configurazione .NET, facilitando il caricamento dei valori di configurazione dall'archivio di Azure App Configuration. È possibile aggiungere il provider durante l'avvio dell'applicazione e usarlo insieme ad altre origini di configurazione.

Per usare il provider di configurazione .NET, installare il pacchetto:

dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration

Si chiama il metodo di estensione AddAzureAppConfiguration su IConfigurationBuilder per aggiungere la Configurazione app di Azure come provider di configurazione della tua applicazione.

La libreria del provider di configurazione implementa la combinazione dei modelli Pattern delle Opzioni e Pattern Builder per fornire un modo dichiarativo pulito per configurare il AzureAppConfigurationOptions. Il AddAzureAppConfiguration metodo accetta un Action<AzureAppConfigurationOptions> parametro delegato che consente di configurare il provider tramite un'API Fluent.

Per connettersi all'archivio Configurazione app di Azure, chiamare il metodo Connect sull'istanza AzureAppConfigurationOptions, che restituisce lo stesso oggetto di opzioni per consentire il concatenamento dei metodi.

È possibile usare il DefaultAzureCredential, o qualsiasi altra implementazione delle credenziali del token, per eseguire l'autenticazione nell'archivio di configurazione dell'applicazione. Seguire le istruzioni per assegnare le credenziali al ruolo lettore dati Configurazione app.

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

Annotazioni

In un'applicazione ASP.NET Core o in un servizio in background è possibile chiamare AddAzureAppConfiguration su builder.Configuration.

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

Utilizzare la configurazione

Dopo aver aggiunto il provider di Configurazione app di Azure, è possibile accedere ai valori di configurazione in diversi modi:

1. Accesso diretto

L'approccio più semplice consiste nel recuperare i valori direttamente dall'istanza IConfiguration :

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

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

2. Iniezione delle dipendenze con IConfiguration

Nei servizi o nei controller è possibile inserire e usare direttamente l'interfaccia 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. Modello di opzioni per la configurazione fortemente tipizzata

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

Per altre informazioni sul modello di opzioni in .NET, vedere la documentazione.

Gestione dei tipi di contenuto JSON

È possibile creare valori chiave JSON in Configurazione app. Quando una chiave-valore con il tipo di contenuto "application/json" viene letta, il provider di configurazione la appiattirà in impostazioni individuali all'interno di IConfiguration. Per altre informazioni, vedere Usare il tipo di contenuto per archiviare i valori di chiave JSON in Configurazione app.

Caricare valori chiave specifici usando selettori

Per impostazione predefinita, il provider di configurazione carica tutte le coppie chiave-valore senza alcuna etichetta da App Configuration. È possibile caricare in modo selettivo i valori chiave dall'archivio di Configurazione app chiamando il Select metodo su 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" })
});

Il Select metodo accetta tre parametri. Il primo parametro è un filtro chiave che specifica quali chiavi caricare, il secondo parametro è un filtro di etichetta che specifica quali valori chiave caricare con etichette specifiche e il terzo parametro specifica una raccolta di filtri di tag che devono essere presenti su un valore chiave da caricare.

Annotazioni

Quando più Select chiamate includono chiavi sovrapposte, le chiamate successive hanno la precedenza su quelle precedenti.

Filtro chiavi

Il parametro del filtro delle chiavi determina quali chiavi di configurazione includere:

  • Corrispondenza esatta: l'uso di una stringa specifica corrisponde solo alle chiavi che corrispondono esattamente al filtro.
  • Corrispondenza prefisso: l'aggiunta di un asterisco (*) alla fine crea un filtro di prefisso (ad esempio, App:Settings:* carica tutte le chiavi a partire da "App:Settings:").
  • Selezione di più tasti: l'uso di una virgola (,) consente la selezione di più chiavi esplicite (ad esempio, Key1,Key2,Key3).
  • Caratteri riservati: i caratteri asterischi (), la virgola (*,) e la barra rovesciata (\) sono riservati e devono essere preceduti da una barra rovesciata se usata nei nomi delle chiavi (ad esempio, il filtro a\\b\,\*c* della chiave restituisce tutti i valori chiave la cui chiave inizia con a\b,*c.).

Annotazioni

Non è possibile combinare i prefissi con caratteri jolly corrispondenti ai filtri delimitati da virgole nella stessa Select chiamata. Ad esempio, abc*,def non è supportato, ma è possibile effettuare chiamate separate Select con abc* e def.

Filtro per etichette

Il parametro filtro etichetta seleziona i valori chiave con un'etichetta specifica. Se non specificato, viene utilizzato il valore predefinito LabelFilter.Null .

Annotazioni

I caratteri asterisco (*) e virgola (,) non sono supportati per il filtro etichette. Il carattere barra rovesciata (\) è riservato e deve essere preceduto da un'altra barra rovesciata (\).

Filtri tag

Il parametro dei filtri tag seleziona i valori chiave con tag specifici. Un valore chiave viene caricato solo se contiene tutti i tag e i valori corrispondenti specificati nei filtri. Per specificare un valore Null per un tag, è possibile usare il valore TagValue.Null predefinito.

Annotazioni

L'asterisco (*), la virgola (,) e la barra rovesciata (\) sono riservati e devono essere preceduti da una barra rovesciata se usati in un filtro tag.

Tagliare il prefisso dalle chiavi

Quando si caricano valori di configurazione con prefissi specifici, è possibile usare il TrimKeyPrefix metodo per rimuovere tali prefissi dalle chiavi nella configurazione. In questo modo vengono create chiavi di configurazione più pulite nell'applicazione mantenendo l'organizzazione nell'archivio di Configurazione app.

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

Ad esempio, se l'archivio di Configurazione app contiene una chiave denominata TestApp:Settings:Message, sarà accessibile nell'applicazione come Settings:Message dopo aver tagliato il TestApp: prefisso.

Mappatura delle impostazioni di configurazione

Quando si caricano valori chiave da Configurazione app di Azure, il provider li recupera prima come oggetti ConfigurationSetting per poi aggiungerli al sistema di configurazione .NET. L'API Map consente di trasformare queste impostazioni durante questa pipeline, consentendo di controllare la modalità di visualizzazione delle configurazioni nell'applicazione.

Il Map metodo accetta una funzione delegato che riceve un ConfigurationSetting oggetto , consente di modificarlo e restituisce un oggetto ValueTask<ConfigurationSetting>. Ciò è particolarmente utile per le trasformazioni dei nomi chiave o la formattazione dei valori in base alle condizioni di runtime.

L'esempio seguente illustra l'uso dell'API Map per sostituire i caratteri di sottolineatura doppia (__) con i due punti (:) nelle chiavi di configurazione. Questa trasformazione mantiene la struttura gerarchica prevista dalla configurazione .NET quando le chiavi devono usare caratteri alternativi in Configurazione app:

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

Suggerimento

L'operazione Map viene applicata a tutte le impostazioni di configurazione recuperate da Configurazione app, quindi assicurarsi che la logica di trasformazione gestisca correttamente tutti i formati di chiave possibili.

Aggiornamento della configurazione

La configurazione dell'aggiornamento consente all'applicazione di eseguire il pull dei valori più recenti dall'archivio di Configurazione app senza dover riavviare. È possibile chiamare il metodo ConfigureRefresh per configurare l'aggiornamento chiave-valore.

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

All'interno del metodo ConfigureRefresh, si chiama il metodo RegisterAll per istruire il provider di configurazione dell'app a ricaricare la configurazione ogniqualvolta rileva una modifica in uno dei valori chiave selezionati (quelli che iniziano con TestApp: e non hanno etichetta).

È possibile aggiungere una chiamata al SetRefreshInterval metodo per specificare il tempo minimo tra gli aggiornamenti della configurazione. Se non è impostato, l'intervallo di aggiornamento predefinito è di 30 secondi.

Attivare l'aggiornamento

Per attivare l'aggiornamento, è necessario chiamare il metodo TryRefreshAsync di IConfigurationRefresher. Configurazione app di Azure offre diversi modelli per l'implementazione a seconda dell'architettura dell'applicazione.

1. Iniezione di dipendenze

Per applicazioni che utilizzano Dependency Injection (inclusi ASP.NET Core e servizi in background), registrare il servizio di aggiornamento:

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() aggiunge il IConfigurationRefreshProvider servizio al contenitore DI, consentendo di accedere agli aggiornamenti di tutte le origini della Configurazione app di Azure nella configurazione dell'applicazione.

Applicazioni ASP.NET Core

Per ASP.NET applicazioni Core, è possibile usare il pacchetto per ottenere un Microsoft.Azure.AppConfiguration.AspNetCoreaggiornamento della configurazione basato su richiesta con un middleware predefinito.

dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore

Dopo aver registrato il servizio, chiamare il UseAzureAppConfiguration per aggiungere il AzureAppConfigurationRefreshMiddleware alla pipeline dell'applicazione per aggiornare automaticamente la configurazione con le richieste in ingresso.

...

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

Il AzureAppConfigurationRefreshMiddleware esegue automaticamente la verifica delle modifiche di configurazione all'intervallo di aggiornamento stabilito. Questo approccio è efficiente perché viene aggiornato solo quando vengono soddisfatte entrambe le condizioni: viene ricevuta una richiesta HTTP e l'intervallo di aggiornamento è trascorso.

Servizi in background

Per i servizi in background, è possibile inserire il IConfigurationRefresherProvider servizio e aggiornare manualmente ognuno degli aggiornamenti registrati.

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. Accesso diretto

Per le applicazioni che non usano l'inserimento delle dipendenze, è possibile ottenere l'aggiornamento direttamente dalle opzioni seguenti:

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

Annotazioni

Anche se la chiamata di aggiornamento non riesce per qualsiasi motivo, l'applicazione continua a usare la configurazione memorizzata nella cache. Un altro tentativo viene eseguito dopo un breve periodo in base all'attività dell'applicazione. La chiamata a refresh è un no-op che avviene prima del termine dell'intervallo di aggiornamento configurato, quindi l'impatto sulle prestazioni è trascurabile anche se viene effettuata di frequente.

Aggiornare la chiave sentinel

Una chiave sentinel è una chiave che si aggiorna dopo aver completato la modifica di tutte le altre chiavi. Il provider di configurazione monitora la chiave sentinel anziché tutti i valori chiave selezionati. Quando viene rilevata una modifica, l'app aggiorna tutti i valori di configurazione.

Questo approccio è utile quando si aggiornano più valori chiave. Aggiornando la chiave sentinel solo dopo il completamento di tutte le altre modifiche di configurazione, assicurarsi che l'applicazione ricarica la configurazione una sola volta, mantenendo la coerenza.

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

Importante

I valori chiave non vengono registrati automaticamente per il monitoraggio dell'aggiornamento. È necessario chiamare ConfigureRefresh in modo esplicito e quindi registrare le chiavi usando il RegisterAll metodo (per monitorare tutte le chiavi caricate) o il Register metodo (per monitorare una singola chiave).

Per altre informazioni sulla configurazione dell'aggiornamento, vedere Esercitazione: Usare la configurazione dinamica in un'app ASP.NET Core.

Indicatore di funzionalità

I flag di funzionalità in Configurazione app di Azure offrono un modo moderno per controllare la disponibilità delle funzionalità nelle applicazioni. A differenza dei valori di configurazione normali, i flag di funzionalità devono essere caricati in modo esplicito usando il UseFeatureFlags metodo . È possibile configurare su FeatureFlagOptions per caricare flag di funzionalità specifici usando selettori e impostare l'intervallo di aggiornamento dei flag di funzionalità.

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

All'interno del metodo UseFeatureFlags, si chiama il metodo Select per caricare in modo selettivo i flag di funzionalità. È possibile usare filtri di chiave, filtri di etichette e filtri di tag per selezionare i flag di funzionalità da caricare. Se non viene chiamato alcun Select metodo, UseFeatureFlags carica di default tutte le bandiere delle funzionalità senza etichetta.

A differenza dei key-value, i flag di funzionalità sono registrati automaticamente per il refresh senza richiedere una chiamata esplicita di ConfigureRefresh. È possibile specificare il tempo minimo tra gli aggiornamenti dei flag di funzionalità tramite il SetRefreshInterval metodo . L'intervallo di aggiornamento predefinito è 30 secondi.

Gestione delle funzionalità

La libreria di gestione delle funzionalità consente di sviluppare ed esporre le funzionalità dell'applicazione in base ai flag di funzionalità. La libreria di gestione delle funzionalità è progettata per funzionare insieme alla libreria del provider di configurazione. Installare il pacchetto Microsoft.FeatureManagement:

dotnet add package Microsoft.FeatureManagement

È possibile chiamare AddFeatureManagement per registrare IVariantFeatureManager e i servizi correlati nel contenitore DI. Questa registrazione rende disponibile la funzionalità flag in tutta l'applicazione tramite l'iniezione delle dipendenze.

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

L'esempio seguente illustra come usare il servizio di gestione delle funzionalità tramite l'inserimento delle dipendenze:

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

Per altre informazioni su come usare la libreria di gestione delle funzionalità, consultare la guida introduttiva al flag di funzionalità.

Informazioni di riferimento su Key Vault

app Azure Configurazione supporta il riferimento ai segreti archiviati in Azure Key Vault. In Configurazione app è possibile creare chiavi mappate ai segreti archiviati in Key Vault. I segreti vengono archiviati in modo sicuro in Key Vault, ma possono essere accessibili come qualsiasi altra configurazione dopo il caricamento.

La libreria del provider di configurazione recupera i riferimenti a Key Vault, proprio come per qualsiasi altra chiave archiviata in Configurazione app. Poiché il client riconosce le chiavi come riferimenti a Key Vault, ha un tipo di contenuto univoco e il client si connette a Key Vault per recuperare i valori per l'applicazione.

Connettersi a Key Vault

È necessario chiamare il ConfigureKeyVault metodo per configurare la connessione a Key Vault. Il provider di Configurazione app di Azure offre diversi modi per autenticare e accedere ai segreti di Key Vault.

1. Registrare l'istanza SecretClient

È possibile registrare istanze specificate SecretClient da utilizzare per risolvere i riferimenti all'insieme di credenziali delle chiavi per i segreti dall'insieme di credenziali delle chiavi associato.

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. Utilizzare le credenziali

È possibile impostare le credenziali utilizzate per l'autenticazione a key vaults che non hanno registrazione 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. Usare il sistema di risoluzione dei segreti personalizzato

È anche possibile chiamare SetSecretResolver per aggiungere un resolver segreto personalizzato che viene usato quando non è disponibile alcuna registrazione SecretClient o la credenziale fornita non riesce ad eseguire l'autenticazione in Key Vault. Questo metodo accetta una funzione delegato che risolve un URI di Key Vault in un valore segreto. L'esempio seguente illustra l'uso di un resolver segreto che recupera un segreto dalle variabili di ambiente in fase di sviluppo e usa i valori di fallback quando non riesce a ottenere il segreto da 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");
                }
            });
        });
});

Annotazioni

Quando si risolvono i riferimenti a Key Vault, il provider segue quest'ordine:

  1. Istanze registrate SecretClient
  2. Credenziali predefinite
  3. Sistema di risoluzione dei segreti personalizzato

Importante

Se l'applicazione carica valori chiave contenenti riferimenti a Key Vault senza una configurazione appropriata di Key Vault, verrà generata un'eccezione all'avvio. Assicurarsi di aver configurato correttamente l'accesso a Key Vault o il resolver segreto.

Suggerimento

È possibile usare un sistema di risoluzione dei segreti personalizzato per gestire i casi in cui i riferimenti a Key Vault vengono aggiunti accidentalmente all'archivio di Configurazione app. Il sistema di risoluzione può fornire valori di fallback, registrare avvisi o gestire in modo adeguato la mancanza di credenziali adeguate per accedere a Key Vault anziché generare eccezioni.

Aggiornamento del segreto di Key Vault

Azure App Configuration consente di configurare gli intervalli di aggiornamento dei segreti indipendentemente dal ciclo di aggiornamento della configurazione. Questo è fondamentale per la sicurezza perché, mentre l'URI di riferimento di Key Vault in Configurazione app rimane invariato, il segreto sottostante in Key Vault potrebbe essere ruotato come parte delle procedure di sicurezza.

Per assicurarsi che l'applicazione usi sempre i valori segreti più aggiornati, configurare il SetSecretRefreshInterval metodo . In questo modo, il provider deve recuperare nuovi valori segreti da Key Vault quando:

  • L'applicazione chiama IConfigurationRefresher.TryRefreshAsync
  • L'intervallo di aggiornamento configurato per il segreto è trascorso

Questo meccanismo funziona anche quando non vengono rilevate modifiche nell'archivio di Configurazione dell'app, garantendo che l'applicazione rimanga sincronizzata con i segreti aggiornati.

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

Per ulteriori informazioni su come utilizzare i riferimenti al Key Vault, vedere Esercitazione: Usare i riferimenti a Key Vault in un'app ASP.NET Core.

Istantanea

Snapshot è un subset non modificabile denominato dei valori chiave di un archivio di Configurazione app. I valori chiave che costituiscono uno snapshot vengono scelti durante la fase di creazione tramite l'utilizzo dei filtri di chiave e etichetta. Dopo aver creato uno snapshot, i valori chiave all'interno di sono garantiti per rimanere invariati.

È possibile chiamare SelectSnapshot per caricare i valori chiave da uno snapshot.

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

Per informazioni sull'uso degli snapshot, vedere Creare e usare snapshot.

Tentativo di avvio

Il caricamento della configurazione è un'operazione di percorso fondamentale durante l'avvio dell'applicazione. Per garantire l'affidabilità, il provider di Configurazione app di Azure implementa un meccanismo di ripetizione affidabile durante il caricamento iniziale della configurazione. Ciò consente di proteggere l'applicazione da problemi di rete temporanei che potrebbero altrimenti impedire l'avvio riuscito.

È possibile personalizzare questo comportamento usando il ConfigureStartupOptions metodo :

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

Replica geografica

Per informazioni sull'uso della replica geografica, vedere Abilitare la replica geografica.

Tracciamento distribuito

Il provider .NET di App Configuration di Azure include il supporto predefinito per il tracciamento distribuito, consentendo di monitorare e risolvere i problemi delle operazioni di configurazione nell'applicazione. Il provider espone un ActivitySource denominato "Microsoft.Extensions.Configuration.AzureAppConfiguration" che avvia Activity per operazioni chiave come il caricamento e l'aggiornamento della configurazione.

L'esempio seguente illustra come configurare OpenTelemetry per acquisire e monitorare le tracce distribuite generate dal provider di configurazione:

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

Per altre informazioni su OpenTelemetry in .NET, vedere la documentazione di OpenTelemetry .NET.

Passaggi successivi

Per informazioni su come usare il provider di configurazione .NET, continuare con l'esercitazione seguente.

Abilitare la configurazione dinamica in un'app Web ASP.NET