Esercitazione: Usare la configurazione dinamica in un'app .NET
La libreria del provider .NET Configurazione app supporta l'aggiornamento della configurazione su richiesta senza causare il riavvio di un'applicazione. Questa esercitazione mostra come è possibile implementare aggiornamenti dinamici della configurazione nel codice. Si basa sull'app introdotta nella guida introduttiva. Prima di continuare, è necessario completare Creare un'app .NET con Configurazione app.
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 apprenderai a:
- Configurare l'app .NET per aggiornarne la configurazione in risposta alle modifiche in un archivio Configurazione app.
- Utilizzare la configurazione più recente nell'applicazione.
Prerequisiti
Se non si ha una sottoscrizione di Azure, creare un account Azure gratuito prima di iniziare.
Completare la guida introduttiva Creare un'app .NET con Configurazione app.
Aggiornamento della configurazione guidata dall'attività
Aprire Program.cs e aggiornare il file con il codice seguente.
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
IConfiguration _configuration = null;
IConfigurationRefresher _refresher = null;
var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
options.Connect(Environment.GetEnvironmentVariable("ConnectionString"))
.ConfigureRefresh(refresh =>
{
refresh.Register("TestApp:Settings:Message")
.SetCacheExpiration(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!");
}
ConfigureRefresh Nel metodo viene registrata una chiave all'interno dell'archivio Configurazione app per il monitoraggio delle modifiche. Il Register metodo dispone di un parametro refreshAll booleano facoltativo che può essere usato per indicare se tutti i valori di configurazione devono essere aggiornati se la chiave registrata cambia. In questo esempio verrà aggiornata solo la chiave TestApp:Impostazioni:Message. Il SetCacheExpiration 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. Si vuole includere la chiamata in cui si considera attiva l'applicazione TryRefreshAsync . 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 sempre. 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 è trascorsa l'ora di scadenza della cache configurata e la TryRefreshAsync chiamata viene attivata di nuovo dall'attività dell'applicazione. La chiamata TryRefreshAsync è un'operazione no-op prima della scadenza della cache configurata, quindi l'impatto sulle prestazioni è minimo, anche se viene chiamato di frequente.
Aggiornamento della configurazione tramite inserimento delle dipendenze
Nel codice precedente si salva manualmente un'istanza di IConfigurationRefresher per richiamare TryRefreshAsync. In alternativa, se si usa l'inserimento delle dipendenze per risolvere i servizi, è possibile fare riferimento ai passaggi seguenti.
Registrare i servizi di Configurazione app necessari richiamando
AddAzureAppConfigurationsuIServiceCollection.Aggiungere il codice seguente a Program.cs.
// Existing code in Program.cs // ... ... // Add Azure App Configuration services to IServiceCollection builder.Services.AddAzureAppConfiguration();Aggiornare la configurazione risolvendo un'istanza di dalla raccolta di
IConfigurationRefresherProviderservizi e richiamandoTryRefreshAsyncognuno 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
Impostare una variabile di ambiente denominata ConnectionString sulla chiave di accesso all'archivio di Configurazione app. Se si usa il prompt dei comandi di Windows, eseguire il comando seguente e riavviare il prompt per rendere effettiva la modifica:
setx ConnectionString "connection-string-of-your-app-configuration-store"Se si usa Windows PowerShell, eseguire il comando seguente:
$Env:ConnectionString = "connection-string-of-your-app-configuration-store"Se si usa macOS o Linux, eseguire il comando seguente:
export ConnectionString='connection-string-of-your-app-configuration-store'Eseguire il comando seguente per compilare l'app console:
dotnet buildAl 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 quindi l'istanza di archivio di Configurazione app creata nell'argomento di avvio rapido.
Selezionare Configuration Explorer e aggiornare i valori delle chiavi seguenti:
Chiave valore TestApp:Settings:Message Dati di Configurazione app di Azure - Aggiornati Premere INVIO per attivare un aggiornamento e stampare il valore aggiornato nel prompt dei comandi o nella finestra di PowerShell.
Nota
Poiché la scadenza della cache è stata impostata su 10 secondi usando il metodo
SetCacheExpirationquando è stata specificata la configurazione per l'operazione di aggiornamento, il valore dell'impostazione di configurazione verrà aggiornato solo se sono trascorsi almeno 10 secondo dopo l'ultimo aggiornamento di tale impostazione.
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 dell'evento Descrizione Verbose I log includono la chiave e l'etichetta dei valori chiave monitorati dall'applicazione per le modifiche apportate dall'archivio 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. Informazioni 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. Avviso 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
Verboseregistrazione a livello di evento specificando ilEventLevel.Verboseparametro , 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 laMicrosoft-Extensions-Configuration-AzureAppConfiguration-Refreshcategoria.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'
Nota
La registrazione è disponibile se si usa la versione 6.0.0 o successiva di uno dei pacchetti seguenti.
Microsoft.Extensions.Configuration.AzureAppConfigurationMicrosoft.Azure.AppConfiguration.AspNetCoreMicrosoft.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 è stato abilitato l'app .NET per aggiornare dinamicamente le impostazioni di configurazione da Configurazione app. Per informazioni su come usare un'identità gestita di Azure per semplificare l'accesso a Configurazione app, continuare con l'esercitazione successiva.