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

2025-04-30

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, dovrai completare la creazione di un'app ASP.NET Core con App Configuration prima.

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.

Ricaricare i dati di Configurazione app

Aprire Program.cs e aggiornare il metodo AddAzureAppConfiguration aggiunto durante la guida introduttiva. È possibile connettersi a Configurazione app usando Microsoft Entra ID (scelta consigliata) o un stringa di connessione. Il frammento di codice seguente illustra l'uso dell'ID Microsoft Entra.

Usare per eseguire l'autenticazione DefaultAzureCredential nell'archivio Configurazione app. Durante il completamento della procedura di avvio rapido elencata nei prerequisiti, hai già assegnato al tuo credential il ruolo Lettore dati di configurazione dell'app.
```
// Load configuration from Azure App Configuration
builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())
           // Load all keys that start with `TestApp:` and have no label.
           .Select("TestApp:*", LabelFilter.Null)
           // Reload configuration if any selected key-values have changed.
           .ConfigureRefresh(refreshOptions =>
               refreshOptions.RegisterAll());
});
```
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.

All'interno del ConfigureRefresh metodo si chiama il RegisterAll metodo per indicare al provider di Configurazione app di ricaricare l'intera configurazione ogni volta che rileva una modifica in uno dei valori chiave selezionati (quelli che iniziano con TestApp: e non hanno etichetta). Per altre informazioni sul monitoraggio delle modifiche alla configurazione, vedere Procedure consigliate per l'aggiornamento della configurazione.

Suggerimento

È possibile aggiungere una chiamata al refreshOptions.SetRefreshInterval 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.

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
// ... ...

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 di Configurazione app monitora qualsiasi altra chiave registrata per l'aggiornamento nella chiamata ConfigureRefresh. Il middleware viene attivato su ogni richiesta in ingresso all'app. Tuttavia, il middleware invierà richieste solo per controllare il valore in Configurazione app quando l'intervallo di aggiornamento impostato è passato.

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

Per compilare l'app usando l'interfaccia della riga di comando di .NET, eseguire questo comando nella shell dei comandi:
```
    dotnet build
```
Al termine della compilazione, eseguire questo comando per eseguire l'app Web in locale:
```
    dotnet run
```
Aprire una finestra del browser e passare all'URL visualizzato nell'output di dotnet run.
Accedere al portale di Azure. Selezionare Tutte le risorse e selezionare l'archivio di Configurazione app creato nell'avvio rapido.

Selezionare Esplora configurazione e aggiornare i valori delle chiavi seguenti.

Chiave	valore
TestApp:Impostazioni:ColoreDiSfondo	verde
TestApp:Impostazioni:FontColor	grigio chiaro
TestApp:Impostazioni:Messaggio	Dati di Configurazione app di Azure - ora con aggiornamenti dinamici

Aggiornare alcune volte il browser. Quando l'intervallo di aggiornamento scade dopo 30 secondi, la pagina viene visualizzata con il 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 ILoggerFactory un valore predefinitoservices.AddAzureAppConfiguration(). 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
Correzione errori di programma	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.

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 da 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 alla configurazione dell'applicazione utilizzando l'identità gestita

Condividi tramite