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
  • Configurazione di app AzureAzure App Configuration
  • 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 (Microsoft.Extensions.Configuration) sono inclusi in modo implicito dal framework.Configuration packages for common configuration provider scenarios (Microsoft.Extensions.Configuration) are included implicitly by the framework.

I pacchetti di configurazione per gli scenari di provider di configurazione comuni (Microsoft.Extensions.Configuration) sono inclusi nel metapacchetto Microsoft.AspNetCore.App.Configuration packages for common configuration provider scenarios (Microsoft.Extensions.Configuration) 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 use classes to represent groups of related settings. Per ulteriori informazioni, vedere Modello di opzioni in ASP.NET Core.For more information, 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 versus 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. Anche le coppie chiave-valore di configurazione dell'host sono incluse nella configurazione dell'app.Host configuration key-value pairs are also included in the app's configuration. Per altre informazioni su come vengono usati i provider di configurazione quando viene creato l'host e sugli effetti delle origini di configurazione sull'host di configurazione, vedere Nozioni fondamentali su ASP.NET Core.For more information on how the configuration providers are used when the host is built and how configuration sources affect host configuration, see Nozioni fondamentali su ASP.NET Core.

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:

La configurazione seguente si applica alle app che usano l'host generico.The following applies to apps using the Generic Host. Per informazioni dettagliate sulla configurazione predefinita quando viene usato l'host Web, vedere la versione di questo argomento per ASP.NET Core 2.2.For details on the default configuration when using the Web Host, see the ASP.NET Core 2.2 version of this topic.

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:

La configurazione seguente si applica alle app che usano l'host Web.The following applies to apps using the Web Host. Per informazioni dettagliate sulla configurazione predefinita quando viene usato l'host generico, vedere la versione più recente di questo argomento.For details on the default configuration when using the Generic Host, see the latest version of this topic.

SicurezzaSecurity

Per proteggere i dati di configurazione sensibili, adottare le pratiche seguenti:Adopt the following practices to secure sensitive configuration data:

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

Per altre informazioni, vedere i seguenti argomenti:For more information, see the following topics:

Azure Key Vault archivia in modo sicuro i segreti delle app ASP.NET Core.Azure Key Vault safely stores app secrets for ASP.NET Core apps. Per ulteriori informazioni, vedere Provider di configurazione di Azure Key Vault in ASP.NET Core.For more information, see Provider di configurazione di Azure Key Vault 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.

ConvenzioniConventions

Origini e providerSources and providers

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.

TastiKeys

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 automaticamente nei due punti.A double underscore (__) is supported by all platforms and is automatically converted into 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.

ValoriValues

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 app (Documentazione di Azure)Azure App Configuration Provider (Azure documentation) Configurazione di app AzureAzure App Configuration
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) (solo nell'ambiente di sviluppo)User secrets (Secret Manager) (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.A common practice is 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.

La sequenza di provider precedente viene usata quando si inizializza un nuovo generatore di host con CreateDefaultBuilder.The preceding sequence of providers is used when you initialize a new host builder with CreateDefaultBuilder. Per altre informazioni, vedere la sezione Configurazione predefinita.For more information, see the Default configuration section.

Configurare il generatore di host con ConfigureHostConfigurationConfigure the host builder with ConfigureHostConfiguration

Per configurare il generatore di host, chiamare ConfigureHostConfiguration e specificare la configurazione.To configure the host builder, call ConfigureHostConfiguration and supply the configuration. ConfigureHostConfiguration viene usato per inizializzare l'oggetto IHostEnvironment da usare in un secondo momento nel processo di compilazione.ConfigureHostConfiguration is used to initialize the IHostEnvironment for use later in the build process. ConfigureHostConfiguration può essere chiamato più volte e i risultati si sommano.ConfigureHostConfiguration can be called multiple times with additive results.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureHostConfiguration(config =>
        {
            var dict = new Dictionary<string, string>
            {
                {"MemoryCollectionKey1", "value1"},
                {"MemoryCollectionKey2", "value2"}
            };

            config.AddInMemoryCollection(dict);
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Configurare il generatore di host con UseConfigurationConfigure the host builder with UseConfiguration

Per configurare il generatore di host, chiamare UseConfiguration sul generatore di host con la configurazione.To configure the host builder, call UseConfiguration on the host builder with the configuration.

public static IWebHostBuilder CreateWebHostBuilder(string[] args)
{
    var dict = new Dictionary<string, string>
    {
        {"MemoryCollectionKey1", "value1"},
        {"MemoryCollectionKey2", "value2"}
    };

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

    return WebHost.CreateDefaultBuilder(args)
        .UseConfiguration(config)
        .UseStartup<Startup>();
}

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)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                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);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}
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.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>();
}

Sostituire la configurazione precedente con argomenti della riga di comandoOverride previous configuration with command-line arguments

Per fornire la configurazione dell'app che può essere sostituita con argomenti della riga di comando, chiamare AddCommandLine per ultimo:To provide app configuration that can be overridden with command-line arguments, call AddCommandLine last:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    // Call other providers here
    config.AddCommandLine(args);
})

Rimuovere i provider aggiunti da CreateDefaultBuilderRemove providers added by CreateDefaultBuilder

Per rimuovere i provider aggiunti da CreateDefaultBuilder, chiamare prima Clear in IConfigurationBuilder. Sources :To remove the providers added by CreateDefaultBuilder, call Clear on the IConfigurationBuilder.Sources first:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();
    // Add providers here
})

Utilizzare la configurazione durante l'avvio dell'appConsume configuration during app 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 viene chiamato il metodo CreateDefaultBuilder(string []).AddCommandLine is automatically called when CreateDefaultBuilder(string []) is called. Per altre informazioni, vedere la sezione Configurazione predefinita.For more information, see the Default configuration section.

CreateDefaultBuilder carica anche:CreateDefaultBuilder also loads:

  • Una configurazione facoltativa dai file appsettings.json e appsettings.{Environment}.json.Optional configuration from appsettings.json and appsettings.{Environment}.json files.
  • Segreti utente (Secret Manager) nell'ambiente di sviluppo.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.

Per le app basate sui modelli di ASP.NET Core, AddCommandLine è già stato chiamato da CreateDefaultBuilder.For apps based on the ASP.NET Core templates, AddCommandLine has already been called by CreateDefaultBuilder. Per aggiungere altri provider di configurazione e mantenere la possibilità di sostituire la configurazione di tali provider con argomenti della riga di comando, chiamare i provider aggiuntivi dell'app in ConfigureAppConfiguration e quindi chiamare AddCommandLine per ultimo.To add additional configuration providers and maintain the ability to override configuration from those providers with command-line arguments, call the app's additional providers in ConfigureAppConfiguration and call AddCommandLine last.

.ConfigureAppConfiguration((hostingContext, config) =>
{
    // Call other providers here
    config.AddCommandLine(args);
})

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 non è necessario se viene usato un segno di uguale, ad esempio CommandLineKey=.The value isn't required 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.

Creare un dizionario dei mapping di sostituzione.Create a switch mappings dictionary. Nell'esempio seguente vengono creati due mapping di sostituzione:In the following example, two switch mappings are created:

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

Quando viene creato l'host, chiamare AddCommandLine con il dizionario dei mapping di sostituzione:When the host is built, call AddCommandLine with the switch mappings dictionary:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddCommandLine(args, _switchMappings);
})

Per le app che usano i mapping di sostituzione, la chiamata a CreateDefaultBuilder non deve passare argomenti.For apps that use switch mappings, the call to CreateDefaultBuilder shouldn't pass arguments. La chiamata AddCommandLine del metodo CreateDefaultBuilder non include sostituzioni mappate e non è possibile passare il dizionario dei mapping di sostituzione a CreateDefaultBuilder.The CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and there's no way to pass the switch mapping dictionary to CreateDefaultBuilder. 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 automaticamente con i due punti.A double underscore (__) is supported by all platforms and is automatically 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 di 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 DOTNET_ per la configurazione host quando viene inizializzato un nuovo generatore di host con l'host generico e viene chiamato CreateDefaultBuilder.AddEnvironmentVariables is used to load environment variables prefixed with DOTNET_ for host configuration when a new host builder is initialized with the Generic Host and CreateDefaultBuilder is called. Per altre informazioni, vedere la sezione Configurazione predefinita.For more information, see the Default configuration section.

AddEnvironmentVariables consente di caricare variabili di ambiente con prefisso ASPNETCORE_ per la configurazione host quando viene inizializzato un nuovo generatore di host con l'host Web e viene chiamato CreateDefaultBuilder.AddEnvironmentVariables is used to load environment variables prefixed with ASPNETCORE_ for host configuration when a new host builder is initialized with the Web Host and CreateDefaultBuilder is called. Per altre informazioni, vedere la sezione Configurazione predefinita.For more information, see the Default configuration section.

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 dai file appsettings.json e appsettings.{Environment}.json.Optional configuration from appsettings.json and appsettings.{Environment}.json files.
  • Segreti utente (Secret Manager) nell'ambiente di sviluppo.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.

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.

.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_");
})
}

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 limitare l'elenco delle variabili di ambiente restituito dall'app, l'app filtra le variabili di ambiente.To keep the list of environment variables rendered by the app short, the app filters environment variables. Vedere il file Pages/Index.cshtml.cs dell'app di esempio.See the sample app's Pages/Index.cshtml.cs file.

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.

Quando viene creato il generatore di host, la configurazione dell'host viene fornita dalle variabili di ambiente.When the host builder is created, host configuration is provided by environment variables. Per altre informazioni sul prefisso usato per queste variabili di ambiente, vedere la sezione Configurazione predefinita.For more information on the prefix used for these environment variables, see the Default configuration section.

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:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddIniFile(
        "config.ini", optional: true, reloadOnChange: true);
})

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 generatore di host con CreateDefaultBuilder.AddJsonFile is automatically called twice when you initialize a new host builder 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 la sezione Configurazione predefinita.For more information, see the Default configuration section.

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:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddJsonFile(
        "config.json", optional: true, reloadOnChange: true);
})

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:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddXmlFile(
        "config.xml", optional: true, reloadOnChange: true);
})

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:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");
    config.AddKeyPerFile(directoryPath: path, optional: true);
})

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.

Nell'esempio seguente viene creato un dizionario di configurazione:In the following example, a configuration dictionary is created:

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

Il dizionario viene usato con una chiamata a AddInMemoryCollection per fornire la configurazione:The dictionary is used with a call to AddInMemoryCollection to provide the configuration:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddInMemoryCollection(_dict);
})

GetValueGetValue

ConfigurationBinder. GetValue <T > estrae un singolo valore dalla configurazione con una chiave specificata e lo converte nel tipo non di raccolta specificato.ConfigurationBinder.GetValue<T> extracts a single value from configuration with a specified key and converts it to the specified noncollection type. Un overload accetta un valore predefinito.An overload accepts a default value.

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.

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.

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; }
}
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"
}
{
  "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. https://www.paramount.comParamount Pictures Corp. https://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;
var starship = new Starship();
_config.GetSection("starship").Bind(starship);
Starship = starship;

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.

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; }
}
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>
<?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>();
TvShow = _config.GetSection("tvshow").Get<TvShow>();

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.

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)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                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);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}
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.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; }
}
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);

È 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>();
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
3.3 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
3.3 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"
    ]
  }
}
{
  "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; }
}
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. Poiché le chiavi di configurazione non fanno distinzione tra maiuscolee minuscole, il dizionario utilizzato per inizializzare il database viene creato con l'operatore di confronto senza distinzione tra maiuscole e minuscole (StringComparer. OrdinalIgnoreCase).Since configuration keys are case-insensitive, the dictionary used to initialize the database is created with the case-insensitive comparer (StringComparer.OrdinalIgnoreCase).

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>(StringComparer.OrdinalIgnoreCase)
            {
                { "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)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                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);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

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>(StringComparer.OrdinalIgnoreCase)
            {
                { "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.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