Configurazione in ASP.NET CoreConfiguration in ASP.NET Core

Di Luke LathamBy Luke Latham

La configurazione delle app in ASP.NET Core si basa su coppie chiave-valore stabilite dai provider di configurazione.App configuration in ASP.NET Core is based on key-value pairs established by configuration providers. I provider di configurazione leggono i dati di configurazione in coppie chiave-valore da un'ampia gamma di origini di configurazione:Configuration providers read configuration data into key-value pairs from a variety of configuration sources:

  • Azure Key VaultAzure Key Vault
  • Argomenti della riga di comandoCommand-line arguments
  • Provider personalizzati (installati o creati)Custom providers (installed or created)
  • File della directoryDirectory files
  • Variabili di ambienteEnvironment variables
  • Oggetti .NET in memoriaIn-memory .NET objects
  • File di impostazioniSettings files

I pacchetti di configurazione per gli scenari di provider di configurazione comuni sono inclusi nel metapacchetto Microsoft.AspNetCore.App.Configuration packages for common configuration provider scenarios are included in the Microsoft.AspNetCore.App metapackage. Gli esempi di codice che seguono e quelli inclusi nell'app di esempio usano lo spazio dei nomi Microsoft.Extensions.Configuration:Code examples that follow and in the sample app use the Microsoft.Extensions.Configuration namespace:

using Microsoft.Extensions.Configuration;

Il modello di opzioni è un'estensione dei concetti di configurazione descritti in questo argomento.The options pattern is an extension of the configuration concepts described in this topic. Le opzioni usano le classi per rappresentare i gruppi di impostazioni correlate.Options uses classes to represent groups of related settings. Per altre informazioni sull'uso del modello di opzioni, vedere Modello di opzioni in ASP.NET Core.For more information on using the options pattern, see Modello di opzioni in ASP.NET Core.

Visualizzare o scaricare il codice di esempio (procedura per il download)View or download sample code (how to download)

Host e configurazione delle appHost vs. app configuration

Prima che l'app venga configurata e avviata, viene configurato e avviato un host.Before the app is configured and started, a host is configured and launched. L'host è responsabile della gestione dell'avvio e della durata delle app.The host is responsible for app startup and lifetime management. Sia l'app che l'host vengono configurati tramite i provider di configurazione descritti in questo argomento.Both the app and the host are configured using the configuration providers described in this topic. Le coppie chiave-valore di configurazione dell'host diventano parte della configurazione globale dell'app.Host configuration key-value pairs become part of the app's global configuration. Per altre informazioni su come vengono usati i provider di configurazione per la creazione dell'host e sugli effetti delle origini di configurazione sulla configurazione dell'host, vedere L'host.For more information on how the configuration providers are used when the host is built and how configuration sources affect host configuration, see The host.

Configurazione predefinitaDefault configuration

Le app basate sui modelli dotnet new di ASP.NET Core chiamano CreateDefaultBuilder durante la compilazione di un host.Web apps based on the ASP.NET Core dotnet new templates call CreateDefaultBuilder when building a host. CreateDefaultBuilder fornisce la configurazione predefinita per l'app nell'ordine seguente:CreateDefaultBuilder provides default configuration for the app in the following order:

I provider di configurazione sono descritti più avanti in questo argomento.The configuration providers are explained later in this topic. Per altre informazioni sull'host e su CreateDefaultBuilder, vedere Host Web ASP.NET Core.For more information on the host and CreateDefaultBuilder, see Host Web ASP.NET Core.

SicurezzaSecurity

Adottare le procedure consigliate seguenti:Adopt the following best practices:

  • Non archiviare mai la password o altri dati sensibili nel codice del provider di configurazione o in file di configurazione di testo normale.Never store passwords or other sensitive data in configuration provider code or in plain text configuration files.
  • Non usare i segreti di produzione in ambienti di sviluppo o di test.Don't use production secrets in development or test environments.
  • Specificare i segreti all'esterno del progetto in modo che non possano essere inavvertitamente inviati a un repository del codice sorgente.Specify secrets outside of the project so that they can't be accidentally committed to a source code repository.

Altre informazioni su come usare più ambienti e la gestione dell'archiviazione sicura dei segreti delle app durante lo sviluppo con Secret Manager (include consigli sull'uso delle variabili di ambiente per l'archiviazione di dati sensibili).Learn more about how to use multiple environments and managing the safe storage of app secrets in development with the Secret Manager (includes advice on using environment variables to store sensitive data). Secret Manager usa il provider di configurazione dei file per archiviare i segreti utente in un file JSON nel sistema locale.The Secret Manager uses the File Configuration Provider to store user secrets in a JSON file on the local system. Il provider di configurazione dei file è descritto più avanti in questo argomento.The File Configuration Provider is described later in this topic.

Azure Key Vault è una delle opzioni per l'archiviazione sicura dei segreti delle app.Azure Key Vault is one option for the safe storage of app secrets. Per ulteriori informazioni, vedere Azure Key Vault Configuration Provider in ASP.NET Core.For more information, see Azure Key Vault Configuration Provider in ASP.NET Core.

Dati di configurazione gerarchiciHierarchical configuration data

L'API di configurazione è in grado di mantenere i dati di configurazione gerarchici rendendoli flat grazie all'uso di un delimitatore nelle chiavi di configurazione.The Configuration API is capable of maintaining hierarchical configuration data by flattening the hierarchical data with the use of a delimiter in the configuration keys.

Nel file JSON seguente, esistono quattro chiavi in una gerarchia strutturata di due sezioni:In the following JSON file, four keys exist in a structured hierarchy of two sections:

{
  "section0": {
    "key0": "value",
    "key1": "value"
  },
  "section1": {
    "key0": "value",
    "key1": "value"
  }
}

Quando il file viene letto nella configurazione, vengono create chiavi univoche per mantenere la struttura di dati gerarchici originale dell'origine di configurazione.When the file is read into configuration, unique keys are created to maintain the original hierarchical data structure of the configuration source. Le sezioni e le chiavi vengono rese flat usando due punti (:) per mantenere la struttura originale:The sections and keys are flattened with the use of a colon (:) to maintain the original structure:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:key0section1:key0
  • section1:key1section1:key1

I metodi GetSection e GetChildren sono disponibili per isolare le sezioni e gli elementi figlio di una sezione nei dati di configurazione.GetSection and GetChildren methods are available to isolate sections and children of a section in the configuration data. Questi metodi sono descritti più avanti in GetSection, GetChildren ed Exists.These methods are described later in GetSection, GetChildren, and Exists. GetSection è incluso nel pacchetto Microsoft.Extensions.Configuration, a sua volta incluso nel metapacchetto Microsoft.AspNetCore.App.GetSection is in the Microsoft.Extensions.Configuration package, which is in the Microsoft.AspNetCore.App metapackage.

ConvenzioniConventions

All'avvio dell'app, le origini di configurazione vengono lette nell'ordine con cui sono specificati i rispettivi provider di configurazione.At app startup, configuration sources are read in the order that their configuration providers are specified.

I provider di configurazione che implementano il rilevamento delle modifiche sono in grado di ricaricare la configurazione quando viene modificata un'impostazione sottostante.Configuration providers that implement change detection have the ability to reload configuration when an underlying setting is changed. Ad esempio, il provider di configurazione dei file (descritto più avanti in questo argomento) e il provider di configurazione di Azure Key Vault implementano il rilevamento delle modifiche.For example, the File Configuration Provider (described later in this topic) and the Azure Key Vault Configuration Provider implement change detection.

IConfiguration è disponibile nel contenitore di inserimento delle dipendenze dell'app.IConfiguration is available in the app's dependency injection (DI) container. IConfiguration può essere inserito in PageModel di Razor Pages per ottenere la configurazione per la classe:IConfiguration can be injected into a Razor Pages PageModel to obtain configuration for the class:

public class IndexModel : PageModel
{
    private readonly IConfiguration _config;

    public IndexModel(IConfiguration config)
    {
        _config = config;
    }

    // The _config local variable is used to obtain configuration 
    // throughout the class.
}

I provider di configurazione non possono usare l'inserimento delle dipendenze, perché non è disponibile quando vengono configurati dall'host.Configuration providers can't utilize DI, as it's not available when they're set up by the host.

Le chiavi di configurazione adottano le convenzioni seguenti:Configuration keys adopt the following conventions:

  • Per le chiavi non viene fatta distinzione tra maiuscole e minuscole.Keys are case-insensitive. Ad esempio, ConnectionString e connectionstring vengono considerate chiavi equivalenti.For example, ConnectionString and connectionstring are treated as equivalent keys.
  • Se un valore per la stessa chiave viene impostato dallo stesso provider di configurazione o da provider diversi, viene usato l'ultimo valore impostato per la chiave.If a value for the same key is set by the same or different configuration providers, the last value set on the key is the value used.
  • Chiavi gerarchicheHierarchical keys
    • Nell'ambito dell'API di configurazione, il separatore due punti (:) funziona in tutte le piattaforme.Within the Configuration API, a colon separator (:) works on all platforms.
    • Nelle variabili di ambiente, un separatore due punti potrebbe non funzionare in tutte le piattaforme.In environment variables, a colon separator may not work on all platforms. Il doppio carattere di sottolineatura (__) è supportato da tutte le piattaforme e viene convertito in due punti.A double underscore (__) is supported by all platforms and is converted to a colon.
    • In Azure Key Vault, le chiavi gerarchiche usano -- (due trattini) come separatore.In Azure Key Vault, hierarchical keys use -- (two dashes) as a separator. È necessario fornire il codice per sostituire i trattini con due punti quando i segreti vengono caricati nella configurazione dell'app.You must provide code to replace the dashes with a colon when the secrets are loaded into the app's configuration.
  • Il ConfigurationBinder supporta l'associazione di matrici agli oggetti usando gli indici delle matrici nelle chiavi di configurazione.The ConfigurationBinder supports binding arrays to objects using array indices in configuration keys. L'associazione di matrici è descritta nella sezione Associare una matrice a una classe.Array binding is described in the Bind an array to a class section.

I valori di configurazione adottano le convenzioni seguenti:Configuration values adopt the following conventions:

  • I valori sono stringhe.Values are strings.
  • I valori null non possono essere archiviati nella configurazione o associati a oggetti.Null values can't be stored in configuration or bound to objects.

ProviderProviders

La tabella seguente mostra i provider di configurazione disponibili per le app ASP.NET Core.The following table shows the configuration providers available to ASP.NET Core apps.

ProviderProvider Fornisce la configurazione da…Provides configuration from…
Provider di configurazione di Azure Key Vault (argomenti Sicurezza)Azure Key Vault Configuration Provider (Security topics) Azure Key VaultAzure Key Vault
Provider di configurazione della riga di comandoCommand-line Configuration Provider Parametri della riga di comandoCommand-line parameters
Provider di configurazione personalizzatoCustom configuration provider Origine personalizzataCustom source
Provider di configurazione delle variabili di ambienteEnvironment Variables Configuration Provider Variabili di ambienteEnvironment variables
Provider di configurazione dei fileFile Configuration Provider File (INI, JSON, XML)Files (INI, JSON, XML)
Provider di configurazione chiave-per-fileKey-per-file Configuration Provider File della directoryDirectory files
Provider di configurazione della memoriaMemory Configuration Provider Raccolte in memoriaIn-memory collections
Segreti utente (Secret Manager) (argomenti Sicurezza)User secrets (Secret Manager) (Security topics) File nella directory dei profili utenteFile in the user profile directory

Le origini di configurazione vengono lette nell'ordine in cui vengono specificati i rispetti provider di configurazione all'avvio.Configuration sources are read in the order that their configuration providers are specified at startup. I provider di configurazione descritti in questo argomento vengono presentati in ordine alfabetico e non nell'ordine in cui potrebbe disporli il codice.The configuration providers described in this topic are described in alphabetical order, not in the order that your code may arrange them. Ordinare i provider di configurazione nel codice in base alle specifiche priorità per le origini di configurazione sottostanti.Order configuration providers in your code to suit your priorities for the underlying configuration sources.

Una sequenza tipica di provider di configurazione è:A typical sequence of configuration providers is:

  1. File (appsettings.json, appsettings.{Environment}.json, dove {Environment} è l'ambiente di hosting corrente dell'app)Files (appsettings.json, appsettings.{Environment}.json, where {Environment} is the app's current hosting environment)
  2. Insieme di credenziali delle chiavi di AzureAzure Key Vault
  3. Segreti utente (Secret Manager) (sono nell'ambiente Development)User secrets (Secret Manager) (in the Development environment only)
  4. Variabili di ambienteEnvironment variables
  5. Argomenti della riga di comandoCommand-line arguments

È pratica comune posizionare il provider di configurazione della riga di comando per ultimo in una serie di provider per consentire agli argomenti della riga di comando di sostituire la configurazione impostata da altri provider.It's a common practice to position the Command-line Configuration Provider last in a series of providers to allow command-line arguments to override configuration set by the other providers.

Questa sequenza di provider viene applicata quando si inizializza un nuovo WebHostBuilder con CreateDefaultBuilder.This sequence of providers is put into place when you initialize a new WebHostBuilder with CreateDefaultBuilder. Per altre informazioni, vedere Host Web: Configurare un host.For more information, see Web Host: Set up a host.

ConfigureAppConfigurationConfigureAppConfiguration

Chiamare ConfigureAppConfiguration quando si crea l'host per specificare i provider di configurazione dell'app, oltre a quelli aggiunti automaticamente da CreateDefaultBuilder:Call ConfigureAppConfiguration when building the host to specify the app's configuration providers in addition to those added automatically by CreateDefaultBuilder:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

La configurazione fornita all'app in ConfigureAppConfiguration è disponibile durante l'avvio dell'app, incluso Startup.ConfigureServices.Configuration supplied to the app in ConfigureAppConfiguration is available during the app's startup, including Startup.ConfigureServices. Per altre informazioni, vedere la sezione Accedere alla configurazione durante l'avvio.For more information, see the Access configuration during startup section.

Provider di configurazione della riga di comandoCommand-line Configuration Provider

CommandLineConfigurationProvider carica la configurazione da coppie chiave-valore di argomenti della riga di comando in fase di esecuzione.The CommandLineConfigurationProvider loads configuration from command-line argument key-value pairs at runtime.

Per attivare la configurazione della riga di comando, metodo di estensione AddCommandLine viene chiamato su un'istanza di ConfigurationBuilder.To activate command-line configuration, the AddCommandLine extension method is called on an instance of ConfigurationBuilder.

AddCommandLine viene chiamato automaticamente quando si Inizializza un nuovo WebHostBuilder con CreateDefaultBuilder.AddCommandLine is automatically called when you initialize a new WebHostBuilder with CreateDefaultBuilder. Per altre informazioni, vedere Host Web: Configurare un host.For more information, see Web Host: Set up a host.

CreateDefaultBuilder carica anche:CreateDefaultBuilder also loads:

  • Una configurazione facoltativa da appsettings.json e appsettings.{Environment}.json.Optional configuration from appsettings.json and appsettings.{Environment}.json.
  • Segreti utente (Secret Manager) (nell'ambiente Development).User secrets (Secret Manager) (in the Development environment).
  • Variabili di ambiente.Environment variables.

CreateDefaultBuilder aggiunge il provider di configurazione della riga di comando per ultimo.CreateDefaultBuilder adds the Command-line Configuration Provider last. Gli argomenti della riga di comando passati in fase di esecuzione sostituiscono la configurazione impostata dagli altri provider.Command-line arguments passed at runtime override configuration set by the other providers.

CreateDefaultBuilder opera durante la creazione dell'host.CreateDefaultBuilder acts when the host is constructed. Pertanto, la configurazione della riga di comando attivata da CreateDefaultBuilder può influire sul modo in cui l'host viene configurato.Therefore, command-line configuration activated by CreateDefaultBuilder can affect how the host is configured.

Chiamare ConfigureAppConfiguration quando si crea l'host per specificare la configurazione dell'app.Call ConfigureAppConfiguration when building the host to specify the app's configuration.

AddCommandLine è già stato chiamato da CreateDefaultBuilder.AddCommandLine has already been called by CreateDefaultBuilder. Se è necessario specificare la configurazione dell'app ed è ancora possibile eseguire l'override della configurazione con argomenti della riga di comando, chiamare i provider aggiuntivi dell'app in ConfigureAppConfiguration e chiamare infine AddCommandLine.If you need to provide app configuration and still be able to override that configuration with command-line arguments, call the app's additional providers in ConfigureAppConfiguration and call AddCommandLine last.

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                // Call other providers here and call AddCommandLine last.
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

Quando si crea un WebHostBuilder direttamente, chiamare UseConfiguration con la configurazione:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

var config = new ConfigurationBuilder()
    // Call additional providers here as needed.
    // Call AddCommandLine last to allow arguments to override other configuration.
    .AddCommandLine(args)
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

EsempioExample

L'app di esempio consente di sfruttare il metodo di servizio statico CreateDefaultBuilder per creare l'host, che include una chiamata a AddCommandLine.The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes a call to AddCommandLine.

  1. Aprire un prompt dei comandi nella directory del progetto.Open a command prompt in the project's directory.
  2. Fornire un argomento della riga di comando per il comando dotnet run, dotnet run CommandLineKey=CommandLineValue.Supply a command-line argument to the dotnet run command, dotnet run CommandLineKey=CommandLineValue.
  3. Dopo che l'app è in esecuzione, aprire un browser per l'app all'indirizzo http://localhost:5000.After the app is running, open a browser to the app at http://localhost:5000.
  4. Notare che l'output contiene la coppia chiave-valore per l'argomento della riga di comando di configurazione fornito per dotnet run.Observe that the output contains the key-value pair for the configuration command-line argument provided to dotnet run.

ArgomentiArguments

Il valore deve seguire un segno di uguale (=) o la chiave deve avere un prefisso (-- o /) quando il valore segue uno spazio.The value must follow an equals sign (=), or the key must have a prefix (-- or /) when the value follows a space. Il valore può essere null se viene usato un segno di uguale (ad esempio, CommandLineKey=).The value can be null if an equals sign is used (for example, CommandLineKey=).

Prefisso chiaveKey prefix EsempioExample
Nessun prefissoNo prefix CommandLineKey1=value1
Due trattini (--)Two dashes (--) --CommandLineKey2=value2, --CommandLineKey2 value2--CommandLineKey2=value2, --CommandLineKey2 value2
Barra (/)Forward slash (/) /CommandLineKey3=value3, /CommandLineKey3 value3/CommandLineKey3=value3, /CommandLineKey3 value3

Nello stesso comando, non mischiare coppie chiave-valore di argomenti della riga di comando che usano un segno di uguale con coppie chiave-valore che usano uno spazio.Within the same command, don't mix command-line argument key-value pairs that use an equals sign with key-value pairs that use a space.

Comandi di esempio:Example commands:

dotnet run CommandLineKey1=value1 --CommandLineKey2=value2 /CommandLineKey3=value3
dotnet run --CommandLineKey1 value1 /CommandLineKey2 value2
dotnet run CommandLineKey1= CommandLineKey2=value2

Mapping di sostituzioneSwitch mappings

I mapping di sostituzione consentono di usare la logica di sostituzione del nome della chiave.Switch mappings allow key name replacement logic. Quando si crea manualmente la configurazione con un ConfigurationBuilder, è possibile specificare un dizionario di mapping di sostituzione per il metodo AddCommandLine.When you manually build configuration with a ConfigurationBuilder, you can provide a dictionary of switch replacements to the AddCommandLine method.

Quando viene utilizzato il dizionario dei mapping di sostituzione, nel dizionario viene controllata la presenza di una chiave corrispondente alla chiave fornita da un argomento della riga di comando.When the switch mappings dictionary is used, the dictionary is checked for a key that matches the key provided by a command-line argument. Se la chiave della riga di comando viene trovata nel dizionario, il valore del dizionario (la sostituzione della chiave) viene passato nuovamente per impostare la coppia chiave-valore nella configurazione dell'app.If the command-line key is found in the dictionary, the dictionary value (the key replacement) is passed back to set the key-value pair into the app's configuration. Un mapping di sostituzione è necessario per le chiavi della riga di comando con un trattino singolo (-) come prefisso.A switch mapping is required for any command-line key prefixed with a single dash (-).

Regole principali del dizionario dei mapping di sostituzione:Switch mappings dictionary key rules:

  • Le sostituzioni devono iniziare con un trattino (-) o un trattino doppio (--).Switches must start with a dash (-) or double-dash (--).
  • Il dizionario dei mapping di sostituzione non deve contenere chiavi duplicate.The switch mappings dictionary must not contain duplicate keys.

Chiamare ConfigureAppConfiguration quando si crea l'host per specificare la configurazione dell'app:Call ConfigureAppConfiguration when building the host to specify the app's configuration:

public class Program
{
    public static readonly Dictionary<string, string> _switchMappings = 
        new Dictionary<string, string>
        {
            { "-CLKey1", "CommandLineKey1" },
            { "-CLKey2", "CommandLineKey2" }
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    // Do not pass the args to CreateDefaultBuilder
    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder()
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddCommandLine(args, _switchMappings);
            })
            .UseStartup<Startup>();
}

Come illustrato nell'esempio precedente, la chiamata a CreateDefaultBuilder non deve passare argomenti quando vengono usati i mapping di sostituzione.As shown in the preceding example, the call to CreateDefaultBuilder shouldn't pass arguments when switch mappings are used. La chiamata AddCommandLine del metodo CreateDefaultBuilder non include sostituzioni mappate e non è possibile passare il dizionario dei mapping di sostituzione a CreateDefaultBuilder.CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and there's no way to pass the switch mapping dictionary to CreateDefaultBuilder. Se gli argomenti includono una sostituzione mappata e vengono passati a CreateDefaultBuilder, l'inizializzazione del rispettivo provider AddCommandLine non riesce con FormatException.If the arguments include a mapped switch and are passed to CreateDefaultBuilder, its AddCommandLine provider fails to initialize with a FormatException. La soluzione consiste nel non passare gli argomenti a CreateDefaultBuilder consentendo invece al metodo AddCommandLine del metodo ConfigurationBuilder di elaborare entrambi gli argomenti e il dizionario dei mapping di sostituzione.The solution isn't to pass the arguments to CreateDefaultBuilder but instead to allow the ConfigurationBuilder method's AddCommandLine method to process both the arguments and the switch mapping dictionary.

Il dizionario dei mapping di sostituzione creato contiene i dati visualizzati nella tabella seguente.After the switch mappings dictionary is created, it contains the data shown in the following table.

ChiaveKey ValueValue
-CLKey1 CommandLineKey1
-CLKey2 CommandLineKey2

Se le chiavi con mapping di sostituzione vengono usate all'avvio dell'app, la configurazione riceve il valore di configurazione per la chiave fornita dal dizionario:If the switch-mapped keys are used when starting the app, configuration receives the configuration value on the key supplied by the dictionary:

dotnet run -CLKey1=value1 -CLKey2=value2

Dopo aver eseguito il comando precedente, la configurazione contiene i valori mostrati nella tabella seguente.After running the preceding command, configuration contains the values shown in the following table.

ChiaveKey ValueValue
CommandLineKey1 value1
CommandLineKey2 value2

Provider di configurazione delle variabili di ambienteEnvironment Variables Configuration Provider

EnvironmentVariablesConfigurationProvider carica la configurazione da coppie chiave-valore di variabili di ambiente in fase di esecuzione.The EnvironmentVariablesConfigurationProvider loads configuration from environment variable key-value pairs at runtime.

Per attivare la configurazione delle variabili di ambiente, chiamare il metodo di estensione AddEnvironmentVariables su un'istanza di ConfigurationBuilder.To activate environment variables configuration, call the AddEnvironmentVariables extension method on an instance of ConfigurationBuilder.

Quando si usano chiavi gerarchiche in variabili di ambiente, il separatore due punti (:) potrebbe non funzionare in tutte le piattaforme (ad esempio in Bash).When working with hierarchical keys in environment variables, a colon separator (:) may not work on all platforms (for example, Bash). Il doppio carattere di sottolineatura (__) è supportato da tutte le piattaforme e viene sostituito con due punti.A double underscore (__) is supported by all platforms and is replaced by a colon.

Servizio App di Azure consente di impostare variabili di ambiente nel portale di Azure che possono sostituire la configurazione delle app tramite il provider di configurazione delle variabili di ambiente.Azure App Service permits you to set environment variables in the Azure Portal that can override app configuration using the Environment Variables Configuration Provider. Per altre informazioni, vedere App Azure: Eseguire l'override della configurazione delle app usando il portale di Azure.For more information, see Azure Apps: Override app configuration using the Azure Portal.

AddEnvironmentVariables consente di caricare variabili di ambiente con prefisso ASPNETCORE_ per la configurazione host quando viene inizializzato un nuovo elemento WebHostBuilder.AddEnvironmentVariables is used to load environment variables prefixed with ASPNETCORE_ for host configuration when a new WebHostBuilder is initialized. Per altre informazioni, vedere Host Web: Configurare un host.For more information, see Web Host: Set up a host.

CreateDefaultBuilder carica anche:CreateDefaultBuilder also loads:

  • Configurazione delle app dalle variabili di ambiente senza prefisso chiamando AddEnvironmentVariables senza prefisso.App configuration from unprefixed environment variables by calling AddEnvironmentVariables without a prefix.
  • Una configurazione facoltativa da appsettings.json e appsettings.{Environment}.json.Optional configuration from appsettings.json and appsettings.{Environment}.json.
  • Segreti utente (Secret Manager) (nell'ambiente Development).User secrets (Secret Manager) (in the Development environment).
  • Argomenti della riga di comando.Command-line arguments.

Il provider di configurazione delle variabili di ambiente viene chiamato dopo aver stabilito la configurazione dai segreti utente e dai file appsettings.The Environment Variables Configuration Provider is called after configuration is established from user secrets and appsettings files. La chiamata del provider in questa posizione consente alle variabili di ambiente lette in fase di esecuzione di sostituire la configurazione impostata dai segreti utente e dai file appsettings.Calling the provider in this position allows the environment variables read at runtime to override configuration set by user secrets and appsettings files.

Chiamare ConfigureAppConfiguration quando si crea l'host per specificare la configurazione dell'app.Call ConfigureAppConfiguration when building the host to specify the app's configuration.

Se è necessario specificare la configurazione dell'app da variabili di ambiente aggiuntive, chiamare i provider aggiuntivi dell'app in ConfigureAppConfiguration e chiamare AddEnvironmentVariables con il prefisso.If you need to provide app configuration from additional environment variables, call the app's additional providers in ConfigureAppConfiguration and call AddEnvironmentVariables with the prefix.

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                // Call additional providers here as needed.
                // Call AddEnvironmentVariables last if you need to allow
                // environment variables to override values from other 
                // providers.
                config.AddEnvironmentVariables(prefix: "PREFIX_");
            })
            .UseStartup<Startup>();
}

Quando si crea un WebHostBuilder direttamente, chiamare UseConfiguration con la configurazione:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

var config = new ConfigurationBuilder()
    .AddEnvironmentVariables()
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

EsempioExample

L'app di esempio consente di sfruttare il metodo di servizio statico CreateDefaultBuilder per creare l'host, che include una chiamata a AddEnvironmentVariables.The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes a call to AddEnvironmentVariables.

  1. Eseguire l'app di esempio.Run the sample app. Aprire un browser per l'app all'indirizzo http://localhost:5000.Open a browser to the app at http://localhost:5000.
  2. Notare che l'output contiene la coppia chiave-valore per la variabile di ambiente ENVIRONMENT.Observe that the output contains the key-value pair for the environment variable ENVIRONMENT. Il valore riflette l'ambiente in cui l'app è in esecuzione, in genere Development durante l'esecuzione locale.The value reflects the environment in which the app is running, typically Development when running locally.

Per mantenere breve l'elenco delle variabili di ambiente restituito dall'app, l'app filtra le variabili di ambiente includendo quelle che iniziano come segue:To keep the list of environment variables rendered by the app short, the app filters environment variables to those that start with the following:

  • ASPNETCORE_ASPNETCORE_
  • urlsurls
  • RegistrazioneLogging
  • ENVIRONMENTENVIRONMENT
  • contentRootcontentRoot
  • AllowedHostsAllowedHosts
  • applicationNameapplicationName
  • CommandLineCommandLine

Se si desidera esporre tutte le variabili di ambiente disponibili all'app, modificare FilteredConfiguration in Pages/Index.cshtml.cs come segue:If you wish to expose all of the environment variables available to the app, change the FilteredConfiguration in Pages/Index.cshtml.cs to the following:

FilteredConfiguration = _config.AsEnumerable();

PrefissiPrefixes

Le variabili di ambiente caricate nella configurazione dell'app vengono filtrate quando si specifica un prefisso per il metodo AddEnvironmentVariables.Environment variables loaded into the app's configuration are filtered when you supply a prefix to the AddEnvironmentVariables method. Ad esempio, per filtrare le variabili di ambiente in base al prefisso CUSTOM_, fornire il prefisso al provider di configurazione:For example, to filter environment variables on the prefix CUSTOM_, supply the prefix to the configuration provider:

var config = new ConfigurationBuilder()
    .AddEnvironmentVariables("CUSTOM_")
    .Build();

Il prefisso viene rimosso quando vengono create le coppie chiave-valore della configurazione.The prefix is stripped off when the configuration key-value pairs are created.

Il metodo di servizio statico CreateDefaultBuilder crea un WebHostBuilder per stabilire l'host dell'app.The static convenience method CreateDefaultBuilder creates a WebHostBuilder to establish the app's host. Quando viene creato WebHostBuilder, la configurazione dell'host corrispondente viene individuata nelle variabili di ambiente con il prefisso ASPNETCORE_.When WebHostBuilder is created, it finds its host configuration in environment variables prefixed with ASPNETCORE_.

Prefissi della stringa di connessioneConnection string prefixes

L'API di configurazione prevede regole di elaborazione speciali per quattro variabili di ambiente di stringa di connessione coinvolte nella configurazione di stringhe di connessione di Azure per l'ambiente dell'app.The Configuration API has special processing rules for four connection string environment variables involved in configuring Azure connection strings for the app environment. Le variabili di ambiente con i prefissi indicati nella tabella vengono caricate nell'app se non viene fornito alcun prefisso a AddEnvironmentVariables.Environment variables with the prefixes shown in the table are loaded into the app if no prefix is supplied to AddEnvironmentVariables.

Prefisso della stringa di connessioneConnection string prefix ProviderProvider
CUSTOMCONNSTR_ Provider personalizzatoCustom provider
MYSQLCONNSTR_ MySQLMySQL
SQLAZURECONNSTR_ Database SQL di AzureAzure SQL Database
SQLCONNSTR_ SQL ServerSQL Server

Quando una variabile di ambiente viene individuata e caricata nella configurazione con uno qualsiasi dei quattro prefissi indicati nella tabella:When an environment variable is discovered and loaded into configuration with any of the four prefixes shown in the table:

  • La chiave di configurazione viene creata rimuovendo il prefisso della variabile di ambiente e aggiungendo una sezione per la chiave di configurazione (ConnectionStrings).The configuration key is created by removing the environment variable prefix and adding a configuration key section (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).A new configuration key-value pair is created that represents the database connection provider (except for CUSTOMCONNSTR_, which has no stated provider).
Chiave della variabile di ambienteEnvironment variable key Chiave di configurazione convertitaConverted configuration key Voce di configurazione del providerProvider configuration entry
CUSTOMCONNSTR_<KEY> ConnectionStrings:<KEY> Voce di configurazione non creata.Configuration entry not created.
MYSQLCONNSTR_<KEY> ConnectionStrings:<KEY> Chiave: ConnectionStrings:<KEY>_ProviderName:Key: ConnectionStrings:<KEY>_ProviderName:
Valore: MySql.Data.MySqlClientValue: MySql.Data.MySqlClient
SQLAZURECONNSTR_<KEY> ConnectionStrings:<KEY> Chiave: ConnectionStrings:<KEY>_ProviderName:Key: ConnectionStrings:<KEY>_ProviderName:
Valore: System.Data.SqlClientValue: System.Data.SqlClient
SQLCONNSTR_<KEY> ConnectionStrings:<KEY> Chiave: ConnectionStrings:<KEY>_ProviderName:Key: ConnectionStrings:<KEY>_ProviderName:
Valore: System.Data.SqlClientValue: System.Data.SqlClient

Provider di configurazione dei fileFile Configuration Provider

FileConfigurationProvider è la classe base per il caricamento della configurazione dal file system.FileConfigurationProvider is the base class for loading configuration from the file system. I provider di configurazione seguenti sono dedicati per specifici tipi di file:The following configuration providers are dedicated to specific file types:

Provider di configurazione INIINI Configuration Provider

IniConfigurationProvider carica la configurazione da coppie chiave-valore di file INI in fase di esecuzione.The IniConfigurationProvider loads configuration from INI file key-value pairs at runtime.

Per attivare la configurazione di file INI, chiamare il metodo di estensione AddIniFile su un'istanza di ConfigurationBuilder.To activate INI file configuration, call the AddIniFile extension method on an instance of ConfigurationBuilder.

I due punti possono essere usati come delimitatore di sezione nella configurazione di file INI.The colon can be used to as a section delimiter in INI file configuration.

Gli overload consentono di specificare:Overloads permit specifying:

  • Se il file è facoltativo.Whether the file is optional.
  • Se la configurazione viene ricaricata se viene modificato il file.Whether the configuration is reloaded if the file changes.
  • Il IFileProvider usato per accedere al file.The IFileProvider used to access the file.

Chiamare ConfigureAppConfiguration quando si crea l'host per specificare la configurazione dell'app:Call ConfigureAppConfiguration when building the host to specify the app's configuration:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddIniFile(
                    "config.ini", optional: true, reloadOnChange: true);
            })
            .UseStartup<Startup>();
}

Il percorso di base è impostato con SetBasePath.The base path is set with SetBasePath. SetBasePath è incluso nel pacchetto Microsoft.Extensions.Configuration.FileExtensions, a sua volta incluso nel metapacchetto Microsoft.AspNetCore.App.SetBasePath is in the Microsoft.Extensions.Configuration.FileExtensions package, which is in the Microsoft.AspNetCore.App metapackage.

Quando si crea un WebHostBuilder direttamente, chiamare UseConfiguration con la configurazione:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

var config = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddIniFile("config.ini", optional: true, reloadOnChange: true)
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

Il percorso di base è impostato con SetBasePath.The base path is set with SetBasePath. SetBasePath è incluso nel pacchetto Microsoft.Extensions.Configuration.FileExtensions, a sua volta incluso nel metapacchetto Microsoft.AspNetCore.App.SetBasePath is in the Microsoft.Extensions.Configuration.FileExtensions package, which is in the Microsoft.AspNetCore.App metapackage.

Un esempio generico di un file di configurazione INI:A generic example of an INI configuration file:

[section0]
key0=value
key1=value

[section1]
subsection:key=value

[section2:subsection0]
key=value

[section2:subsection1]
key=value

Il file di configurazione precedente carica le chiavi seguenti con value:The previous configuration file loads the following keys with value:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:subsection:keysection1:subsection:key
  • section2:subsection0:keysection2:subsection0:key
  • section2:subsection1:keysection2:subsection1:key

Provider di configurazione JSONJSON Configuration Provider

Il JsonConfigurationProvider carica la configurazione da coppie chiave-valore di file JSON in fase di esecuzione.The JsonConfigurationProvider loads configuration from JSON file key-value pairs during runtime.

Per attivare la configurazione di file JSON, chiamare il metodo di estensione AddJsonFile su un'istanza di ConfigurationBuilder.To activate JSON file configuration, call the AddJsonFile extension method on an instance of ConfigurationBuilder.

Gli overload consentono di specificare:Overloads permit specifying:

  • Se il file è facoltativo.Whether the file is optional.
  • Se la configurazione viene ricaricata se viene modificato il file.Whether the configuration is reloaded if the file changes.
  • Il IFileProvider usato per accedere al file.The IFileProvider used to access the file.

AddJsonFile viene chiamato automaticamente due volte quando si inizializza un nuovo WebHostBuilder con CreateDefaultBuilder.AddJsonFile is automatically called twice when you initialize a new WebHostBuilder with CreateDefaultBuilder. Il metodo viene chiamato per caricare la configurazione da:The method is called to load configuration from:

  • appsettings.json – Questo file viene letto per primo.appsettings.json – This file is read first. La versione dell'ambiente del file può sostituire i valori forniti dal file appsettings.json.The environment version of the file can override the values provided by the appsettings.json file.
  • appsettings.{Environment}.json – La versione dell'ambiente del file viene caricata in base a IHostingEnvironment.EnvironmentName.appsettings.{Environment}.json – The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName.

Per altre informazioni, vedere Host Web: Configurare un host.For more information, see Web Host: Set up a host.

CreateDefaultBuilder carica anche:CreateDefaultBuilder also loads:

Il provider di configurazione JSON viene stabilito per primo.The JSON Configuration Provider is established first. I segreti utente, le variabili di ambiente e gli argomenti della riga di comando sostituiscono quindi la configurazione impostata dai file appsettings.Therefore, user secrets, environment variables, and command-line arguments override configuration set by the appsettings files.

Chiamare ConfigureAppConfiguration quando si crea l'host per specificare la configurazione dell'app per file diversi da appsettings.json e appsettings.{Environment}.json:Call ConfigureAppConfiguration when building the host to specify the app's configuration for files other than appsettings.json and appsettings.{Environment}.json:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddJsonFile(
                    "config.json", optional: true, reloadOnChange: true);
            })
            .UseStartup<Startup>();
}

Il percorso di base è impostato con SetBasePath.The base path is set with SetBasePath. SetBasePath è incluso nel pacchetto Microsoft.Extensions.Configuration.FileExtensions, a sua volta incluso nel metapacchetto Microsoft.AspNetCore.App.SetBasePath is in the Microsoft.Extensions.Configuration.FileExtensions package, which is in the Microsoft.AspNetCore.App metapackage.

Quando si crea un WebHostBuilder direttamente, chiamare UseConfiguration con la configurazione:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

var config = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("config.json", optional: true, reloadOnChange: true)
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

Il percorso di base è impostato con SetBasePath.The base path is set with SetBasePath. SetBasePath è incluso nel pacchetto Microsoft.Extensions.Configuration.FileExtensions, a sua volta incluso nel metapacchetto Microsoft.AspNetCore.App.SetBasePath is in the Microsoft.Extensions.Configuration.FileExtensions package, which is in the Microsoft.AspNetCore.App metapackage.

EsempioExample

L'app di esempio consente di sfruttare il metodo di servizio statico CreateDefaultBuilder per creare l'host, che include due chiamate a AddJsonFile.The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes two calls to AddJsonFile. La configurazione viene caricata da appsettings.json e appsettings.{Environment}.json.Configuration is loaded from appsettings.json and appsettings.{Environment}.json.

  1. Eseguire l'app di esempio.Run the sample app. Aprire un browser per l'app all'indirizzo http://localhost:5000.Open a browser to the app at http://localhost:5000.
  2. Notare che l'output contiene coppie chiave-valore per la configurazione mostrata nella tabella in base all'ambiente.Observe that the output contains key-value pairs for the configuration shown in the table depending on the environment. Le chiavi di configurazione di registrazione usano i due punti (:) come separatore gerarchico.Logging configuration keys use the colon (:) as a hierarchical separator.
ChiaveKey Valore DevelopmentDevelopment Value Valore ProductionProduction Value
Logging:LogLevel:SystemLogging:LogLevel:System InformazioniInformation InformazioniInformation
Logging:LogLevel:MicrosoftLogging:LogLevel:Microsoft InformazioniInformation InformazioniInformation
Logging:LogLevel:DefaultLogging:LogLevel:Default DebugDebug ErrorError
AllowedHostsAllowedHosts * *

Provider di configurazione XMLXML Configuration Provider

Il XmlConfigurationProvider carica la configurazione da coppie chiave-valore di file XML in fase di esecuzione.The XmlConfigurationProvider loads configuration from XML file key-value pairs at runtime.

Per attivare la configurazione di file XML, chiamare il metodo di estensione AddXmlFile su un'istanza di ConfigurationBuilder.To activate XML file configuration, call the AddXmlFile extension method on an instance of ConfigurationBuilder.

Gli overload consentono di specificare:Overloads permit specifying:

  • Se il file è facoltativo.Whether the file is optional.
  • Se la configurazione viene ricaricata se viene modificato il file.Whether the configuration is reloaded if the file changes.
  • Il IFileProvider usato per accedere al file.The IFileProvider used to access the file.

Il nodo radice del file di configurazione viene ignorato quando vengono create le coppie chiave-valore della configurazione.The root node of the configuration file is ignored when the configuration key-value pairs are created. Non specificare una definizione DTD (Document Type Definition) o uno spazio dei nomi nel file.Don't specify a Document Type Definition (DTD) or namespace in the file.

Chiamare ConfigureAppConfiguration quando si crea l'host per specificare la configurazione dell'app:Call ConfigureAppConfiguration when building the host to specify the app's configuration:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddXmlFile(
                    "config.xml", optional: true, reloadOnChange: true);
            })
            .UseStartup<Startup>();
}

Il percorso di base è impostato con SetBasePath.The base path is set with SetBasePath. SetBasePath è incluso nel pacchetto Microsoft.Extensions.Configuration.FileExtensions, a sua volta incluso nel metapacchetto Microsoft.AspNetCore.App.SetBasePath is in the Microsoft.Extensions.Configuration.FileExtensions package, which is in the Microsoft.AspNetCore.App metapackage.

Quando si crea un WebHostBuilder direttamente, chiamare UseConfiguration con la configurazione:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

var config = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddXmlFile("config.xml", optional: true, reloadOnChange: true)
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

Il percorso di base è impostato con SetBasePath.The base path is set with SetBasePath. SetBasePath è incluso nel pacchetto Microsoft.Extensions.Configuration.FileExtensions, a sua volta incluso nel metapacchetto Microsoft.AspNetCore.App.SetBasePath is in the Microsoft.Extensions.Configuration.FileExtensions package, which is in the Microsoft.AspNetCore.App metapackage.

I file di configurazione XML possono usare nomi di elementi distinti per le sezioni ripetute:XML configuration files can use distinct element names for repeating sections:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <section0>
    <key0>value</key0>
    <key1>value</key1>
  </section0>
  <section1>
    <key0>value</key0>
    <key1>value</key1>
  </section1>
</configuration>

Il file di configurazione precedente carica le chiavi seguenti con value:The previous configuration file loads the following keys with value:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:key0section1:key0
  • section1:key1section1:key1

La ripetizione di elementi che usano lo stesso nome di elemento funziona se si usa l'attributo name per distinguere gli elementi:Repeating elements that use the same element name work if the name attribute is used to distinguish the elements:

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

Il file di configurazione precedente carica le chiavi seguenti con value:The previous configuration file loads the following keys with value:

  • section:section0:key:key0section:section0:key:key0
  • section:section0:key:key1section:section0:key:key1
  • section:section1:key:key0section:section1:key:key0
  • section:section1:key:key1section:section1:key:key1

È possibile usare attributi per fornire valori:Attributes can be used to supply values:

<?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:The previous configuration file loads the following keys with value:

  • key:attributekey:attribute
  • section:key:attributesection:key:attribute

Provider di configurazione KeyPerFileKey-per-file Configuration Provider

Il KeyPerFileConfigurationProvider usa i file di una directory come coppie chiave-valore della configurazione.The KeyPerFileConfigurationProvider uses a directory's files as configuration key-value pairs. La chiave è il nome del file.The key is the file name. Il valore contiene il contenuto del file.The value contains the file's contents. Il provider di configurazione KeyPerFile viene usato in scenari di hosting Docker.The Key-per-file Configuration Provider is used in Docker hosting scenarios.

Per attivare la configurazione chiave-per-file, chiamare il metodo di estensione AddKeyPerFile su un'istanza di ConfigurationBuilder.To activate key-per-file configuration, call the AddKeyPerFile extension method on an instance of ConfigurationBuilder. Il directoryPath per i file deve essere un percorso assoluto.The directoryPath to the files must be an absolute path.

Gli overload consentono di specificare:Overloads permit specifying:

  • Un delegato Action<KeyPerFileConfigurationSource> che configura l'origine.An Action<KeyPerFileConfigurationSource> delegate that configures the source.
  • Se la directory è facoltativa e il percorso della directory.Whether the directory is optional and the path to the directory.

Il doppio carattere di sottolineatura (__) viene usato come delimitatore per le chiavi di configurazione nei nomi dei file.The double-underscore (__) is used as a configuration key delimiter in file names. Ad esempio, il nome di file Logging__LogLevel__System produce la chiave di configurazione Logging:LogLevel:System.For example, the file name Logging__LogLevel__System produces the configuration key Logging:LogLevel:System.

Chiamare ConfigureAppConfiguration quando si crea l'host per specificare la configurazione dell'app:Call ConfigureAppConfiguration when building the host to specify the app's configuration:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                var path = Path.Combine(
                    Directory.GetCurrentDirectory(), "path/to/files");
                config.AddKeyPerFile(directoryPath: path, optional: true);
            })
            .UseStartup<Startup>();
}

Il percorso di base è impostato con SetBasePath.The base path is set with SetBasePath. SetBasePath è incluso nel pacchetto Microsoft.Extensions.Configuration.FileExtensions, a sua volta incluso nel metapacchetto Microsoft.AspNetCore.App.SetBasePath is in the Microsoft.Extensions.Configuration.FileExtensions package, which is in the Microsoft.AspNetCore.App metapackage.

Quando si crea un WebHostBuilder direttamente, chiamare UseConfiguration con la configurazione:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

var path = Path.Combine(Directory.GetCurrentDirectory(), "path/to/files");
var config = new ConfigurationBuilder()
    .AddKeyPerFile(directoryPath: path, optional: true)
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

Provider di configurazione della memoriaMemory Configuration Provider

Il MemoryConfigurationProvider usa una raccolta in memoria come coppie chiave-valore della configurazione.The MemoryConfigurationProvider uses an in-memory collection as configuration key-value pairs.

Per attivare la configurazione della raccolta in memoria, chiamare il metodo di estensione AddInMemoryCollection su un'istanza di ConfigurationBuilder.To activate in-memory collection configuration, call the AddInMemoryCollection extension method on an instance of ConfigurationBuilder.

Il provider di configurazione può essere inizializzato con un IEnumerable<KeyValuePair<String,String>>.The configuration provider can be initialized with an IEnumerable<KeyValuePair<String,String>>.

Chiamare ConfigureAppConfiguration quando si crea l'host per specificare la configurazione dell'app:Call ConfigureAppConfiguration when building the host to specify the app's configuration:

public class Program
{
    public static readonly Dictionary<string, string> _dict = 
        new Dictionary<string, string>
        {
            {"MemoryCollectionKey1", "value1"},
            {"MemoryCollectionKey2", "value2"}
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(_dict);
            })
            .UseStartup<Startup>();
}

Quando si crea un WebHostBuilder direttamente, chiamare UseConfiguration con la configurazione:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

var dict = new Dictionary<string, string>
    {
        {"MemoryCollectionKey1", "value1"},
        {"MemoryCollectionKey2", "value2"}
    };

var config = new ConfigurationBuilder()
    .AddInMemoryCollection(dict)
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

GetValueGetValue

ConfigurationBinder.GetValue<T> estrae un valore dalla configurazione con una chiave specificata e lo converte nel tipo specificato.ConfigurationBinder.GetValue<T> extracts a value from configuration with a specified key and converts it to the specified type. Un overload consente di specificare un valore predefinito se non viene trovata la chiave.An overload permits you to provide a default value if the key isn't found.

L'esempio seguente:The following example:

  • Estrae il valore di stringa dalla configurazione con la chiave NumberKey.Extracts the string value from configuration with the key NumberKey. Se NumberKey non viene trovato nelle chiavi di configurazione, viene usato il valore predefinito di 99.If NumberKey isn't found in the configuration keys, the default value of 99 is used.
  • Assegna al valore il tipo int.Types the value as an int.
  • Memorizza il valore nella proprietà NumberConfig per l'uso da parte della pagina.Stores the value in the NumberConfig property for use by the page.
public class IndexModel : PageModel
{
    public IndexModel(IConfiguration config)
    {
        _config = config;
    }

    public int NumberConfig { get; private set; }

    public void OnGet()
    {
        NumberConfig = _config.GetValue<int>("NumberKey", 99);
    }
}

GetSection, GetChildren ed ExistsGetSection, GetChildren, and Exists

Per gli esempi che seguono, prendere in considerazione il file JSON seguente.For the examples that follow, consider the following JSON file. Vengono trovate quattro chiavi in due sezioni, una delle quali include una coppia di sottosezioni:Four keys are found across two sections, one of which includes a pair of subsections:

{
  "section0": {
    "key0": "value",
    "key1": "value"
  },
  "section1": {
    "key0": "value",
    "key1": "value"
  },
  "section2": {
    "subsection0" : {
      "key0": "value",
      "key1": "value"
    },
    "subsection1" : {
      "key0": "value",
      "key1": "value"
    }
  }
}

Quando il file viene letto nella configurazione, vengono create le chiavi gerarchiche univoche seguenti per contenere i valori di configurazione:When the file is read into configuration, the following unique hierarchical keys are created to hold the configuration values:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:key0section1:key0
  • section1:key1section1:key1
  • section2:subsection0:key0section2:subsection0:key0
  • section2:subsection0:key1section2:subsection0:key1
  • section2:subsection1:key0section2:subsection1:key0
  • section2:subsection1:key1section2:subsection1:key1

GetSectionGetSection

IConfiguration.GetSection estrae una sottosezione della configurazione con la chiave di sottosezione specificata.IConfiguration.GetSection extracts a configuration subsection with the specified subsection key. GetSection è incluso nel pacchetto Microsoft.Extensions.Configuration, a sua volta incluso nel metapacchetto Microsoft.AspNetCore.App.GetSection is in the Microsoft.Extensions.Configuration package, which is in the Microsoft.AspNetCore.App metapackage.

Per restituire una IConfigurationSection che contiene solo le coppie chiave-valore in section1, chiamare GetSection e fornire il nome della sezione:To return an IConfigurationSection containing only the key-value pairs in section1, call GetSection and supply the section name:

var configSection = _config.GetSection("section1");

configSection non ha un valore, ma solo una chiave e un percorso.The configSection doesn't have a value, only a key and a path.

In modo analogo, per ottenere i valori per le chiavi in section2:subsection0, chiamare GetSection e fornire il percorso della sezione:Similarly, to obtain the values for keys in section2:subsection0, call GetSection and supply the section path:

var configSection = _config.GetSection("section2:subsection0");

GetSection non restituisce mai null.GetSection never returns null. Se non viene trovata una sezione corrispondente, viene restituita una IConfigurationSection vuota.If a matching section isn't found, an empty IConfigurationSection is returned.

Quando GetSection restituisce una sezione corrispondente, Value non viene compilata.When GetSection returns a matching section, Value isn't populated. Quando la sezione esiste, vengono restituiti Key e Path.A Key and Path are returned when the section exists.

GetChildrenGetChildren

Una chiamata a IConfiguration.GetChildren per section2 ottiene una IEnumerable<IConfigurationSection> che include:A call to IConfiguration.GetChildren on section2 obtains an IEnumerable<IConfigurationSection> that includes:

  • subsection0
  • subsection1
var configSection = _config.GetSection("section2");

var children = configSection.GetChildren();

EsistenteExists

Usare ConfigurationExtensions.Exists per determinare se esiste una sezione di configurazione:Use ConfigurationExtensions.Exists to determine if a configuration section exists:

var sectionExists = _config.GetSection("section2:subsection2").Exists();

Considerati i dati di esempio, sectionExists è false perché non esiste una sezione section2:subsection2 nei dati di configurazione.Given the example data, sectionExists is false because there isn't a section2:subsection2 section in the configuration data.

Eseguire l'associazione a una classeBind to a class

La configurazione può essere associata alle classi che rappresentano gruppi di impostazioni correlate usando il modello di opzioni.Configuration can be bound to classes that represent groups of related settings using the options pattern. Per ulteriori informazioni, vedere Modello di opzioni in ASP.NET Core.For more information, see Modello di opzioni in ASP.NET Core.

I valori di configurazione vengono restituiti come stringhe, ma la chiamata di Bind consente la costruzione di oggetti POCO.Configuration values are returned as strings, but calling Bind enables the construction of POCO objects. Bind è incluso nel pacchetto Microsoft.Extensions.Configuration.Binder, a sua volta incluso nel metapacchetto Microsoft.AspNetCore.App.Bind is in the Microsoft.Extensions.Configuration.Binder package, which is in the Microsoft.AspNetCore.App metapackage.

L'app di esempio contiene un modello Starship (Models/Starship.cs):The sample app contains a Starship model (Models/Starship.cs):

public class Starship
{
    public string Name { get; set; }
    public string Registry { get; set; }
    public string Class { get; set; }
    public decimal Length { get; set; }
    public bool Commissioned { get; set; }
}

La sezione starship del file starship.json crea la configurazione quando l'app di esempio usa il provider di configurazione JSON per caricare la configurazione:The starship section of the starship.json file creates the configuration when the sample app uses the JSON Configuration Provider to load the configuration:

{
  "starship": {
    "name": "USS Enterprise",
    "registry": "NCC-1701",
    "class": "Constitution",
    "length": 304.8,
    "commissioned": false
  },
  "trademark": "Paramount Pictures Corp. http://www.paramount.com"
}

Vengono create le coppie chiave-valore della configurazione seguenti:The following configuration key-value pairs are created:

ChiaveKey ValueValue
starship:namestarship:name USS EnterpriseUSS Enterprise
starship:registrystarship:registry NCC-1701NCC-1701
starship:classstarship:class ConstitutionConstitution
starship:lengthstarship:length 304.8304.8
starship:commissionedstarship:commissioned FalseFalse
trademarktrademark Paramount Pictures Corp. http://www.paramount.comParamount Pictures Corp. http://www.paramount.com

L'app di esempio chiama GetSection con la chiave starship.The sample app calls GetSection with the starship key. Le coppie chiave-valore starship sono isolate.The starship key-value pairs are isolated. Il metodo Bind viene chiamato sulla sottosezione passando un'istanza della classe Starship.The Bind method is called on the subsection passing in an instance of the Starship class. Dopo aver associato i valori dell'istanza, l'istanza viene assegnata a una proprietà per il rendering:After binding the instance values, the instance is assigned to a property for rendering:

var starship = new Starship();
_config.GetSection("starship").Bind(starship);
Starship = starship;

GetSection è incluso nel pacchetto Microsoft.Extensions.Configuration, a sua volta incluso nel metapacchetto Microsoft.AspNetCore.App.GetSection is in the Microsoft.Extensions.Configuration package, which is in the Microsoft.AspNetCore.App metapackage.

Associazione a un oggetto graficoBind to an object graph

Bind è in grado di associare un intero oggetto grafico POCO.Bind is capable of binding an entire POCO object graph. Bind è incluso nel pacchetto Microsoft.Extensions.Configuration.Binder, a sua volta incluso nel metapacchetto Microsoft.AspNetCore.App.Bind is in the Microsoft.Extensions.Configuration.Binder package, which is in the Microsoft.AspNetCore.App metapackage.

L'esempio contiene un modello TvShow il cui oggetto grafico include Metadata e le classi Actors (Models/TvShow.cs):The sample contains a TvShow model whose object graph includes Metadata and Actors classes (Models/TvShow.cs):

public class TvShow
{
    public Metadata Metadata { get; set; }
    public Actors Actors { get; set; }
    public string Legal { get; set; }
}

public class Metadata
{
    public string Series { get; set; }
    public string Title { get; set; }
    public DateTime AirDate { get; set; }
    public int Episodes { get; set; }
}

public class Actors
{
    public string Names { get; set; }
}

L'app di esempio ha un file tvshow.xml che contiene i dati di configurazione:The sample app has a tvshow.xml file containing the configuration data:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <tvshow>
    <metadata>
      <series>Dr. Who</series>
      <title>The Sun Makers</title>
      <airdate>11/26/1977</airdate>
      <episodes>4</episodes>
    </metadata>
    <actors>
      <names>Tom Baker, Louise Jameson, John Leeson</names>
    </actors>
    <legal>(c)1977 BBC https://www.bbc.co.uk/programmes/b006q2x0</legal>
  </tvshow>
</configuration>

La configurazione viene associata all'intero oggetto grafico TvShow con il metodo Bind.Configuration is bound to the entire TvShow object graph with the Bind method. L'istanza associata viene assegnata a una proprietà per il rendering:The bound instance is assigned to a property for rendering:

var tvShow = new TvShow();
_config.GetSection("tvshow").Bind(tvShow);
TvShow = tvShow;

ConfigurationBinder.Get<T> associa e restituisce il tipo specificato.ConfigurationBinder.Get<T> binds and returns the specified type. Get<T> può essere più comodo che usare Bind.Get<T> is more convenient than using Bind. Il codice seguente mostra come usare Get<T> con l'esempio precedente, che consente di assegnare l'istanza associata direttamente alla proprietà usata per il rendering:The following code shows how to use Get<T> with the preceding example, which allows the bound instance to be directly assigned to the property used for rendering:

TvShow = _config.GetSection("tvshow").Get<TvShow>();

Get è incluso nel pacchetto Microsoft.Extensions.Configuration.Binder, a sua volta incluso nel metapacchetto Microsoft.AspNetCore.App.Get is in the Microsoft.Extensions.Configuration.Binder package, which is in the Microsoft.AspNetCore.App metapackage. Get<T> è disponibile in ASP.NET Core 1.1 o versioni successive.Get<T> is available in ASP.NET Core 1.1 or later. GetSection è incluso nel pacchetto Microsoft.Extensions.Configuration, a sua volta incluso nel metapacchetto Microsoft.AspNetCore.App.GetSection is in the Microsoft.Extensions.Configuration package, which is in the Microsoft.AspNetCore.App metapackage.

Associare una matrice a una classeBind an array to a class

L'app di esempio dimostra i concetti spiegati in questa sezione.The sample app demonstrates the concepts explained in this section.

Il Bind supporta l'associazione di matrici agli oggetti usando gli indici delle matrici nelle chiavi di configurazione.The Bind supports binding arrays to objects using array indices in configuration keys. Qualsiasi formato di matrice che espone un segmento chiave numerico (:0:, :1:, … :{n}:) supporta l'associazione di matrici a una matrice di classi POCO.Any array format that exposes a numeric key segment (:0:, :1:, … :{n}:) is capable of array binding to a POCO class array. "Bind" è incluso nel pacchetto Microsoft.Extensions.Configuration.Binder, a sua volta incluso nel metapacchetto Microsoft.AspNetCore.App.`Bind`` is in the Microsoft.Extensions.Configuration.Binder package, which is in the Microsoft.AspNetCore.App metapackage.

Nota

L'associazione viene fornita per convenzione.Binding is provided by convention. I provider di configurazione personalizzati non devono implementare l'associazione di matrici.Custom configuration providers aren't required to implement array binding.

Elaborazione di matrici in memoriaIn-memory array processing

Prendere in considerazione le chiavi di configurazione e i valori indicati nella tabella seguente.Consider the configuration keys and values shown in the following table.

ChiaveKey ValueValue
array:entries:0array:entries:0 value0value0
array:entries:1array:entries:1 value1value1
array:entries:2array:entries:2 value2value2
array:entries:4array:entries:4 value4value4
array:entries:5array:entries:5 value5value5

Queste chiavi e i valori vengono caricati nell'app di esempio usando il provider di configurazione della memoria:These keys and values are loaded in the sample app using the Memory Configuration Provider:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

La matrice ignora un valore per l'indice #3.The array skips a value for index #3. Lo strumento di associazione di configurazione non è in grado di associare valori null o di creare voci null negli oggetti associati, situazione che diventerà chiara tra poco quando viene illustrato il risultato dell'associazione di questa matrice a un oggetto.The configuration binder isn't capable of binding null values or creating null entries in bound objects, which becomes clear in a moment when the result of binding this array to an object is demonstrated.

Nell'app di esempio, è disponibile una classe POCO per i dati di configurazione associati:In the sample app, a POCO class is available to hold the bound configuration data:

public class ArrayExample
{
    public string[] Entries { get; set; }
}

I dati di configurazione sono associati all'oggetto:The configuration data is bound to the object:

var arrayExample = new ArrayExample();
_config.GetSection("array").Bind(arrayExample);

GetSection è incluso nel pacchetto Microsoft.Extensions.Configuration, a sua volta incluso nel metapacchetto Microsoft.AspNetCore.App.GetSection is in the Microsoft.Extensions.Configuration package, which is in the Microsoft.AspNetCore.App metapackage.

È possibile usare anche la sintassi ConfigurationBinder.Get<T>, che produce codice più compatto:ConfigurationBinder.Get<T> syntax can also be used, which results in more compact code:

ArrayExample = _config.GetSection("array").Get<ArrayExample>();

L'oggetto associato, un'istanza di ArrayExample, riceve i dati di matrice dalla configurazione.The bound object, an instance of ArrayExample, receives the array data from configuration.

Indice di ArrayExample.EntriesArrayExample.Entries Index Valore di ArrayExample.EntriesArrayExample.Entries Value
00 value0value0
11 value1value1
22 value2value2
33 value4value4
44 value5value5

L'indice #3 nell'oggetto associato contiene i dati di configurazione per la chiave di configurazione array:4 e il relativo valore value4.Index #3 in the bound object holds the configuration data for the array:4 configuration key and its value of value4. Quando i dati di configurazione contenenti una matrice vengono associati, gli indici di matrice nelle chiavi di configurazione vengono usati semplicemente per scorrere i dati di configurazione quando si crea l'oggetto.When configuration data containing an array is bound, the array indices in the configuration keys are merely used to iterate the configuration data when creating the object. Un valore null non può essere mantenuto nei dati di configurazione e una voce con valore null non viene creata in un oggetto associato quando una matrice nelle chiavi di configurazione ignora uno o più indici.A null value can't be retained in configuration data, and a null-valued entry isn't created in a bound object when an array in configuration keys skip one or more indices.

L'elemento di configurazione mancante per l'indice #3 può essere fornito prima dell'associazione all'istanza ArrayExample da qualsiasi provider di configurazione che produce la coppia chiave-valore corretta nella configurazione.The missing configuration item for index #3 can be supplied before binding to the ArrayExample instance by any configuration provider that produces the correct key-value pair in configuration. Se il codice di esempio include un provider di configurazione JSON aggiuntivo con la coppia chiave-valore mancante, ArrayExample.Entries corrisponde alla matrice di configurazione completa:If the sample included an additional JSON Configuration Provider with the missing key-value pair, the ArrayExample.Entries matches the complete configuration array:

missing_value.json:missing_value.json:

{
  "array:entries:3": "value3"
}

In ConfigureAppConfiguration:In ConfigureAppConfiguration:

config.AddJsonFile("missing_value.json", optional: false, reloadOnChange: false);

La coppia chiave-valore mostrata nella tabella viene caricata nella configurazione.The key-value pair shown in the table is loaded into configuration.

ChiaveKey ValueValue
array:entries:3array:entries:3 value3value3

Se l'istanza della classe ArrayExample viene associata dopo che il provider di configurazione JSON include la voce per l'indice #3, la matrice ArrayExample.Entries include il valore.If the ArrayExample class instance is bound after the JSON Configuration Provider includes the entry for index #3, the ArrayExample.Entries array includes the value.

Indice di ArrayExample.EntriesArrayExample.Entries Index Valore di ArrayExample.EntriesArrayExample.Entries Value
00 value0value0
11 value1value1
22 value2value2
33 value3value3
44 value4value4
55 value5value5

Elaborazione di matrice JSONJSON array processing

Se un file JSON contiene una matrice, vengono create chiavi di configurazione per gli elementi della matrice con un indice di sezione in base zero.If a JSON file contains an array, configuration keys are created for the array elements with a zero-based section index. Nel file di configurazione seguente, subsection è una matrice:In the following configuration file, subsection is an array:

{
  "json_array": {
    "key": "valueA",
    "subsection": [
      "valueB",
      "valueC",
      "valueD"
    ]
  }
}

Il provider di configurazione JSON legge i dati di configurazione nelle coppie chiave-valore seguenti:The JSON Configuration Provider reads the configuration data into the following key-value pairs:

ChiaveKey ValueValue
json_array:keyjson_array:key valueAvalueA
json_array:subsection:0json_array:subsection:0 valueBvalueB
json_array:subsection:1json_array:subsection:1 valueCvalueC
json_array:subsection:2json_array:subsection:2 valueDvalueD

Nell'app di esempio, la classe POCO seguente è disponibile per associare le coppie chiave-valore della configurazione:In the sample app, the following POCO class is available to bind the configuration key-value pairs:

public class JsonArrayExample
{
    public string Key { get; set; }
    public string[] Subsection { get; set; }
}

Dopo l'associazione, JsonArrayExample.Key contiene il valore valueA.After binding, JsonArrayExample.Key holds the value valueA. I valori di sottosezione vengono archiviati nella proprietà matrice POCO Subsection.The subsection values are stored in the POCO array property, Subsection.

Indice di JsonArrayExample.SubsectionJsonArrayExample.Subsection Index Valore di JsonArrayExample.SubsectionJsonArrayExample.Subsection Value
00 valueBvalueB
11 valueCvalueC
22 valueDvalueD

Provider di configurazione personalizzatoCustom configuration provider

L'app di esempio dimostra come creare un provider di configurazione di base che legge le coppie chiave-valore di configurazione da un database usando Entity Framework (EF).The sample app demonstrates how to create a basic configuration provider that reads configuration key-value pairs from a database using Entity Framework (EF).

Il provider ha le caratteristiche seguenti:The provider has the following characteristics:

  • Il database in memoria di Entity Framework viene usato a scopo dimostrativo.The EF in-memory database is used for demonstration purposes. Per usare un database che richiede una stringa di connessione, implementare un ConfigurationBuilder secondario per fornire la stringa di connessione da un altro provider di configurazione.To use a database that requires a connection string, implement a secondary ConfigurationBuilder to supply the connection string from another configuration provider.
  • Il provider legge una tabella di database in una configurazione all'avvio.The provider reads a database table into configuration at startup. Il provider non esegue una query sul database per ogni chiave.The provider doesn't query the database on a per-key basis.
  • Il ricaricamento in caso di modifica non è implementato, quindi l'aggiornamento del database dopo l'avvio dell'app non ha alcun effetto sulla configurazione dell'app.Reload-on-change isn't implemented, so updating the database after the app starts has no effect on the app's configuration.

Definire un'entità EFConfigurationValue per l'archiviazione dei valori di configurazione nel database.Define an EFConfigurationValue entity for storing configuration values in the database.

Models/EFConfigurationValue.cs:Models/EFConfigurationValue.cs:

public class EFConfigurationValue
{
    public string Id { get; set; }
    public string Value { get; set; }
}

Aggiungere EFConfigurationContext per archiviare i valori configurati e accedervi.Add an EFConfigurationContext to store and access the configured values.

EFConfigurationProvider/EFConfigurationContext.cs:EFConfigurationProvider/EFConfigurationContext.cs:

public class EFConfigurationContext : DbContext
{
    public EFConfigurationContext(DbContextOptions options) : base(options)
    {
    }

    public DbSet<EFConfigurationValue> Values { get; set; }
}

Creare una classe che implementi IConfigurationSource.Create a class that implements IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs:EFConfigurationProvider/EFConfigurationSource.cs:

public class EFConfigurationSource : IConfigurationSource
{
    private readonly Action<DbContextOptionsBuilder> _optionsAction;

    public EFConfigurationSource(Action<DbContextOptionsBuilder> optionsAction)
    {
        _optionsAction = optionsAction;
    }

    public IConfigurationProvider Build(IConfigurationBuilder builder)
    {
        return new EFConfigurationProvider(_optionsAction);
    }
}

Creare il provider di configurazione personalizzato ereditando da ConfigurationProvider.Create the custom configuration provider by inheriting from ConfigurationProvider. Il provider di configurazione inizializza il database quando è vuoto.The configuration provider initializes the database when it's empty.

EFConfigurationProvider/EFConfigurationProvider.cs:EFConfigurationProvider/EFConfigurationProvider.cs:

public class EFConfigurationProvider : ConfigurationProvider
{
    public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
    {
        OptionsAction = optionsAction;
    }

    Action<DbContextOptionsBuilder> OptionsAction { get; }

    // Load config data from EF DB.
    public override void Load()
    {
        var builder = new DbContextOptionsBuilder<EFConfigurationContext>();

        OptionsAction(builder);

        using (var dbContext = new EFConfigurationContext(builder.Options))
        {
            dbContext.Database.EnsureCreated();

            Data = !dbContext.Values.Any()
                ? CreateAndSaveDefaultValues(dbContext)
                : dbContext.Values.ToDictionary(c => c.Id, c => c.Value);
        }
    }

    private static IDictionary<string, string> CreateAndSaveDefaultValues(
        EFConfigurationContext dbContext)
    {
        // Quotes (c)2005 Universal Pictures: Serenity
        // https://www.uphe.com/movies/serenity
        var configValues = new Dictionary<string, string>
            {
                { "quote1", "I aim to misbehave." },
                { "quote2", "I swallowed a bug." },
                { "quote3", "You can't stop the signal, Mal." }
            };

        dbContext.Values.AddRange(configValues
            .Select(kvp => new EFConfigurationValue 
                {
                    Id = kvp.Key,
                    Value = kvp.Value
                })
            .ToArray());

        dbContext.SaveChanges();

        return configValues;
    }
}

Un metodo di estensione AddEFConfiguration consente di aggiungere l'origine di configurazione a un ConfigurationBuilder.An AddEFConfiguration extension method permits adding the configuration source to a ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs:Extensions/EntityFrameworkExtensions.cs:

public static class EntityFrameworkExtensions
{
    public static IConfigurationBuilder AddEFConfiguration(
        this IConfigurationBuilder builder, 
        Action<DbContextOptionsBuilder> optionsAction)
    {
        return builder.Add(new EFConfigurationSource(optionsAction));
    }
}

L'esempio di codice seguente mostra come usare il EFConfigurationProvider personalizzato in Program.cs:The following code shows how to use the custom EFConfigurationProvider in Program.cs:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

Accedere alla configurazione durante l'avvioAccess configuration during startup

Inserire IConfiguration nel costruttore Startup per accedere ai valori di configurazione in Startup.ConfigureServices.Inject IConfiguration into the Startup constructor to access configuration values in Startup.ConfigureServices. Per accedere alla configurazione in Startup.Configure, inserire IConfiguration direttamente nel metodo o usare l'istanza dal costruttore:To access configuration in Startup.Configure, either inject IConfiguration directly into the method or use the instance from the constructor:

public class Startup
{
    private readonly IConfiguration _config;

    public Startup(IConfiguration config)
    {
        _config = config;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        var value = _config["key"];
    }

    public void Configure(IApplicationBuilder app, IConfiguration config)
    {
        var value = config["key"];
    }
}

Per un esempio di accesso alla configurazione usando metodi di servizio di avvio, vedere Avvio dell'applicazione: Metodi pratici.For an example of accessing configuration using startup convenience methods, see App startup: Convenience methods.

Accedere alla configurazione in una pagina Razor Pages o in una visualizzazione MVCAccess configuration in a Razor Pages page or MVC view

Per accedere alle impostazioni di configurazione in una pagina Razor Pages o in una visualizzazione MVC, aggiungere un direttiva using (Informazioni di riferimento su C#: direttiva using) per lo spazio dei nomi Microsoft.Extensions.Configuration e inserire IConfiguration nella pagina o nella visualizzazione.To access configuration settings in a Razor Pages page or an MVC view, add a using directive (C# reference: using directive) for the Microsoft.Extensions.Configuration namespace and inject IConfiguration into the page or view.

In una pagina Razor Pages:In a Razor Pages page:

@page
@model IndexModel
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Index Page</title>
</head>
<body>
    <h1>Access configuration in a Razor Pages page</h1>
    <p>Configuration value for 'key': @Configuration["key"]</p>
</body>
</html>

In una visualizzazione MVC:In an MVC view:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Index View</title>
</head>
<body>
    <h1>Access configuration in an MVC view</h1>
    <p>Configuration value for 'key': @Configuration["key"]</p>
</body>
</html>

Aggiungere la configurazione da un assembly esternoAdd configuration from an external assembly

Un'implementazione IHostingStartup consente l'aggiunta di miglioramenti a un'app all'avvio, da un assembly esterno alla classe Startup dell'app.An IHostingStartup implementation allows adding enhancements to an app at startup from an external assembly outside of the app's Startup class. Per ulteriori informazioni, vedere Usare assembly di avvio dell'hosting in ASP.NET Core.For more information, see Usare assembly di avvio dell'hosting in ASP.NET Core.

Risorse aggiuntiveAdditional resources