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:

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.

1. Registrare i servizi di Configurazione app necessari richiamando AddAzureAppConfiguration su IServiceCollection.

   Aggiungere il codice seguente a Program.cs.

   // Existing code in Program.cs
   // ... ...
   
   // Add Azure App Configuration services to IServiceCollection
   builder.Services.AddAzureAppConfiguration();
   

2. Aggiornare la configurazione risolvendo un'istanza di dalla raccolta di IConfigurationRefresherProvider servizi e richiamando TryRefreshAsync 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

1. 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>'
   

2. Eseguire il comando seguente per compilare l'app console:

    dotnet build
   

3. Al termine della compilazione, eseguire questo comando per eseguire l'app Web in locale:

    dotnet run
   

   

4. Accedere al portale di Azure. Selezionare Tutte le risorse e quindi l'istanza di archivio di Configurazione app creata nell'argomento di avvio rapido.

5. Selezionare Configuration Explorer e aggiornare i valori delle chiavi seguenti:

   Chiave	valore
   TestApp:Settings:Message	Dati di Configurazione app di Azure - Aggiornati

6. 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 SetCacheExpiration quando è 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 Verbose registrazione a livello di evento specificando il EventLevel.Verbose parametro , 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'
  

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.

1. Accedere al portale di Azure e selezionare Gruppi di risorse.
2. Nella casella Filtra per nome immettere il nome del gruppo di risorse.
3. Nell'elenco dei risultati selezionare il nome del gruppo di risorse per visualizzare una panoramica.
4. Selezionare Elimina gruppo di risorse.
5. 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.