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

Questa esercitazione illustra come abilitare gli aggiornamenti della configurazione dinamica in un'app ASP.NET Core. Si basa sull'app Web presentata nelle guide introduttive. L'app userà la libreria del provider Configurazione app per le funzionalità di memorizzazione nella cache e aggiornamento della configurazione predefinite. Prima di continuare, completare le procedure descritte in Creare un'app ASP.NET Core con Configurazione app.

In questa esercitazione apprenderai a:

• Configurare l'app per aggiornarne la configurazione in risposta alle modifiche in un archivio Configurazione app.
• Inserire la configurazione più recente nell'app.

Prerequisiti

Completare la guida introduttiva: Creare un'app ASP.NET Core con Configurazione app.

Aggiungere una chiave Sentinel

Una chiave sentinel è una chiave che si aggiorna dopo aver completato la modifica di tutte le altre chiavi. L'app monitora la chiave sentinel. Quando viene rilevata una modifica, l'app aggiorna tutti i valori di configurazione. Questo approccio consente di garantire la coerenza della configurazione nell'app e riduce il numero complessivo di richieste effettuate all'archivio Configurazione app, rispetto al monitoraggio di tutte le chiavi per le modifiche.

1. Nella portale di Azure aprire l'archivio Configurazione app e selezionare Esplora configurazione > Crea > chiave-valore.
2. In Chiave immettere TestApp:Settings:Sentinel. In Valore immettere 1. Lasciare vuoti i campi Etichetta e Tipo di contenuto.
3. Selezionare Applica.

Ricaricare i dati di Configurazione app

1. Aprire Program.cs e aggiornare il AddAzureAppConfiguration metodo aggiunto in precedenza durante l'avvio rapido.

   // Load configuration from Azure App Configuration
   builder.Configuration.AddAzureAppConfiguration(options =>
   {
       options.Connect(connectionString)
              // Load all keys that start with `TestApp:` and have no label
              .Select("TestApp:*", LabelFilter.Null)
              // Configure to reload configuration if the registered sentinel key is modified
              .ConfigureRefresh(refreshOptions =>
                   refreshOptions.Register("TestApp:Settings:Sentinel", refreshAll: true));
   });
   

   Il Select metodo viene usato per caricare tutti i valori chiave il cui nome della chiave inizia con TestApp: e che non hanno etichetta. È possibile chiamare il Select metodo più volte per caricare le configurazioni con prefissi o etichette diversi. Se si condivide un Configurazione app Store con più app, questo approccio consente di caricare la configurazione solo pertinente per l'app corrente invece di caricare tutti gli elementi dallo Store.

   ConfigureRefresh Nel metodo si registrano le chiavi da monitorare per le modifiche nell'archivio Configurazione app. Il refreshAll parametro al Register metodo indica che tutte le configurazioni specificate dal Select metodo verranno ricaricate se la chiave registrata cambia.

   Suggerimento

   È possibile aggiungere una chiamata al refreshOptions.SetCacheExpiration metodo per specificare il tempo minimo tra gli aggiornamenti della configurazione. In questo esempio si usa il valore predefinito di 30 secondi. Modificare in base a un valore superiore se è necessario ridurre il numero di richieste effettuate all'archivio Configurazione app.

2. Aggiungere app Azure middleware di configurazione alla raccolta di servizi dell'app.

   Aggiornare Program.cs con il codice seguente.

   // Existing code in Program.cs
   // ... ...
   
   builder.Services.AddRazorPages();
   
   // Add Azure App Configuration middleware to the container of services.
   builder.Services.AddAzureAppConfiguration();
   
   // Bind configuration "TestApp:Settings" section to the Settings object
   builder.Services.Configure<Settings>(builder.Configuration.GetSection("TestApp:Settings"));
   
   var app = builder.Build();
   
   // The rest of existing code in program.cs
   // ... ...
   

3. Chiamare il metodo UseAzureAppConfiguration . Consente all'app di usare il middleware Configurazione app per aggiornare automaticamente la configurazione.

   Aggiornare Program.cs con il codice seguente.

   // Existing code in Program.cs
   // ... ...
   
   var app = builder.Build();
   
   if (!app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/Error");
       app.UseHsts();
   }
   
   // Use Azure App Configuration middleware for dynamic configuration refresh.
   app.UseAzureAppConfiguration();
   
   // The rest of existing code in program.cs
   // ... ...
   

L'app è stata configurata per usare il modello di opzioni in ASP.NET Core durante l'avvio rapido. Quando la configurazione sottostante dell'app viene aggiornata da Configurazione app, l'oggetto fortemente tipizzato ottenuto Settings tramite IOptionsSnapshot<T> viene aggiornato automaticamente. Si noti che non è consigliabile usare se IOptions<T> si vuole aggiornare la configurazione dinamica perché non legge i dati di configurazione dopo l'avvio dell'app.

Aggiornamento della configurazione basata su richiesta

L'aggiornamento della configurazione viene attivato dalle richieste in ingresso all'app Web. Se l'app non è inattiva, non verrà eseguito alcun aggiornamento. Quando l'app è attiva, il middleware Configurazione app monitora la chiave sentinel o qualsiasi altra chiave registrata per l'aggiornamento nella ConfigureRefresh chiamata. Il middleware viene attivato su ogni richiesta in ingresso all'app. Tuttavia, il middleware invierà solo le richieste per controllare il valore in Configurazione app quando è trascorsa la scadenza della cache impostata.

• Se una richiesta di Configurazione app per il rilevamento delle modifiche non riesce, l'app continuerà a usare la configurazione memorizzata nella cache. I nuovi tentativi di verificare la presenza di modifiche verranno eseguiti periodicamente mentre sono presenti nuove richieste in ingresso per l'app.
• L'aggiornamento della configurazione viene eseguito in modo asincrono per l'elaborazione delle richieste in ingresso dell'app. Non blocca o rallenta la richiesta in ingresso che ha attivato l'aggiornamento. La richiesta che ha attivato l'aggiornamento potrebbe non ottenere i valori di configurazione aggiornati, ma le richieste successive otterranno nuovi valori di configurazione.
• Per assicurarsi che il middleware venga attivato, chiamare il app.UseAzureAppConfiguration() metodo come appropriato nella pipeline di richiesta, in modo che un altro middleware non lo ignori nell'app.

Compilare ed eseguire l'app in locale

1. Per compilare l'app usando l'interfaccia della riga di comando di .NET, eseguire questo comando nella shell dei comandi:

       dotnet build
   

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

       dotnet run
   

3. Aprire una finestra del browser e passare all'URL visualizzato nell'output di dotnet run.

   

4. Accedere al portale di Azure. Selezionare Tutte le risorse e quindi l'archivio di Configurazione app creato nella guida di avvio rapido.

5. Selezionare Esplora configurazione e aggiornare i valori delle chiavi seguenti. Ricordarsi di aggiornare la chiave sentinel alla fine.

   Chiave	valore
   TestApp:Settings:BackgroundColor	green
   TestApp:Settings:FontColor	lightGray
   TestApp:Settings:Message	Dati di Configurazione app di Azure - ora con aggiornamenti dinamici
   TestApp:Settings:Sentinel	2

6. Aggiornare alcune volte il browser. Quando la cache scade dopo 30 secondi, la pagina viene visualizzata con contenuto 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.

• Quando viene richiamato, viene aggiunto automaticamente services.AddAzureAppConfiguration() un valore predefinitoILoggerFactory. Il provider Configurazione app usa questa ILoggerFactory opzione per creare un'istanza di ILogger, che restituisce questi log. ASP.NET Core usa ILogger per la registrazione per impostazione predefinita, quindi non è necessario apportare altre modifiche al codice per abilitare la registrazione per il provider di Configurazione app.

• I log vengono restituiti a livelli di log diversi. Il livello predefinito è Information.

  Livello di registrazione	Descrizione
  Debug	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 Debug registrazione a livello di log aggiungendo l'esempio seguente al appsettings.json file. Questo esempio si applica anche a tutti gli altri livelli di log.

  "Logging": {
      "LogLevel": {
          "Microsoft.Extensions.Configuration.AzureAppConfiguration": "Debug"
      }
  }
  

• 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 log:

  dbug: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
      Key-value read from App Configuration. Change:'Modified' Key:'ExampleKey' Label:'ExampleLabel' Endpoint:'https://examplestore.azconfig.io'
  
  info: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
      Setting updated. Key:'ExampleKey'
  
  warn: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
      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'
  

L'uso ILogger di è il metodo preferito nelle applicazioni ASP.NET ed è prioritario come origine di registrazione se è presente un'istanza di ILoggerFactory . Tuttavia, se ILoggerFactory non è disponibile, i log possono essere abilitati e configurati in alternativa tramite le istruzioni per le app .NET Core. Per altre informazioni, vedere Registrazione in .NET Core e ASP.NET Core.

Nota

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.

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 è stata abilitata l'app Web ASP.NET Core per aggiornare in modo dinamico le impostazioni di configurazione di Configurazione app. Per informazioni su come usare un'identità gestita di Azure per semplificare l'accesso a Configurazione app, continuare con l'esercitazione successiva.

Accedere a Configurazione app di Azure usando l’identità gestita