Esercitazione: Usare la configurazione dinamica in un'app .NET

La libreria del provider .NET di Configurazione app supporta l'aggiornamento della configurazione su richiesta senza causare il riavvio di un'applicazione. Questa esercitazione illustra come implementare gli aggiornamenti della configurazione dinamica nel codice. Si basa sull'app introdotta nell'avvio rapido. Prima di continuare, è necessario completare Creare un'app .NET con App Configuration.

Per completare i passaggi riportati in questa esercitazione, è possibile usare qualsiasi editor di codice. Visual Studio Code è un'ottima opzione ed è disponibile per le piattaforme Windows, macOS e Linux.

In questa esercitazione si apprenderà come:

Configura la tua app .NET per aggiornare la sua configurazione per rispondere alle modifiche in un archivio di configurazione dell'app.
Utilizzare la configurazione più recente nell'applicazione.

Prerequisiti

Se non si ha un account Azure, creare un account gratuito prima di iniziare.

Completare l'avvio rapido Creare un'app .NET con Configurazione app.

Aggiornamento della configurazione guidata dall'attività

Aprire Program.cs e aggiornare il file con il codice seguente. È possibile connettersi a App Configuration usando Microsoft Entra ID (scelta consigliata) o una stringa di connessione. Il frammento di codice seguente illustra l'uso dell'ID Microsoft Entra.

Usare DefaultAzureCredential per eseguire l'autenticazione nell'archivio di Configurazione app. Durante il completamento dell'avvio rapido elencato nei prerequisiti, è già stato assegnato il ruolo Lettore dati di configurazione app.

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

IConfiguration _configuration = null;
IConfigurationRefresher _refresher = null;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    string endpoint = Environment.GetEnvironmentVariable("Endpoint"); 
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())            
           // Load the key-value with key "TestApp:Settings:Message" and no label
           .Select("TestApp:Settings:Message")
           // Reload configuration if any selected key-values have changed.
           .ConfigureRefresh(refresh =>
           {
               refresh.RegisterAll()
                      .SetRefreshInterval(TimeSpan.FromSeconds(10));
           })

    _refresher = options.GetRefresher();
});

_configuration = builder.Build();

Console.WriteLine(_configuration["TestApp:Settings:Message"] ?? "Hello world!");

// Wait for the user to press Enter
Console.ReadLine();

if (_refresher != null)
{
    await _refresher.TryRefreshAsync();
    Console.WriteLine(_configuration["TestApp:Settings:Message"] ?? "Hello world!");

}

All'interno del ConfigureRefresh metodo, chiami il RegisterAll metodo per indicare al provider di configurazione dell'app di ricaricare l'intera configurazione ogni volta che rileva una modifica in uno dei valori chiave selezionati, ad esempio, solo TestApp:Settings:Message. Per altre informazioni sul monitoraggio delle modifiche alla configurazione, vedere Procedure consigliate per l'aggiornamento della configurazione.

Il SetRefreshInterval metodo specifica il tempo minimo che deve trascorrere prima che venga effettuata una nuova richiesta a Configurazione app per verificare la presenza di eventuali modifiche alla configurazione. In questo esempio si esegue l'override dell'ora di scadenza predefinita di 30 secondi, specificando invece un'ora di 10 secondi a scopo dimostrativo.

La chiamata al ConfigureRefresh metodo da solo non causerà l'aggiornamento automatico della configurazione. Chiamare il TryRefreshAsync metodo dall'interfaccia IConfigurationRefresher per attivare un aggiornamento. Questa progettazione consiste nell'evitare richieste inviate a Configurazione app anche quando l'applicazione è inattiva. Dovresti includere la chiamata TryRefreshAsync nel punto in cui consideri l'applicazione attiva. Ad esempio, può essere quando si elabora un messaggio in arrivo, un ordine o un'iterazione di un'attività complessa. Può anche essere in un timer se l'applicazione è attiva tutto il tempo. In questo esempio si chiama TryRefreshAsync ogni volta che si preme INVIO. Anche se la chiamata TryRefreshAsync non riesce per qualsiasi motivo, l'applicazione continua a usare la configurazione memorizzata nella cache. Viene eseguito un altro tentativo quando l'intervallo di aggiornamento configurato è passato e la TryRefreshAsync chiamata viene attivata di nuovo dall'attività dell'applicazione. La chiamata a TryRefreshAsync è un no-op prima che l'intervallo di aggiornamento configurato sia trascorso, quindi l'impatto sulle prestazioni è minimo, anche se viene effettuata di frequente.

Aggiornamento della configurazione tramite l'inserimento dipendenza

Nel codice precedente si salva manualmente un'istanza di IConfigurationRefresher per richiamare TryRefreshAsync. In alternativa, se si usa l'inserimento dipendenza per risolvere i servizi, è possibile fare riferimento ai passi seguenti.

Registrare i servizi richiesti di configurazione delle app richiamando AddAzureAppConfiguration su IServiceCollection.

Aggiungere il codice seguente per Program.cs.
```
// Existing code in Program.cs
// ... ...

// Add Azure App Configuration services to IServiceCollection
builder.Services.AddAzureAppConfiguration();
```

Aggiornare la configurazione risolvendo un'istanza di IConfigurationRefresherProvider dalla raccolta di servizi e richiamando TryRefreshAsync in ognuno dei relativi aggiornamenti.

class SampleConfigRefresher
{
    private readonly IEnumerable<IConfigurationRefresher> _refreshers = null;

    public SampleConfigRefresher(IConfigurationRefresherProvider refresherProvider)
    {
        _refreshers = refresherProvider.Refreshers;
    }

    public async Task RefreshConfiguration()
    {
        foreach (var refresher in _refreshers)
        {
            _ = refresher.TryRefreshAsync();
        }
    }
}

Compilare ed eseguire l'app in locale

Imposta una variabile di ambiente denominata Endpoint all'endpoint del tuo archivio Configurazione app, trovato nella sezione Panoramica del portale Azure.

Se si usa il prompt dei comandi di Windows, eseguire il comando seguente e riavviare il prompt per rendere effettiva la modifica:
```
setx Endpoint "<endpoint-of-your-app-configuration-store>"
```
Se si usa PowerShell, eseguire il comando seguente:
```
$Env:Endpoint = "<endpoint-of-your-app-configuration-store>"
```
Se si usa macOS o Linux, eseguire il comando seguente:
```
export Endpoint='<endpoint-of-your-app-configuration-store>'
```
Eseguire il comando seguente per compilare l'app console:
```
 dotnet build
```
Al termine della compilazione, eseguire questo comando per eseguire l'app Web in locale:
```
 dotnet run
```
Accedere al portale di Azure. Selezionare Tutte le risorse e selezionare l'istanza dell'archivio di Configurazione app creata nell'avvio rapido.
Selezionare Esplora configurazione e aggiornare i valori delle chiavi seguenti:

Chiave Valore

TestApp:Impostazioni:Messaggio Dati di Configurazione app di Azure - Aggiornato
Premere INVIO per attivare un aggiornamento e stampare il valore aggiornato nel prompt dei comandi o nella finestra di PowerShell.

Annotazioni

Poiché l'intervallo di aggiornamento è stato impostato su 10 secondi usando il SetRefreshInterval metodo durante la specifica della configurazione per l'operazione di aggiornamento, il valore per l'impostazione di configurazione verrà aggiornato solo se sono trascorsi almeno 10 secondi dall'ultimo aggiornamento per tale impostazione.

Chiave	Valore
TestApp:Impostazioni:Messaggio	Dati di Configurazione app di Azure - Aggiornato

Registrazione e monitoraggio

I log vengono restituiti all'aggiornamento della configurazione e contengono informazioni dettagliate sui valori chiave recuperati dall'archivio Configurazione app e le modifiche di configurazione apportate all'applicazione. Se si dispone di un'applicazione ASP.NET Core, vedere queste istruzioni per registrazione e monitoraggio in ASP.NET Core. In caso contrario, è possibile abilitare la registrazione usando le istruzioni per la registrazione con Azure SDK.

I log vengono restituiti a diversi livelli di evento. Il livello predefinito è Informational.

Livello evento	Descrizione
Dettagliato	I log includono la chiave e l'etichetta dei valori chiave monitorati dall'applicazione per le modifiche apportate dall'archivio di Configurazione app. Le informazioni includono anche se il valore chiave è stato modificato rispetto a quello già caricato dall'applicazione. Abilitare i log a questo livello per risolvere i problemi dell'applicazione se non è stata apportata una modifica della configurazione come previsto.
Di carattere informativo	I log includono le chiavi delle impostazioni di configurazione aggiornate durante un aggiornamento della configurazione. I valori delle impostazioni di configurazione vengono omessi dal log per evitare perdite di dati sensibili. È possibile monitorare i log a questo livello per assicurarsi che l'applicazione rilevi le modifiche di configurazione previste.
Avvertimento	I log includono errori ed eccezioni che si sono verificati durante l'aggiornamento della configurazione. Le occorrenze occasionali possono essere ignorate perché il provider di configurazione continuerà a usare i dati memorizzati nella cache e tenterà di aggiornare la configurazione la volta successiva. È possibile monitorare i log a questo livello per avvisi ripetitivi che potrebbero indicare potenziali problemi. Ad esempio, è stata ruotata la stringa di connessione ma si è dimenticato di aggiornare l'applicazione.

È possibile abilitare la registrazione a livello di evento Verbose specificando il parametro EventLevel.Verbose, come illustrato nell'esempio seguente. Queste istruzioni si applicano anche a tutti gli altri livelli di evento. Questo esempio abilita anche i log solo per la Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh categoria.

using var listener = new AzureEventSourceListener((eventData, text) =>
{
    if (eventData.EventSource.Name == "Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh")
    {
        Console.WriteLine("[{1}] {0}: {2}", eventData.EventSource.Name, eventData.Level, text);
    }
}, EventLevel.Verbose);

La categoria di registrazione è Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh, che viene visualizzata prima di ogni log. Ecco alcuni log di esempio a ogni livello di evento:

[Verbose] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
Key-value read from App Configuration. Change:'Modified' Key:'ExampleKey' Label:'ExampleLabel' Endpoint:'https://examplestore.azconfig.io'

[Informational] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
Setting updated. Key:'ExampleKey'

[Warning] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
A refresh operation failed while resolving a Key Vault reference.
Key vault error. ErrorCode:'SecretNotFound' Key:'ExampleKey' Label:'ExampleLabel' Etag:'6LaqgBQM9C_Do2XyZa2gAIfj_ArpT52-xWwDSLb2hDo' SecretIdentifier:'https://examplevault.vault.azure.net/secrets/ExampleSecret'

Annotazioni

La registrazione è disponibile se si usa la versione 6.0.0 o successiva di uno dei pacchetti seguenti.

Microsoft.Extensions.Configuration.AzureAppConfiguration
Microsoft.Azure.AppConfiguration.AspNetCore
Microsoft.Azure.AppConfiguration.Functions.Worker

Pulire le risorse

Se non si vuole continuare a usare le risorse create in questo articolo, eliminare il gruppo di risorse creato qui per evitare addebiti.

Importante

L'eliminazione di un gruppo di risorse è irreversibile. Il gruppo di risorse e tutte le risorse in esso contenute vengono eliminati in modo permanente. Assicurarsi di non eliminare accidentalmente il gruppo di risorse o le risorse sbagliate. Se le risorse per questo articolo sono state create in un gruppo di risorse che contiene altre risorse che si vogliono mantenere, eliminare ogni risorsa singolarmente dal rispettivo riquadro anziché eliminare il gruppo di risorse.

Accedere al portale di Azure e selezionare Gruppi di risorse.
Nella casella Filtra per nome immettere il nome del gruppo di risorse.
Nell'elenco dei risultati selezionare il nome del gruppo di risorse per visualizzare una panoramica.
Selezionare Elimina gruppo di risorse.
Verrà chiesto di confermare l'eliminazione del gruppo di risorse. Immettere il nome del gruppo di risorse per confermare e selezionare Elimina.

Dopo qualche istante, il gruppo di risorse e tutte le risorse che contiene vengono eliminati.

Passaggi successivi

In questa esercitazione, hai abilitato l'app .NET per aggiornare dinamicamente le impostazioni di configurazione da App Configuration. Per informazioni su come usare un'identità gestita di Azure per semplificare l'accesso a App Configuration, continuare con l'esercitazione successiva.

Integrazione dell'identità gestita

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-04-21