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

Articolo
04/18/2023

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

In questa esercitazione verranno illustrate le procedure per:

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.

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

Ricaricare i dati di Configurazione app

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

.NET 6.0+
.NET Core 3.x

// 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));
});

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureAppConfiguration(config =>
            {
                //Retrieve the Connection String from the secrets manager
                IConfiguration settings = config.Build();
                string connectionString = settings.GetConnectionString("AppConfig");

                // Load configuration from Azure App Configuration
                config.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));
                });
            });

            webBuilder.UseStartup<Startup>();
        });

Il Select metodo viene usato per caricare tutti i valori chiave il cui nome chiave inizia con TestApp: e che non hanno etichetta. È possibile chiamare il Select metodo più di una volta per caricare le configurazioni con prefissi o etichette diverse. Se si condivide un Configurazione app store con più app, questo approccio consente di caricare la configurazione solo pertinente per l'app corrente anziché caricare tutto dal proprio store.

Nel metodo si registrano le chiavi da monitorare per le modifiche nell'archivio ConfigureRefresh 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 un valore superiore se è necessario ridurre il numero di richieste effettuate nell'archivio Configurazione app.

Aggiungere Configurazione app di Azure middleware alla raccolta di servizi dell'app.

.NET 6.0+
.NET Core 3.x

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

Aprire Startup.cs e aggiornare il metodo ConfigureServices.

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages();

    // Add Azure App Configuration middleware to the container of services.
    services.AddAzureAppConfiguration();

    // Bind configuration "TestApp:Settings" section to the Settings object
    services.Configure<Settings>(Configuration.GetSection("TestApp:Settings"));
}

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

.NET 6.0+
.NET Core 3.x

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

Aggiornare il Configure metodo in Startup.cs.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    // Use Azure App Configuration middleware for dynamic configuration refresh.
    app.UseAzureAppConfiguration();

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

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 tramite IOptionsSnapshot<T> viene aggiornato Settings automaticamente. Si noti che non è consigliabile usare l'aggiornamento IOptions<T> della configurazione dinamica se è desiderato 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. Nessun aggiornamento si verificherà se l'app è inattiva. Quando l'app è attiva, il middleware Configurazione app monitora la chiave sentinel o qualsiasi altra chiave registrata per l'aggiornamento della ConfigureRefresh chiamata. Il middleware viene attivato su ogni richiesta in ingresso all'app. Tuttavia, il middleware invierà solo richieste per controllare il valore in Configurazione app quando la scadenza della cache impostata è passata.

Se una richiesta di Configurazione app per il rilevamento delle modifiche ha esito negativo, l'app continuerà a usare la configurazione memorizzata nella cache. I nuovi tentativi di verifica delle modifiche verranno apportati periodicamente mentre sono presenti nuove richieste in ingresso all'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 prima dell'appropriato nella pipeline della richiesta in modo che un altro middleware non lo ignora nell'app.

Compilare ed eseguire l'app in locale

Per compilare l'app usando l'interfaccia della riga di comando di .NET Core, 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 quindi l'archivio di Configurazione app creato nella guida di avvio rapido.

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

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.

Un valore predefinito ILoggerFactory viene aggiunto automaticamente quando services.AddAzureAppConfiguration() viene richiamato. Il provider di Configurazione app usa questa opzione ILoggerFactory 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 modifiche di codice aggiuntive per abilitare la registrazione per il provider di Configurazione app.

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

Livello registro	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 è cambiato rispetto a quello già caricato dall'applicazione. Abilitare i log a questo livello per risolvere i problemi dell'applicazione se una modifica di configurazione non è stata eseguita 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 la perdita di dati sensibili. È possibile monitorare i log a questo livello per garantire 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 gli 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 è 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 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 Configurazione app usando l'identità gestita