Provider di configurazione in .NET

La configurazione in .NET è possibile con i provider di configurazione. Diversi tipi di provider si basano su varie origini di configurazione. Questo articolo illustra in dettaglio tutti i diversi provider di configurazione e le relative origini corrispondenti.

• Provider di configurazione file
• Provider di configurazione delle variabili di ambiente
• Provider di configurazione della riga di comando
• Provider di configurazione chiave-per-file
• Provider di configurazione della memoria

Provider di configurazione file

FileConfigurationProvider è la classe base per il caricamento della configurazione dal file system. I provider di configurazione seguenti derivano da FileConfigurationProvider:

• Provider di configurazione JSON
• Provider di configurazione XML
• Provider di configurazione INI

Le chiavi non fanno distinzione tra maiuscole e minuscole. Tutti i provider di configurazione dei file generano un'eccezione FormatException quando vengono trovate chiavi duplicate in un singolo provider.

Provider di configurazione JSON

La classe JsonConfigurationProvider carica la configurazione da un file JSON. Installare il pacchetto NuGet Microsoft.Extensions.Configuration.Json.

Gli overload possono specificare:

• Se il file è facoltativo.
• Se la configurazione viene ricaricata se viene modificato il file.

Osservare il codice seguente:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using ConsoleJson.Example;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.Sources.Clear();

IHostEnvironment env = builder.Environment;

builder.Configuration
    .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
    .AddJsonFile($"appsettings.{env.EnvironmentName}.json", true, true);

TransientFaultHandlingOptions options = new();
builder.Configuration.GetSection(nameof(TransientFaultHandlingOptions))
    .Bind(options);

Console.WriteLine($"TransientFaultHandlingOptions.Enabled={options.Enabled}");
Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={options.AutoRetryDelay}");

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Il codice precedente:

• Cancella tutti i provider di configurazione esistenti aggiunti per impostazione predefinita nel metodo CreateApplicationBuilder(String[]).
• Configura il provider di configurazione JSON per caricare i file appsettings.json e appsettings.Environment.json con le opzioni seguenti:
  • optional: true: il file è facoltativo.
  • reloadOnChange: true: il file viene ricaricato quando vengono salvate le modifiche.

Di seguito è riportato un esempio di file appsettings.json con varie impostazioni di configurazione:

{
    "SecretKey": "Secret key value",
    "TransientFaultHandlingOptions": {
        "Enabled": true,
        "AutoRetryDelay": "00:00:07"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    }
}

Dall'istanza di IConfigurationBuilder, dopo l'aggiunta dei provider di configurazione, è possibile chiamare IConfigurationBuilder.Build() per ottenere l'oggetto IConfigurationRoot. La radice di configurazione rappresenta la radice di una gerarchia di configurazione. Le sezioni della configurazione possono essere associate a istanze di oggetti .NET e fornite successivamente come IOptions<TOptions> tramite l'inserimento delle dipendenze.

Si consideri la classe TransientFaultHandlingOptions definita come segue:

namespace ConsoleJson.Example;

public sealed class TransientFaultHandlingOptions
{
    public bool Enabled { get; set; }
    public TimeSpan AutoRetryDelay { get; set; }
}

Il codice seguente compila la radice di configurazione, associa una sezione al tipo di classe TransientFaultHandlingOptions e stampa i valori associati nella finestra della console:

TransientFaultHandlingOptions options = new();
builder.Configuration.GetSection(nameof(TransientFaultHandlingOptions))
    .Bind(options);

Console.WriteLine($"TransientFaultHandlingOptions.Enabled={options.Enabled}");
Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={options.AutoRetryDelay}");

L'applicazione scrive l'output di esempio seguente:

// Sample output:
//    TransientFaultHandlingOptions.Enabled=True
//    TransientFaultHandlingOptions.AutoRetryDelay=00:00:07

Provider di configurazione XML

La classe XmlConfigurationProvider carica la configurazione da un file XML in fase di esecuzione. Installare il pacchetto NuGet Microsoft.Extensions.Configuration.Xml.

Il codice seguente illustra la configurazione dei file XML usando il provider di configurazione XML.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.Sources.Clear();

builder.Configuration
    .AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true)
    .AddXmlFile("repeating-example.xml", optional: true, reloadOnChange: true);

builder.Configuration.AddEnvironmentVariables();

if (args is { Length: > 0 })
{
    builder.Configuration.AddCommandLine(args);
}

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Il codice precedente:

• Cancella tutti i provider di configurazione esistenti aggiunti per impostazione predefinita nel metodo CreateApplicationBuilder(String[]).
• Configura il provider di configurazione XML per caricare i file appsettings.xml e repeating-example.xml con le opzioni seguenti:
  • optional: true: il file è facoltativo.
  • reloadOnChange: true: il file viene ricaricato quando vengono salvate le modifiche.
• Configura il provider di configurazione delle variabili di ambiente.
• Configura il provider di configurazione della riga di comando se il args specificato contiene argomenti.

Le impostazioni XML vengono sostituite dalle impostazioni nel provider di configurazione delle variabili di ambiente e nel provider di configurazione della riga di comando.

Di seguito è riportato un esempio di file appsettings.xml con varie impostazioni di configurazione:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <SecretKey>Secret key value</SecretKey>
  <TransientFaultHandlingOptions>
    <Enabled>true</Enabled>
    <AutoRetryDelay>00:00:07</AutoRetryDelay>
  </TransientFaultHandlingOptions>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

In .NET 5 e versioni precedenti aggiungere l'attributo name per distinguere gli elementi ripetuti che usano lo stesso nome di elemento. In .NET 6 e versioni successive il provider di configurazione XML indicizza automaticamente gli elementi ripetuti. Ciò significa che non è necessario specificare l'attributo name, tranne se si vuole l'indice "0" nella chiave ed è presente un solo elemento. Se si esegue l'aggiornamento a .NET 6 o versione successiva, è possibile che si verifichi un'interruzione risultante da questa modifica nel comportamento. Per altre informazioni, vedere Elementi XML ripetuti includono l'indice.)

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <section name="section0">
    <key name="key0">value 00</key>
    <key name="key1">value 01</key>
  </section>
  <section name="section1">
    <key name="key0">value 10</key>
    <key name="key1">value 11</key>
  </section>
</configuration>

Il codice seguente legge il file di configurazione precedente e visualizza le chiavi e i valori:

IConfigurationRoot configurationRoot = builder.Configuration;

string key00 = "section:section0:key:key0";
string key01 = "section:section0:key:key1";
string key10 = "section:section1:key:key0";
string key11 = "section:section1:key:key1";

string? val00 = configurationRoot[key00];
string? val01 = configurationRoot[key01];
string? val10 = configurationRoot[key10];
string? val11 = configurationRoot[key11];

Console.WriteLine($"{key00} = {val00}");
Console.WriteLine($"{key01} = {val01}");
Console.WriteLine($"{key10} = {val10}");
Console.WriteLine($"{key10} = {val11}");

L'applicazione scriverà l'output di esempio seguente:

// Sample output:
//    section:section0:key:key0 = value 00
//    section:section0:key:key1 = value 01
//    section:section1:key:key0 = value 10
//    section:section1:key:key0 = value 11

È possibile usare attributi per fornire valori:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <key attribute="value" />
  <section>
    <key attribute="value" />
  </section>
</configuration>

Il file di configurazione precedente carica le chiavi seguenti con value:

• key:attribute
• section:key:attribute

Provider di configurazione INI

La classe IniConfigurationProvider carica la configurazione da un file INI in fase di esecuzione. Installare il pacchetto NuGet Microsoft.Extensions.Configuration.Ini.

Il codice seguente cancella tutti i provider di configurazione e aggiunge il IniConfigurationProvider con due file INI come origine:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
builder.Configuration.Sources.Clear();

IHostEnvironment env = builder.Environment;

builder.Configuration
    .AddIniFile("appsettings.ini", optional: true, reloadOnChange: true)
    .AddIniFile($"appsettings.{env.EnvironmentName}.ini", true, true);

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Di seguito è riportato un esempio di file appsettings.ini con varie impostazioni di configurazione:

SecretKey="Secret key value"

[TransientFaultHandlingOptions]
Enabled=True
AutoRetryDelay="00:00:07"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Il codice seguente visualizza le impostazioni di configurazione precedenti scrivendole nella finestra della console:

foreach ((string key, string? value) in
    builder.Configuration.AsEnumerable().Where(t => t.Value is not null))
{
    Console.WriteLine($"{key}={value}");
}

L'applicazione scriverà l'output di esempio seguente:

// Sample output:
//    TransientFaultHandlingOptions:Enabled=True
//    TransientFaultHandlingOptions:AutoRetryDelay=00:00:07
//    SecretKey=Secret key value
//    Logging:LogLevel:Microsoft=Warning
//    Logging:LogLevel:Default=Information

Provider di configurazione delle variabili di ambiente

Usando la configurazione predefinita, EnvironmentVariablesConfigurationProvider carica la configurazione dalle coppie chiave-valore della variabile di ambiente dopo aver letto appsettings.json, appsettings.Environment.jsone secret manager. Pertanto, i valori chiave letti dall'ambiente sostituiscono i valori letti da appsettings.json, appsettings.Environment.json, e secret manager.

Il delimitatore : non funziona con le chiavi gerarchiche delle variabili di ambiente in tutte le piattaforme. Ad esempio, il delimitatore : non è supportato da Bash. Il doppio carattere di sottolineatura (__), supportato in tutte le piattaforme, sostituisce automaticamente tutti i delimitatori : nelle variabili di ambiente.

Si consideri la classe TransientFaultHandlingOptions:

public class TransientFaultHandlingOptions
{
    public bool Enabled { get; set; }
    public TimeSpan AutoRetryDelay { get; set; }
}

I comandi di set seguenti impostano le chiavi e i valori dell'ambiente di SecretKey e TransientFaultHandlingOptions.

set SecretKey="Secret key from environment"
set TransientFaultHandlingOptions__Enabled="true"
set TransientFaultHandlingOptions__AutoRetryDelay="00:00:13"

Queste impostazioni di ambiente vengono impostate solo nei processi avviati dalla finestra di comando in cui sono state impostate. Non vengono lette dalle app Web avviate con Visual Studio.

Con Visual Studio 2019 e versioni successive, è possibile specificare le variabili di ambiente usando la finestra di dialogo Avvia profili.

I comandi setx seguenti possono essere usati per impostare le chiavi e i valori di ambiente in Windows. A differenza di set, le impostazioni setx vengono mantenute. /M imposta la variabile nell'ambiente di sistema. Se non viene usata l'opzione /M, viene impostata una variabile di ambiente dell'utente.

setx SecretKey "Secret key from setx environment" /M
setx TransientFaultHandlingOptions__Enabled "true" /M
setx TransientFaultHandlingOptions__AutoRetryDelay "00:00:05" /M

Per verificare che i comandi precedenti esaguano l'override di qualsiasi impostazione appsettings.json e appsettings.Environment.json:

• Con Visual Studio: uscire e riavviare Visual Studio.
• Con l'interfaccia della riga di comando: avviare una nuova finestra di comando e immettere dotnet run.

Prefissi

Chiamare AddEnvironmentVariables con una stringa per specificare un prefisso per le variabili di ambiente:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.AddEnvironmentVariables(prefix: "CustomPrefix_");

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Nel codice precedente:

• config.AddEnvironmentVariables(prefix: "CustomPrefix_") viene aggiunto dopo i provider di configurazione predefiniti. Per un esempio di ordinamento dei provider di configurazione, vedere provider di configurazione XML.
• Le variabili di ambiente impostate con il prefisso CustomPrefix_ sostituiscono i provider di configurazione predefiniti. Sono incluse le variabili di ambiente senza il prefisso.

Il prefisso viene rimosso quando vengono lette le coppie chiave-valore della configurazione.

La configurazione predefinita carica le variabili di ambiente e gli argomenti della riga di comando preceduti da DOTNET_. Il prefisso DOTNET_ viene usato da .NET per host e configurazione dell'app, ma non per la configurazione dell'utente.

Per altre informazioni sulla configurazione dell'host e dell'app, vedere Host generico .NET.

Prefissi della stringa di connessione

L'API di configurazione ha regole di elaborazione speciali per quattro variabili di ambiente della stringa di connessione. Queste stringhe di connessione sono coinvolte nella configurazione delle stringhe di connessione di Azure per l'ambiente dell'app. Le variabili di ambiente con i prefissi indicati nella tabella vengono caricate nell'app con la configurazione predefinita o quando non viene fornito alcun prefisso per AddEnvironmentVariables.

Quando una variabile di ambiente viene individuata e caricata nella configurazione con uno qualsiasi dei quattro prefissi indicati nella tabella:

• La chiave di configurazione viene creata rimuovendo il prefisso della variabile di ambiente e aggiungendo una sezione per la chiave di configurazione (ConnectionStrings).
• Viene creata una nuova coppia chiave-valore della configurazione che rappresenta il provider di connessione al database (ad eccezione di CUSTOMCONNSTR_, che non ha un provider dichiarato).

Variabili di ambiente impostate in launchSettings.json

I valori di ambiente in launchSettings.json eseguono l'override dei valori impostati nell'ambiente di sistema.

Impostazioni di Servizio app di Azure

In servizio app di Azure, selezionare Nuova impostazione applicazione nella pagina Impostazioni>configurazione. Le impostazioni applicazione del Servizio app di Azure sono:

• Crittografate mentre sono inattive e trasmesse su un canale crittografato.
• Esposte come variabili di ambiente.

Provider di configurazione della riga di comando

Usando la configurazione predefinita, CommandLineConfigurationProvider carica la configurazione dalle coppie chiave-valore dell'argomento della riga di comando dopo le origini di configurazione seguenti:

• File appsettings.json e appsettings.Environment.file json.
• Segreti dell'app (Secret Manager) nell'ambiente Development.
• variabili di ambiente.

Per impostazione predefinita, i valori di configurazione impostati nella riga di comando sostituiscono i valori di configurazione impostati con tutti gli altri provider di configurazione.

Con Visual Studio 2019 e versioni successive, è possibile specificare gli argomenti della riga di comando usando la finestra di dialogo Profili di avvio.

Argomenti della riga di comando

Il comando seguente imposta chiavi e valori usando =:

dotnet run SecretKey="Secret key from command line"

Il comando seguente imposta chiavi e valori usando /:

dotnet run /SecretKey "Secret key set from forward slash"

Il comando seguente imposta chiavi e valori usando --:

dotnet run --SecretKey "Secret key set from double hyphen"

Il valore di chiave:

• Deve seguire = o la chiave deve avere un prefisso -- o / quando il valore segue uno spazio.
• Non è richiesto se viene usato =. Ad esempio: SomeKey=.

Nello stesso comando, non mischiare coppie chiave-valore di argomenti della riga di comando che usano = con coppie chiave-valore che usano uno spazio.

Provider di configurazione chiave-per-file

Il KeyPerFileConfigurationProvider usa i file di una directory come coppie chiave-valore della configurazione. La chiave è il nome del file. Il valore è il contenuto del file. Il provider di configurazione chiave-per-file viene usato negli scenari di hosting di Docker.

Per attivare la configurazione chiave-per-file, chiamare il metodo di estensione AddKeyPerFile su un'istanza di ConfigurationBuilder. Il directoryPath per i file deve essere un percorso assoluto.

Gli overload consentono di specificare:

• Un delegato Action<KeyPerFileConfigurationSource> che configura l'origine.
• Se la directory è facoltativa e il percorso della directory.

Il doppio carattere di sottolineatura (__) viene usato come delimitatore per le chiavi di configurazione nei nomi dei file. Ad esempio, il nome di file Logging__LogLevel__System produce la chiave di configurazione Logging:LogLevel:System.

Chiamare ConfigureAppConfiguration quando si crea l'host per specificare la configurazione dell'app:

.ConfigureAppConfiguration((_, configuration) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");

    configuration.AddKeyPerFile(directoryPath: path, optional: true);
})

Provider di configurazione della memoria

Il MemoryConfigurationProvider usa una raccolta in memoria come coppie chiave-valore della configurazione.

Il codice seguente aggiunge una raccolta di memoria al sistema di configurazione:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.AddInMemoryCollection(
    new Dictionary<string, string?>
    {
        ["SecretKey"] = "Dictionary MyKey Value",
        ["TransientFaultHandlingOptions:Enabled"] = bool.TrueString,
        ["TransientFaultHandlingOptions:AutoRetryDelay"] = "00:00:07",
        ["Logging:LogLevel:Default"] = "Warning"
    });

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Nel codice precedente, MemoryConfigurationBuilderExtensions.AddInMemoryCollection(IConfigurationBuilder, IEnumerable<KeyValuePair<String,String>>) aggiunge il provider di memoria dopo i provider di configurazione predefiniti. Per un esempio di ordinamento dei provider di configurazione, vedere provider di configurazione XML.

Vedi anche

• Configurazione in .NET
• Host generico .NET
• Implementare un provider di configurazione personalizzato