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.

Carica configurazione della rete

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

Chiamare il metodo di estensione AddAzureAppConfiguration su IConfigurationBuilder per aggiungere Configurazione app di Azure come provider di configurazione dell’applicazione.

La raccolta dei provider di configurazione implementa un Modello di opzioni e un Modello generatore combinati per fornire un modo chiaro e dichiarativo per configurare 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 di 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. Inserimento 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 una 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 viene letta una coppia chiave-valore con il tipo di contenuto "application/json", il provider di configurazione la rendere flat in singole impostazioni all'interno di IConfiguration. Per altre informazioni, vedere Usare il tipo di contenuto per archiviare i valori di chiave JSON in Configurazione app.

Annotazioni

A partire dalla versione 8.4.0 di Microsoft.Extensions.Configuration.AzureAppConfiguration, il provider di configurazione consente di inserire commenti, come definito in (JSONC), nelle coppie chiave-valore con contenuto di tipo application/json.

Caricare coppie chiave-valore specifiche usando selettori

Per impostazione predefinita, il provider di configurazione carica tutte le coppie chiave-valore senza alcuna etichetta da Configurazione app. È 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 la corrispondenza di prefissi di caratteri jolly con filtri separati da virgola nella stessa chiamata Select. 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 carattere di escape tramite un’altra barra rovesciata (\).

Filtri per i 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 caratteri riservati e devono essere preceduti da una barra rovesciata se usati in un filtro tag.

Rimuovere 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 servizio IConfigurationRefreshProvider al contenitore DI, che consente di accedere ai processi di aggiornamento di tutte le origini di 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 il processo di aggiornamento direttamente da queste opzioni:

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.

Aggiornamento della 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 delle coppie chiave-valore, i flag di funzionalità vengono registrati automaticamente per il processo di aggiornamento senza richiedere una chiamata ConfigureRefresh esplicita. È 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 dei 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 disponibili i flag di funzionalità in tutta l'applicazione tramite l'inserimento 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à, vedere l’avvio rapido al flag di funzionalità.

Telemetria dei segnali di funzionalità

Quando i dati di telemetria dei flag di funzionalità sono abilitati, il provider di Configurazione app di Azure inserisce proprietà aggiuntive nei dati di telemetria dei flag di funzionalità. Queste proprietà forniscono più contesto sul flag di funzionalità e sulla relativa valutazione:

  • AllocationID: identificatore univoco che rappresenta lo stato dell'allocazione del flag di funzionalità.
  • ETag: L'ETag corrente per il feature flag.
  • FeatureFlagReference: riferimento al flag di funzionalità nel formato di <your_store_endpoint>kv/<feature_flag_key>. Quando è presente un'etichetta, il riferimento lo include come parametro di query: <your_store_endpoint>kv/<feature_flag_key>?label=<feature_flag_label>.

Lo schema completo è disponibile nella definizione dello schema di eventi di valutazione delle funzionalità di Configurazione app. Per ulteriori informazioni su come utilizzare la telemetria dei flag di funzionalità, consultare la guida abilitare la telemetria per i flag di funzionalità.

Riferimento Key Vault

Configurazione app di Azure 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 è possibile accedervi come qualsiasi altra configurazione dopo il caricamento.

La libreria dei 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 SecretClient specificate da usare 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 usate per l'autenticazione agli insiemi di credenziali delle chiavi che non hanno un SecretClient registrato.

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 SecretClient registrate
  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 dei segreti di Key Vault

Configurazione app di Azure 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 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 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.

Snapshot

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. Una volta creato uno snapshot, è garantito che i valori chiave in esso contenuti rimarranno 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.

Informazioni di riferimento sullo snapshot

Un riferimento allo snapshot è un'impostazione di configurazione che fa riferimento a uno snapshot nello stesso archivio di Configurazione app. Quando viene caricato, il provider lo risolve e aggiunge tutte le coppie chiave-valore dallo snapshot. L'uso di riferimenti snapshot consente di passare da uno snapshot all'altro in fase di esecuzione, a differenza SelectSnapshot("...")di , che richiede modifiche al codice e/o riavvii per passare a un nuovo snapshot.

Annotazioni

Per usare i riferimenti snapshot, usare la versione 8.4.0 o successiva di Microsoft.Extensions.Configuration.AzureAppConfiguration.

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.

Controllo integrità

Il provider .NET di Configurazione app di Azure supporta i controlli di integrità delle app .NET. Per abilitare i controlli di integrità, è possibile chiamare il metodo AddAzureAppConfiguration() in IHealthChecksBuilder, che consente di aggiungere un elemento IHealthCheck con il nome di registrazione predefinito di "Microsoft.Extensions.Configuration.AzureAppConfiguration".

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

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

Il provider .NET verrà considerato non integro quando l'ultimo tentativo di caricamento o aggiornamento avrà esisto negativo.

Per altre informazioni sui controlli di integrità in .NET, vedere la documentazione sul monitoraggio dello stato di integrità di .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

  • Last updated on