Configurazione in ASP.NET CoreConfiguration in ASP.NET Core

Di Rick Anderson e Kirk LarkinBy Rick Anderson and Kirk Larkin

La configurazione in ASP.NET Core viene eseguita utilizzando uno o più provider di configurazione.Configuration in ASP.NET Core is performed using one or more configuration providers. I provider di configurazione leggono i dati di configurazione da coppie chiave-valore usando un'ampia gamma di origini di configurazione:Configuration providers read configuration data from key-value pairs using a variety of configuration sources:

  • File di impostazioni, ad esempio appSettings. JSONSettings files, such as appsettings.json
  • Variabili di ambienteEnvironment variables
  • Insieme di credenziali chiave di AzureAzure Key Vault
  • Configurazione app di AzureAzure App Configuration
  • Argomenti della riga di comandoCommand-line arguments
  • Provider personalizzati, installati o creatiCustom providers, installed or created
  • File della directoryDirectory files
  • Oggetti .NET in memoriaIn-memory .NET objects

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

Configurazione predefinitaDefault configuration

ASP.NET Core app Web create con DotNet New o Visual Studio generano il codice seguente:ASP.NET Core web apps created with dotnet new or Visual Studio generate the following code:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

CreateDefaultBuilder fornisce la configurazione predefinita per l'app nell'ordine seguente:CreateDefaultBuilder provides default configuration for the app in the following order:

  1. ChainedConfigurationProvider : aggiunge un oggetto IConfiguration esistente come origine.ChainedConfigurationProvider : Adds an existing IConfiguration as a source. Nel caso di configurazione predefinita, aggiunge la configurazione host e la imposta come prima origine per la configurazione dell' app .In the default configuration case, adds the host configuration and setting it as the first source for the app configuration.
  2. appSettings. JSON con il provider di configurazione JSON.appsettings.json using the JSON configuration provider.
  3. appSettings. Environment . JSON con il provider di configurazione JSON.appsettings.Environment.json using the JSON configuration provider. Ad esempio, appSettings. Produzione. JSON e appSettings. Sviluppo. JSON.For example, appsettings.Production.json and appsettings.Development.json.
  4. Segreti dell'app quando l'app viene eseguita Development nell'ambiente.App secrets when the app runs in the Development environment.
  5. Variabili di ambiente che usano il provider di configurazione delle variabili di ambiente.Environment variables using the Environment Variables configuration provider.
  6. Argomenti della riga di comando che usano il provider di configurazione della riga di comando.Command-line arguments using the Command-line configuration provider.

I provider di configurazione aggiunti successivamente sostituiscono le impostazioni di chiave precedenti.Configuration providers that are added later override previous key settings. Se MyKey , ad esempio, è impostato sia in appSettings. JSON che nell'ambiente, viene utilizzato il valore dell'ambiente.For example, if MyKey is set in both appsettings.json and the environment, the environment value is used. Utilizzando i provider di configurazione predefiniti, il provider di configurazione della riga di comando esegue l'override di tutti gli altri provider.Using the default configuration providers, the Command-line configuration provider overrides all other providers.

Per ulteriori informazioni su CreateDefaultBuilder, vedere impostazioni predefinite del generatore.For more information on CreateDefaultBuilder, see Default builder settings.

Il codice seguente Visualizza i provider di configurazione abilitati nell'ordine in cui sono stati aggiunti:The following code displays the enabled configuration providers in the order they were added:

public class Index2Model : PageModel
{
    private IConfigurationRoot ConfigRoot;

    public Index2Model(IConfiguration configRoot)
    {
        ConfigRoot = (IConfigurationRoot)configRoot;
    }

    public ContentResult OnGet()
    {           
        string str = "";
        foreach (var provider in ConfigRoot.Providers.ToList())
        {
            str += provider.ToString() + "\n";
        }

        return Content(str);
    }
}

appsettings.jsonappsettings.json

Si consideri il file appSettings. JSON seguente:Consider the following appsettings.json file:

{
    "Position": {
        "Title": "Editor",
        "Name": "Joe Smith"
    },
    "MyKey": "My appsettings.json Value",
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    },
    "AllowedHosts": "*"
}

Il codice seguente del download dell'esempio Visualizza diverse impostazioni di configurazione precedenti:The following code from the sample download displays several of the preceding configurations settings:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Il valore JsonConfigurationProvider predefinito carica la configurazione nell'ordine seguente:The default JsonConfigurationProvider loads configuration in the following order:

  1. appsettings.jsonappsettings.json
  2. appSettings. Environment . JSON : ad esempio, appSettings. Produzione. JSON e appSettings. Sviluppo. file JSON .appsettings.Environment.json : For example, the appsettings.Production.json and appsettings.Development.json files. La versione dell'ambiente del file viene caricata in base a IHostingEnvironment. EnvironmentName.The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName. Per altre informazioni, vedere Usare più ambienti in ASP.NET Core.For more information, see Usare più ambienti in ASP.NET Core.

appSettings. Environment. i valori JSON eseguono l'override delle chiavi in appSettings. JSON.appsettings.Environment.json values override keys in appsettings.json. Ad esempio, per impostazione predefinita:For example, by default:

  • In fase di sviluppo, appSettings. Sviluppo. la configurazione JSON sovrascrive i valori trovati in appSettings. JSON.In development, appsettings.Development.json configuration overwrites values found in appsettings.json.
  • In produzione, appSettings. Produzione. la configurazione JSON sovrascrive i valori trovati in appSettings. JSON.In production, appsettings.Production.json configuration overwrites values found in appsettings.json. Ad esempio, quando si distribuisce l'app in Azure.For example, when deploying the app to Azure.

Associare i dati di configurazione gerarchici usando il modello di opzioniBind hierarchical configuration data using the options pattern

Il modo migliore per leggere i valori di configurazione correlati consiste nell'usare il modello di opzioni.The preferred way to read related configuration values is using the options pattern. Ad esempio, per leggere i valori di configurazione seguenti:For example, to read the following configuration values:

  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  }

Creare la classe PositionOptions seguente:Create the following PositionOptions class:

public class PositionOptions
{
    public string Title { get; set; }
    public string Name { get; set; }
}

Tutte le proprietà di lettura/scrittura pubbliche del tipo sono associate.All the public read-write properties of the type are bound. I campi non sono associati.Fields are not bound.

Il codice seguente:The following code:

  • Chiama ConfigurationBinder. Bind per associare la PositionOptions classe alla Position sezione.Calls ConfigurationBinder.Bind to bind the PositionOptions class to the Position section.
  • Consente di Position visualizzare i dati di configurazione.Displays the Position configuration data.
public class Test22Model : PageModel
{
    private readonly IConfiguration Configuration;

    public Test22Model(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var positionOptions = new PositionOptions();
        Configuration.GetSection("Position").Bind(positionOptions);

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

ConfigurationBinder.Get<T>associa e restituisce il tipo specificato.ConfigurationBinder.Get<T> binds and returns the specified type. ConfigurationBinder.Get<T>può essere più pratico rispetto all' ConfigurationBinder.Binduso di.ConfigurationBinder.Get<T> may be more convenient than using ConfigurationBinder.Bind. Il codice seguente illustra come usare ConfigurationBinder.Get<T> con la PositionOptions classe:The following code shows how to use ConfigurationBinder.Get<T> with the PositionOptions class:

public class Test21Model : PageModel
{
    private readonly IConfiguration Configuration;
    public PositionOptions positionOptions { get; private set; }

    public Test21Model(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        positionOptions = Configuration.GetSection("Position").Get<PositionOptions>();

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

Un approccio alternativo quando si usa il modello di opzioni è associare Position la sezione e aggiungerla al contenitore del servizio di inserimento delle dipendenze.An alternative approach when using the options pattern is to bind the Position section and add it to the dependency injection service container. Nel codice seguente, PositionOptions viene aggiunto al contenitore del servizio con Configure e associato alla configurazione:In the following code, PositionOptions is added to the service container with Configure and bound to configuration:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<PositionOptions>(Configuration.GetSection("Position"));
    services.AddRazorPages();
}

Utilizzando il codice precedente, il codice seguente legge le opzioni di posizione:Using the preceding code, the following code reads the position options:

public class Test2Model : PageModel
{
    private readonly PositionOptions _options;

    public Test2Model(IOptions<PositionOptions> options)
    {
        _options = options.Value;
    }

    public ContentResult OnGet()
    {
        return Content($"Title: {_options.Title} \n" +
                       $"Name: {_options.Name}");
    }
}

Utilizzando la configurazione predefinita , appSettings. JSON e appSettings. Environmenti file con estensione JSON sono abilitati con reloadOnChange: true.Using the default configuration, the appsettings.json and appsettings.Environment.json files are enabled with reloadOnChange: true. Modifiche apportate a appSettings. JSON e appSettings. Environmentil file con estensione JSON dopo l'avvio dell'app viene letto dal provider di configurazione JSON.Changes made to the appsettings.json and appsettings.Environment.json file after the app starts are read by the JSON configuration provider.

Per informazioni sull'aggiunta di altri file di configurazione JSON, vedere provider di configurazione JSON in questo documento.See JSON configuration provider in this document for information on adding additional JSON configuration files.

Gestione della sicurezza e del segretoSecurity and secret manager

Linee guida sui dati di configurazione:Configuration data guidelines:

  • 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. Il gestore del segreto può essere usato per archiviare i segreti in fase di sviluppo.The Secret manager can be used to store secrets in development.
  • 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 impostazione predefinita, Secret Manager legge le impostazioni di configurazione dopo appSettings. JSON e appSettings. Environment . JSON.By default, Secret manager reads configuration settings after appsettings.json and appsettings.Environment.json.

Per ulteriori informazioni sull'archiviazione di password o altri dati sensibili:For more information on storing passwords or other sensitive data:

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

Variabili di ambienteEnvironment variables

Usando la configurazione predefinita , carica EnvironmentVariablesConfigurationProvider la configurazione dalle coppie chiave-valore della variabile di ambiente dopo aver letto appSettings. JSON, appSettings. Environment . JSONe gestione segreta.Using the default configuration, the EnvironmentVariablesConfigurationProvider loads configuration from environment variable key-value pairs after reading appsettings.json, appsettings.Environment.json, and Secret manager. Pertanto, i valori di chiave letti dall'ambiente eseguono l'override dei valori letti da appSettings. JSON, appSettings. Environment . JSONe gestione segreta.Therefore, key values read from the environment override values read from appsettings.json, appsettings.Environment.json, and Secret manager.

Il : separatore non funziona con le chiavi gerarchiche delle variabili di ambiente in tutte le piattaforme.The : separator doesn't work with environment variable hierarchical keys on all platforms. __, il doppio carattere di sottolineatura, è:__, the double underscore, is:

  • Supportato da tutte le piattaforme.Supported by all platforms. Il : separatore, ad esempio, non è Bashsupportato da bash __ , ma è.For example, the : separator is not supported by Bash, but __ is.
  • Sostituito automaticamente da:Automatically replaced by a :

I comandi set seguenti:The following set commands:

  • Impostare le chiavi e i valori di ambiente dell' esempio precedente in Windows.Set the environment keys and values of the preceding example on Windows.
  • Testare le impostazioni quando si usa il download di esempio.Test the settings when using the sample download. Il dotnet run comando deve essere eseguito nella directory del progetto.The dotnet run command must be run in the project directory.
set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run

Le impostazioni di ambiente precedenti:The preceding environment settings:

  • Vengono impostati solo nei processi avviati dalla finestra di comando in cui sono stati impostati.Are only set in processes launched from the command window they were set in.
  • Non verrà letto dai browser avviati con Visual Studio.Won't be read by browsers launched with Visual Studio.

Per impostare le chiavi e i valori di ambiente in Windows, è possibile usare i comandi Setx seguenti.The following setx commands can be used to set the environment keys and values on Windows. Diversamente da set, setx le impostazioni sono rese permanente.Unlike set, setx settings are persisted. /Mimposta la variabile nell'ambiente di sistema./M sets the variable in the system environment. Se l' /M opzione non viene usata, viene impostata una variabile di ambiente utente.If the /M switch isn't used, a user environment variable is set.

setx MyKey "My key from setx Environment" /M
setx Position__Title Setx_Environment_Editor /M
setx Position__Name Environment_Rick /M

Per verificare che i comandi precedenti eseguano l'override di appSettings. JSON e appSettings. Environment . JSON:To test that the preceding commands override appsettings.json and appsettings.Environment.json:

  • Con Visual Studio: chiudere e riavviare Visual Studio.With Visual Studio: Exit and restart Visual Studio.
  • Con l'interfaccia della riga di comando: avviare una nuova dotnet runfinestra di comando e immettere.With the CLI: Start a new command window and enter dotnet run.

Chiamare AddEnvironmentVariables con una stringa per specificare un prefisso per le variabili di ambiente:Call AddEnvironmentVariables with a string to specify a prefix for environment variables:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddEnvironmentVariables(prefix: "MyCustomPrefix_");
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Nel codice precedente:In the preceding code:

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

I comandi seguenti verificano il prefisso personalizzato:The following commands test the custom prefix:

set MyCustomPrefix_MyKey="My key with MyCustomPrefix_ Environment"
set MyCustomPrefix_Position__Title=Editor_with_customPrefix
set MyCustomPrefix_Position__Name=Environment_Rick_cp
dotnet run

La configurazione predefinita carica le variabili di ambiente e gli argomenti della riga DOTNET_ di ASPNETCORE_comando preceduti da e.The default configuration loads environment variables and command line arguments prefixed with DOTNET_ and ASPNETCORE_. I DOTNET_ prefissi e ASPNETCORE_ vengono usati da ASP.NET Core per la configurazione dell'host e dell'app, ma non per la configurazione dell'utente.The DOTNET_ and ASPNETCORE_ prefixes are used by ASP.NET Core for host and app configuration, but not for user configuration. Per ulteriori informazioni sulla configurazione dell'host e dell'app, vedere .NET Generic Host.For more information on host and app configuration, see .NET Generic Host.

In app Azure servizioselezionare impostazione nuova applicazione nella pagina Impostazioni > configurazione .On Azure App Service, select New application setting on the Settings > Configuration page. App Azure impostazioni dell'applicazione del servizio sono:Azure App Service application settings are:

  • Crittografati a riposo e trasmessi su un canale crittografato.Encrypted at rest and transmitted over an encrypted channel.
  • Esposto come variabile di ambiente.Exposed as environment variables.

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.

Per informazioni sulle stringhe di connessione del database di Azure, vedere prefissi della stringa di connessione .See Connection string prefixes for information on Azure database connection strings.

Riga di comandoCommand-line

Utilizzando la configurazione predefinita , carica CommandLineConfigurationProvider la configurazione dalle coppie chiave-valore dell'argomento della riga di comando dopo le origini di configurazione seguenti:Using the default configuration, the CommandLineConfigurationProvider loads configuration from command-line argument key-value pairs after the following configuration sources:

Per impostazione predefinita, i valori di configurazione impostati nei valori di configurazione di override della riga di comando impostati con tutti gli altri provider di configurazione.By default, configuration values set on the command-line override configuration values set with all the other configuration providers.

Argomenti della riga di comandoCommand-line arguments

Il comando seguente imposta le chiavi e i =valori usando:The following command sets keys and values using =:

dotnet run MyKey="My key from command line" Position:Title=Cmd Position:Name=Cmd_Rick

Il comando seguente imposta le chiavi e i /valori usando:The following command sets keys and values using /:

dotnet run /MyKey "Using /" /Position:Title=Cmd_ /Position:Name=Cmd_Rick

Il comando seguente imposta le chiavi e i --valori usando:The following command sets keys and values using --:

dotnet run --MyKey "Using --" --Position:Title=Cmd-- --Position:Name=Cmd--Rick

Valore chiave:The key value:

  • Deve seguire =oppure la chiave deve avere un prefisso -- o / quando il valore segue uno spazio.Must follow =, or the key must have a prefix of -- or / when the value follows a space.
  • Non è obbligatorio = se si usa.Isn't required if = is used. Ad esempio: MySetting=.For example, MySetting=.

All'interno dello stesso comando, non combinare coppie chiave-valore dell'argomento della riga di = comando che usano con coppie chiave-valore che usano uno spazio.Within the same command, don't mix command-line argument key-value pairs that use = with key-value pairs that use a space.

Mapping di sostituzioneSwitch mappings

I mapping switch consentono la logica di sostituzione del nome chiave .Switch mappings allow key name replacement logic. Fornire un dizionario di sostituzioni switch al AddCommandLine metodo.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 viene passato di nuovo per impostare la coppia chiave-valore nella configurazione dell'app.If the command-line key is found in the dictionary, the dictionary value 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 opzioni devono iniziare - con --o.Switches must start with - or --.
  • Il dizionario dei mapping di sostituzione non deve contenere chiavi duplicate.The switch mappings dictionary must not contain duplicate keys.

Per usare un dizionario dei mapping switch, passarlo alla chiamata a AddCommandLine:To use a switch mappings dictionary, pass it into the call to AddCommandLine:

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

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var switchMappings = new Dictionary<string, string>()
         {
             { "-k1", "key1" },
             { "-k2", "key2" },
             { "--alt3", "key3" },
             { "--alt4", "key4" },
             { "--alt5", "key5" },
             { "--alt6", "key6" },
         };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddCommandLine(args, switchMappings);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Il codice seguente mostra i valori chiave per le chiavi sostituite:The following code shows the key values for the replaced keys:

public class Test3Model : PageModel
{
    private readonly IConfiguration Config;

    public Test3Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        return Content(
                $"Key1: '{Config["Key1"]}'\n" +
                $"Key2: '{Config["Key2"]}'\n" +
                $"Key3: '{Config["Key3"]}'\n" +
                $"Key4: '{Config["Key4"]}'\n" +
                $"Key5: '{Config["Key5"]}'\n" +
                $"Key6: '{Config["Key6"]}'");
    }
}

Eseguire il comando seguente per testare la sostituzione della chiave:Run the following command to test the key replacement:

dotnet run -k1=value1 -k2 value2 --alt3=value2 /alt4=value3 --alt5 value5 /alt6 value6

Nota: attualmente = non è possibile usare per impostare i valori di sostituzione delle chiavi con un -trattino singolo.Note: Currently, = cannot be used to set key-replacement values with a single dash -. Vedere il problema in GitHub.See this GitHub issue.

Il comando seguente funziona per testare la sostituzione della chiave:The following command works to test key replacement:

dotnet run -k1 value1 -k2 value2 --alt3=value2 /alt4=value3 --alt5 value5 /alt6 value6

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 CreateDefaultBuilder AddCommandLine chiamata al metodo non include opzioni mappate e non è possibile passare il dizionario di mapping switch 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 non passa gli argomenti a CreateDefaultBuilder ma per consentire al ConfigurationBuilder AddCommandLine metodo del metodo di elaborare sia gli argomenti sia il dizionario di mapping delle opzioni.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.

Dati di configurazione gerarchiciHierarchical configuration data

L'API di configurazione legge i dati di configurazione gerarchici rendendo flat i dati gerarchici con l'uso di un delimitatore nelle chiavi di configurazione.The Configuration API reads hierarchical configuration data by flattening the hierarchical data with the use of a delimiter in the configuration keys.

Il download di esempio contiene il file appSettings. JSON seguente:The sample download contains the following appsettings.json file:

{
    "Position": {
        "Title": "Editor",
        "Name": "Joe Smith"
    },
    "MyKey": "My appsettings.json Value",
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    },
    "AllowedHosts": "*"
}

Il codice seguente del download dell'esempio Visualizza diverse impostazioni di configurazione:The following code from the sample download displays several of the configurations settings:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Il modo migliore per leggere i dati di configurazione gerarchici consiste nell'usare il modello di opzioni.The preferred way to read hierarchical configuration data is using the options pattern. Per altre informazioni, vedere associare dati di configurazione gerarchici in questo documento.For more information, see Bind hierarchical configuration data in this document.

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.

Chiavi e valori di configurazioneConfiguration keys and values

Chiavi di configurazione:Configuration keys:

  • Non fanno distinzione tra maiuscole e minuscole.Are case-insensitive. Ad esempio, ConnectionString e connectionstring vengono considerate chiavi equivalenti.For example, ConnectionString and connectionstring are treated as equivalent keys.
  • Se una chiave e un valore vengono impostati in più provider di configurazione, viene utilizzato il valore dell'ultimo provider aggiunto.If a key and value is set in more than one configuration providers, the value from the last provider added is used. Per ulteriori informazioni, vedere configurazione predefinita.For more information, see Default configuration.
  • 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. Un doppio carattere di sottolineatura, __, è supportato da tutte le piattaforme e viene convertito :automaticamente in due punti.A double underscore, __, is supported by all platforms and is automatically converted into a colon :.
    • In Azure Key Vault, le chiavi gerarchiche -- utilizzano come separatore.In Azure Key Vault, hierarchical keys use -- as a separator. Il provider di configurazione Azure Key Vault sostituisce -- automaticamente con : un quando i segreti vengono caricati nella configurazione dell'app.The Azure Key Vault configuration provider automatically replaces -- with a : 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.

Valori di configurazione:Configuration values:

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

Provider di configurazioneConfiguration providers

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 daProvides configuration from
Provider di configurazione Azure Key VaultAzure Key Vault configuration provider Insieme di credenziali chiave di AzureAzure Key Vault
Provider di configurazione app AzureAzure App configuration provider Configurazione app di 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 fileFile configuration provider File INI, JSON e XMLINI, JSON, and XML files
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
Gestione segretaSecret Manager File nella directory dei profili utenteFile in the user profile directory

Le origini di configurazione vengono lette nell'ordine in cui sono specificati i provider di configurazione.Configuration sources are read in the order that their configuration providers are specified. Ordinare i provider di configurazione nel codice in base alle priorità per le origini di configurazione sottostanti richieste dall'app.Order configuration providers in code to suit the priorities for the underlying configuration sources that the app requires.

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

  1. appsettings.jsonappsettings.json
  2. appSettings. Environment. JSONappsettings.Environment.json
  3. Gestione segretaSecret Manager
  4. Variabili di ambiente che usano il provider di configurazione delle variabili di ambiente.Environment variables using the Environment Variables configuration provider.
  5. Argomenti della riga di comando che usano il provider di configurazione della riga di comando.Command-line arguments using the Command-line configuration provider.

Una procedura comune consiste nell'aggiungere il provider di configurazione della riga di comando per ultimo in una serie di provider per consentire agli argomenti della riga di comando di eseguire l'override del set di configurazione da parte degli altri provider.A common practice is to add 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 utilizzata nella configurazione predefinita.The preceding sequence of providers is used in the default configuration.

Prefissi della stringa di connessioneConnection string prefixes

L'API di configurazione dispone di regole di elaborazione speciali per quattro variabili di ambiente della stringa di connessione.The Configuration API has special processing rules for four connection string environment variables. Queste stringhe di connessione sono necessarie per configurare le stringhe di connessione di Azure per l'ambiente dell'app.These connection strings are involved in configuring Azure connection strings for the app environment. Le variabili di ambiente con i prefissi visualizzati nella tabella vengono caricate nell'app con la configurazione predefinita o quando non viene fornito alcun AddEnvironmentVariablesprefisso a.Environment variables with the prefixes shown in the table are loaded into the app with the default configuration or when 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 JSONJSON configuration provider

Carica JsonConfigurationProvider la configurazione dalle coppie chiave-valore del file JSON.The JsonConfigurationProvider loads configuration from JSON file key-value pairs.

Gli overload possono specificare:Overloads can specify:

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

Esaminare il codice seguente:Consider the following code:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("MyConfig.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Il codice precedente:The preceding code:

In genere non si vuole che un file JSON personalizzato esegua l'override dei valori impostati nel provider di configurazione delle variabili di ambiente e nel provider di configurazione della riga di comando.You typically don't want a custom JSON file overriding values set in the Environment variables configuration provider and the Command-line configuration provider.

Il codice seguente cancella tutti i provider di configurazione e aggiunge diversi provider di configurazione:The following code clears all the configuration providers and adds several configuration providers:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

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

                config.AddJsonFile("MyConfig.json", optional: true, reloadOnChange: true)
                      .AddJsonFile($"MyConfig.{env.EnvironmentName}.json",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Nel codice precedente, Settings in config. JSON e config. Environment. file JSON :In the preceding code, settings in the MyConfig.json and MyConfig.Environment.json files:

Il download di esempio contiene il file config. JSON seguente:The sample download contains the following MyConfig.json file:

{
    "Position": {
        "Title": "Titolo My Config",
        "Name": "My Config Smith"
    },
    "MyKey": "MyConfig.json Value",
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    },
    "AllowedHosts": "*"
}

Il codice seguente del download dell'esempio Visualizza diverse impostazioni di configurazione precedenti:The following code from the sample download displays several of the preceding configurations settings:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Provider di configurazione 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 derivano da FileConfigurationProvider:The following configuration providers derive from FileConfigurationProvider:

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.

Il codice seguente cancella tutti i provider di configurazione e aggiunge diversi provider di configurazione:The following code clears all the configuration providers and adds several configuration providers:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddIniFile("MyIniConfig.ini", optional: true, reloadOnChange: true)
                      .AddIniFile($"MyIniConfig.{env.EnvironmentName}.ini",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Nel codice precedente, le impostazioni in MyIniConfig. ini e MyIniConfig. Environment. i file ini vengono sottoposti a override dalle impostazioni nel:In the preceding code, settings in the MyIniConfig.ini and MyIniConfig.Environment.ini files are overridden by settings in the:

Il download di esempio contiene il seguente file MyIniConfig. ini :The sample download contains the following MyIniConfig.ini file:

MyKey="MyIniConfig.ini Value"

[Position]
Title="My INI Config title"
Name="My INI Config name"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Il codice seguente del download dell'esempio Visualizza diverse impostazioni di configurazione precedenti:The following code from the sample download displays several of the preceding configurations settings:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

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.

Il codice seguente cancella tutti i provider di configurazione e aggiunge diversi provider di configurazione:The following code clears all the configuration providers and adds several configuration providers:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddXmlFile("MyXMLFile.xml", optional: true, reloadOnChange: true)
                      .AddXmlFile($"MyXMLFile.{env.EnvironmentName}.xml",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Nel codice precedente, le impostazioni in MyXMLFile. XML e MyXMLFile. Environment. i file XML vengono sottoposti a override dalle impostazioni in:In the preceding code, settings in the MyXMLFile.xml and MyXMLFile.Environment.xml files are overridden by settings in the:

Il download di esempio contiene il seguente file MyXMLFile. XML :The sample download contains the following MyXMLFile.xml file:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <MyKey>MyXMLFile Value</MyKey>
  <Position>
    <Title>Title from  MyXMLFile</Title>
    <Name>Name from MyXMLFile</Name>
  </Position>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

Il codice seguente del download dell'esempio Visualizza diverse impostazioni di configurazione precedenti:The following code from the sample download displays several of the preceding configurations settings:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

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 00</key>
    <key name="key1">value 01</key>
  </section>
  <section name="section1">
    <key name="key0">value 10</key>
    <key name="key1">value 11</key>
  </section>
</configuration>

Il codice seguente legge il file di configurazione precedente e visualizza le chiavi e i valori:The following code reads the previous configuration file and displays the keys and values:

public class IndexModel : PageModel
{
    private readonly IConfiguration Configuration;

    public IndexModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var key00 = "section:section0:key:key0";
        var key01 = "section:section0:key:key1";
        var key10 = "section:section1:key:key0";
        var key11 = "section:section1:key:key1";

        var val00 = Configuration[key00];
        var val01 = Configuration[key01];
        var val10 = Configuration[key10];
        var val11 = Configuration[key11];

        return Content($"{key00} value: {val00} \n" +
                       $"{key01} value: {val01} \n" +
                       $"{key10} value: {val10} \n" +
                       $"{key10} value: {val11} \n"
                       );
    }
}

È 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 chiave per fileKey-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 chiave per file viene usato negli scenari di hosting di 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.

Il codice seguente aggiunge una raccolta di memoria al sistema di configurazione:The following code adds a memory collection to the configuration system:

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

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var Dict = new Dictionary<string, string>
        {
           {"MyKey", "Dictionary MyKey Value"},
           {"Position:Title", "Dictionary_Title"},
           {"Position:Name", "Dictionary_Name" },
           {"Logging:LogLevel:Default", "Warning"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(Dict);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Il codice seguente del download dell'esempio Visualizza le impostazioni di configurazione precedenti:The following code from the sample download displays the preceding configurations settings:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Nel codice precedente, config.AddInMemoryCollection(Dict) viene aggiunto dopo i provider di configurazione predefiniti.In the preceding code, config.AddInMemoryCollection(Dict) is added after the default configuration providers. Per un esempio di ordinamento dei provider di configurazione, vedere provider di configurazione JSON.For an example of ordering the configuration providers, see JSON configuration provider.

Vedere associare una matrice per un altro esempio MemoryConfigurationProviderdi utilizzo di.See Bind an array for another example using MemoryConfigurationProvider.

GetValueGetValue

ConfigurationBinder.GetValue<T>estrae un singolo valore dalla configurazione con una chiave specificata e lo converte nel tipo specificato:ConfigurationBinder.GetValue<T> extracts a single value from configuration with a specified key and converts it to the specified type:

public class TestNumModel : PageModel
{
    private readonly IConfiguration Configuration;

    public TestNumModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var number = Configuration.GetValue<int>("NumberKey", 99);
        return Content($"{number}");
    }
}

Nel codice precedente, se NumberKey non è stato trovato nella configurazione, viene usato il valore 99 predefinito di.In the preceding code, if NumberKey isn't found in the configuration, the default value of 99 is used.

GetSection, GetChildren ed ExistsGetSection, GetChildren, and Exists

Per gli esempi che seguono, prendere in considerazione il seguente file MySubsection. JSON :For the examples that follow, consider the following MySubsection.json file:

{
  "section0": {
    "key0": "value00",
    "key1": "value01"
  },
  "section1": {
    "key0": "value10",
    "key1": "value11"
  },
  "section2": {
    "subsection0": {
      "key0": "value200",
      "key1": "value201"
    },
    "subsection1": {
      "key0": "value210",
      "key1": "value211"
    }
  }
}

Il codice seguente aggiunge MySubsection. JSON ai provider di configurazione:The following code adds MySubsection.json to the configuration providers:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("MySubsection.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

GetSectionGetSection

IConfiguration. GetSection restituisce una sottosezione di configurazione con la chiave della sottosezione specificata.IConfiguration.GetSection returns a configuration subsection with the specified subsection key.

Il codice seguente restituisce i valori section1per:The following code returns values for section1:

public class TestSectionModel : PageModel
{
    private readonly IConfiguration Config;

    public TestSectionModel(IConfiguration configuration)
    {
        Config = configuration.GetSection("section1");
    }

    public ContentResult OnGet()
    {
        return Content(
                $"section1:key0: '{Config["key0"]}'\n" +
                $"section1:key1: '{Config["key1"]}'");
    }
}

Il codice seguente restituisce i valori section2:subsection0per:The following code returns values for section2:subsection0:

public class TestSection2Model : PageModel
{
    private readonly IConfiguration Config;

    public TestSection2Model(IConfiguration configuration)
    {
        Config = configuration.GetSection("section2:subsection0");
    }

    public ContentResult OnGet()
    {
        return Content(
                $"section2:subsection0:key0 '{Config["key0"]}'\n" +
                $"section2:subsection0:key1:'{Config["key1"]}'");
    }
}

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.

GetChildren ed EXISTSGetChildren and Exists

Il codice seguente chiama IConfiguration. GetChildren e restituisce i valori section2:subsection0per:The following code calls IConfiguration.GetChildren and returns values for section2:subsection0:

public class TestSection4Model : PageModel
{
    private readonly IConfiguration Config;

    public TestSection4Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        string s = null;
        var selection = Config.GetSection("section2");
        if (!selection.Exists())
        {
            throw new System.Exception("section2 does not exist.");
        }
        var children = selection.GetChildren();

        foreach (var subSection in children)
        {
            int i = 0;
            var key1 = subSection.Key + ":key" + i++.ToString();
            var key2 = subSection.Key + ":key" + i.ToString();
            s += key1 + " value: " + selection[key1] + "\n";
            s += key2 + " value: " + selection[key2] + "\n";
        }
        return Content(s);
    }
}

Il codice precedente chiama ConfigurationExtensions. Exists per verificare che la sezione esista:The preceding code calls ConfigurationExtensions.Exists to verify the section exists:

Associare una matriceBind an array

ConfigurationBinder. Bind supporta l'associazione di matrici a oggetti usando gli indici di matrice nelle chiavi di configurazione.The ConfigurationBinder.Bind supports binding arrays to objects using array indices in configuration keys. Qualsiasi formato di matrice che espone un segmento di chiave numerica è in grado di associare array a una matrice di classi poco .Any array format that exposes a numeric key segment is capable of array binding to a POCO class array.

Si consideri il file con estensione JSON dal download di esempio:Consider MyArray.json from the sample download:

{
  "array": {
    "entries": {
      "0": "value00",
      "1": "value10",
      "2": "value20",
      "4": "value40",
      "5": "value50"
    }
  }
}

Il codice seguente aggiunge il file Array. JSON ai provider di configurazione:The following code adds MyArray.json to the configuration providers:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("MyArray.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Il codice seguente legge la configurazione e Visualizza i valori:The following code reads the configuration and displays the values:

public class ArrayModel : PageModel
{
    private readonly IConfiguration Config;
    public ArrayExample _array { get; private set; }

    public ArrayModel(IConfiguration config)
    {
        Config = config;
    }

    public ContentResult OnGet()
    {
        _array = Config.GetSection("array").Get<ArrayExample>();
        string s = null;

        for (int j = 0; j < _array.Entries.Length; j++)
        {
            s += $"Index: {j}  Value:  {_array.Entries[j]} \n";
        }

        return Content(s);
    }
}

Il codice precedente restituisce l'output seguente:The preceding code returns the following output:

Index: 0  Value: value00
Index: 1  Value: value10
Index: 2  Value: value20
Index: 3  Value: value40
Index: 4  Value: value50

Nell'output precedente, index 3 ha un valore value40, corrispondente a "4": "value40", in ArrayList. JSON.In the preceding output, Index 3 has value value40, corresponding to "4": "value40", in MyArray.json. Gli indici di matrice associati sono continui e non sono associati all'indice della chiave di configurazione.The bound array indices are continuous and not bound to the configuration key index. Il binder di configurazione non è in grado di associare valori null o di creare voci null negli oggetti associatiThe configuration binder isn't capable of binding null values or creating null entries in bound objects

Il codice seguente carica la array:entries configurazione con il AddInMemoryCollection metodo di estensione:The following code loads the array:entries configuration with the AddInMemoryCollection extension method:

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

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var arrayDict = new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            //              3   Skipped
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Il codice seguente legge la configurazione in arrayDict Dictionary e Visualizza i valori:The following code reads the configuration in the arrayDict Dictionary and displays the values:

public class ArrayModel : PageModel
{
    private readonly IConfiguration Config;
    public ArrayExample _array { get; private set; }

    public ArrayModel(IConfiguration config)
    {
        Config = config;
    }

    public ContentResult OnGet()
    {
        _array = Config.GetSection("array").Get<ArrayExample>();
        string s = null;

        for (int j = 0; j < _array.Entries.Length; j++)
        {
            s += $"Index: {j}  Value:  {_array.Entries[j]} \n";
        }

        return Content(s);
    }
}

Il codice precedente restituisce l'output seguente:The preceding code returns the following output:

Index: 0  Value: value0
Index: 1  Value: value1
Index: 2  Value: value2
Index: 3  Value: value4
Index: 4  Value: value5

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 sono associati, gli indici di matrice nelle chiavi di configurazione vengono usati per scorrere i dati di configurazione durante la creazione dell'oggetto.When configuration data containing an array is bound, the array indices in the configuration keys are 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.

È possibile specificare l'elemento di #configurazione mancante per l' ArrayExample indice 3 prima di eseguire il binding all'istanza da qualsiasi provider di #configurazione che legga la coppia chiave/valore dell'indice 3.The missing configuration item for index #3 can be supplied before binding to the ArrayExample instance by any configuration provider that reads the index #3 key/value pair. Si consideri il seguente file valore3. JSON dal Download di esempio:Consider the following Value3.json file from the sample download:

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

Il codice seguente include la configurazione per valore3. JSON e arrayDict Dictionary:The following code includes configuration for Value3.json and the arrayDict Dictionary:

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

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var arrayDict = new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            //              3   Skipped
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile("Value3.json",
                                    optional: false, reloadOnChange: false);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Il codice seguente legge la configurazione precedente e Visualizza i valori:The following code reads the preceding configuration and displays the values:

public class ArrayModel : PageModel
{
    private readonly IConfiguration Config;
    public ArrayExample _array { get; private set; }

    public ArrayModel(IConfiguration config)
    {
        Config = config;
    }

    public ContentResult OnGet()
    {
        _array = Config.GetSection("array").Get<ArrayExample>();
        string s = null;

        for (int j = 0; j < _array.Entries.Length; j++)
        {
            s += $"Index: {j}  Value:  {_array.Entries[j]} \n";
        }

        return Content(s);
    }
}

Il codice precedente restituisce l'output seguente:The preceding code returns the following output:

Index: 0  Value: value0
Index: 1  Value: value1
Index: 2  Value: value2
Index: 3  Value: value3
Index: 4  Value: value4
Index: 5  Value: value5

I provider di configurazione personalizzati non devono implementare l'associazione di matrici.Custom configuration providers aren't required to implement array binding.

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

Accedi alla configurazione all'avvioAccess configuration in Startup

Il codice seguente consente di visualizzare i Startup dati di configurazione nei metodi:The following code displays configuration data in Startup methods:

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
        Console.WriteLine($"MyKey : {Configuration["MyKey"]}");
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        Console.WriteLine($"Position:Title : {Configuration["Position:Title"]}");

        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

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

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.

Configurazione dell'accesso in Razor PagesAccess configuration in Razor Pages

Il codice seguente Visualizza i dati di configurazione in una pagina Razor:The following code displays configuration data in a Razor Page:

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

Configuration value for 'MyKey': @Configuration["MyKey"]

Accedere alla configurazione in un file di visualizzazione MVCAccess configuration in a MVC view file

Il codice seguente consente di visualizzare i dati di configurazione in una visualizzazione MVC:The following code displays configuration data in a MVC view:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

Configuration value for 'MyKey': @Configuration["MyKey"]

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 host predefinitaDefault host configuration

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.

  • La configurazione dell'host viene specificata da:Host configuration is provided from:
  • La configurazione predefinita dell'host Web viene stabilita (ConfigureWebHostDefaults) nel modo seguente:Web Host default configuration is established (ConfigureWebHostDefaults):
    • Kestrel viene usato come server Web e configurato con i provider di configurazione dell'app.Kestrel is used as the web server and configured using the app's configuration providers.
    • Aggiungere il middleware di filtro host.Add Host Filtering Middleware.
    • Aggiungere il middleware delle intestazioni inoltrate se la variabile di ambiente ASPNETCORE_FORWARDEDHEADERS_ENABLED è impostata su true.Add Forwarded Headers Middleware if the ASPNETCORE_FORWARDEDHEADERS_ENABLED environment variable is set to true.
    • Abilitare l'integrazione di IIS.Enable IIS integration.

Altra configurazioneOther configuration

Questo argomento riguarda solo la configurazione dell'app.This topic only pertains to app configuration. Altri aspetti dell'esecuzione e dell'hosting di app ASP.NET Core sono configurati usando i file di configurazione non trattati in questo argomento:Other aspects of running and hosting ASP.NET Core apps are configured using configuration files not covered in this topic:

  • Launch. JSON/launchSettings. JSON sono i file di configurazione degli strumenti per l'ambiente di sviluppo, descritti:launch.json/launchSettings.json are tooling configuration files for the Development environment, described:
  • Web. config è un file di configurazione del server, descritto negli argomenti seguenti:web.config is a server configuration file, described in the following topics:

Per ulteriori informazioni sulla migrazione della configurazione dell'app da versioni precedenti di ASP.NET Eseguire la migrazione da ASP.NET ad ASP.NET Core, vedere.For more information on migrating app configuration from earlier versions of ASP.NET, see Eseguire la migrazione da ASP.NET ad ASP.NET Core.

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 altre 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

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:

  • Insieme di credenziali chiave di AzureAzure Key Vault
  • Configurazione app di 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 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 altre 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.

Altra configurazioneOther configuration

Questo argomento riguarda solo la configurazione dell'app.This topic only pertains to app configuration. Altri aspetti dell'esecuzione e dell'hosting di app ASP.NET Core sono configurati usando i file di configurazione non trattati in questo argomento:Other aspects of running and hosting ASP.NET Core apps are configured using configuration files not covered in this topic:

  • Launch. JSON/launchSettings. JSON sono i file di configurazione degli strumenti per l'ambiente di sviluppo, descritti:launch.json/launchSettings.json are tooling configuration files for the Development environment, described:
  • Web. config è un file di configurazione del server, descritto negli argomenti seguenti:web.config is a server configuration file, described in the following topics:

Per ulteriori informazioni sulla migrazione della configurazione dell'app da versioni precedenti di ASP.NET Eseguire la migrazione da ASP.NET ad ASP.NET Core, vedere.For more information on migrating app configuration from earlier versions of ASP.NET, see Eseguire la migrazione da ASP.NET ad 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 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 altre 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. IConfigurationpuò essere inserito in un Razor Pages PageModel o MVC Controller per ottenere la configurazione per la classe.IConfiguration can be injected into a Razor Pages PageModel or MVC Controller to obtain configuration for the class.

Negli esempi seguenti il _config campo viene usato per accedere ai valori di configurazione:In the following examples, the _config field is used to access configuration values:

public class IndexModel : PageModel
{
    private readonly IConfiguration _config;

    public IndexModel(IConfiguration config)
    {
        _config = config;
    }
}
public class HomeController : Controller
{
    private readonly IConfiguration _config;

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

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. Scrivere il codice per sostituire i trattini con i due punti quando i segreti vengono caricati nella configurazione dell'app.Write 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) Insieme di credenziali chiave di AzureAzure Key Vault
Provider di Configurazione app (Documentazione di Azure)Azure App Configuration Provider (Azure documentation) Configurazione app di 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 fileFile Configuration Provider File (INI, JSON, XML)Files (INI, JSON, XML)
Provider di configurazione KeyPerFileKey-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 sono descritti in ordine alfabetico, non nell'ordine in cui il codice li dispone.The configuration providers described in this topic are described in alphabetical order, not in the order that the code arranges them. Ordinare i provider di configurazione nel codice in base alle priorità per le origini di configurazione sottostanti richieste dall'app.Order configuration providers in code to suit the priorities for the underlying configuration sources that the app requires.

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

  1. Files (appSettings. JSON, appSettings. { Environment}. JSON, dove {Environment} è l'ambiente host corrente dell'app)Files (appsettings.json, appsettings.{Environment}.json, where {Environment} is the app's current hosting environment)
  2. Insieme di credenziali chiave 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 utilizzata quando viene inizializzato un nuovo generatore host CreateDefaultBuildercon.The preceding sequence of providers is used when a new host builder is initialized with CreateDefaultBuilder. Per altre informazioni, vedere la sezione Configurazione predefinita.For more information, see the Default configuration section.

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)
    {
        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.

ArgumentsArguments

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 compila manualmente la ConfigurationBuilder AddCommandLine configurazione con un oggetto, fornire un dizionario di sostituzioni switch al metodo.When manually building configuration with a ConfigurationBuilder, 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 ValoreValue
-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 ValoreValue
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.

Il : separatore non funziona con le chiavi gerarchiche delle variabili di ambiente in tutte le piattaforme.The : separator doesn't work with environment variable hierarchical keys on all platforms. __, il doppio carattere di sottolineatura, è:__, the double underscore, is:

  • Supportato da tutte le piattaforme.Supported by all platforms. Il : separatore, ad esempio, non è Bashsupportato da bash __ , ma è.For example, the : separator is not supported by Bash, but __ is.
  • Sostituito automaticamente da:Automatically replaced by a :

App Azure servizio consente di impostare le variabili di ambiente nel portale di Azure che possono eseguire l'override della configurazione dell'app usando il provider di configurazione delle variabili di ambiente.Azure App Service permits setting 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 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.

Per fornire la configurazione dell'app da altre variabili di ambiente, chiamare i provider aggiuntivi ConfigureAppConfiguration dell'app AddEnvironmentVariables in e chiamare con il prefisso: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) =>
{
    config.AddEnvironmentVariables(prefix: "PREFIX_");
})

Chiamare AddEnvironmentVariables Last per consentire alle variabili di ambiente con il prefisso specificato di eseguire l'override dei valori di altri provider.Call AddEnvironmentVariables last to allow environment variables with the given prefix to override values from other providers.

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.

Per esporre tutte le variabili di ambiente disponibili per l'app, modificare FilteredConfiguration in pages/index. cshtml. cs come riportato di seguito: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 AddEnvironmentVariables per il metodo.Environment variables loaded into the app's configuration are filtered when supplying 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

EsempioExample

Nel server viene creata una variabile di ambiente della stringa di connessione personalizzata:A custom connection string environment variable is created on the server:

  • Nome –CUSTOMCONNSTR_ReleaseDBName – CUSTOMCONNSTR_ReleaseDB
  • Valore – diData Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=TrueValue – Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True

Se IConfiguration viene inserito e assegnato a un campo denominato _config, leggere il valore:If IConfiguration is injected and assigned to a field named _config, read the value:

_config["ConnectionStrings:ReleaseDB"]

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.

AddJsonFileviene chiamato automaticamente due volte quando viene inizializzato un nuovo generatore CreateDefaultBuilderhost con.AddJsonFile is automatically called twice when a new host builder is initialized 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 sfrutta il metodo CreateDefaultBuilder di convenienza statica per compilare 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 prima chiamata a AddJsonFile carica la configurazione da appSettings. JSON:The first call to AddJsonFile loads configuration from appsettings.json:

    {
      "Logging": {
        "LogLevel": {
          "Default": "Warning"
        }
      },
      "AllowedHosts": "*"
    }
    
  • La seconda chiamata a AddJsonFile carica la configurazione da appSettings. { Environment}. JSON.The second call to AddJsonFile loads configuration from appsettings.{Environment}.json. Per appSettings. Development. JSON nell'app di esempio, viene caricato il file seguente:For appsettings.Development.json in the sample app, the following file is loaded:

    {
      "Logging": {
        "LogLevel": {
          "Default": "Debug",
          "System": "Information",
          "Microsoft": "Information"
        }
      }
    }
    
  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. L'output contiene coppie chiave-valore per la configurazione basata sull'ambiente dell'app.The output contains key-value pairs for the configuration based on the app's environment. Il livello di registrazione della chiave Logging:LogLevel:Default è Debug quando si esegue l'app nell'ambiente di sviluppo.The log level for the key Logging:LogLevel:Default is Debug when running the app in the Development environment.
  3. Eseguire di nuovo l'app di esempio nell'ambiente di produzione:Run the sample app again in the Production environment:
    1. Aprire il file Properties/launchSettings. JSON .Open the Properties/launchSettings.json file.
    2. Nel ConfigurationSample profilo, modificare il valore della variabile di ASPNETCORE_ENVIRONMENT ambiente in Production.In the ConfigurationSample profile, change the value of the ASPNETCORE_ENVIRONMENT environment variable to Production.
    3. Salvare il file ed eseguire l'app con dotnet run in una shell dei comandi.Save the file and run the app with dotnet run in a command shell.
  4. Impostazioni in appSettings. Development. JSON non sostituisce più le impostazioni in appSettings. JSON.The settings in the appsettings.Development.json no longer override the settings in appsettings.json. Il livello di registrazione per la Logging:LogLevel:Default chiave Warningè.The log level for the key Logging:LogLevel:Default is Warning.

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();

ExistsExists

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.

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. Come per l'associazione di un oggetto semplice, vengono associate solo le proprietà di lettura/scrittura pubbliche.As with binding a simple object, only public read/write properties are bound.

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

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

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

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

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

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

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

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

ConfigurationBinder.Get<T>associa e restituisce il tipo specificato.ConfigurationBinder.Get<T> binds and returns the specified type. Get<T> può essere più comodo che usare Bind.Get<T> is more convenient than using Bind. Il codice seguente illustra come usare Get<T> con l'esempio precedente:The following code shows how to use Get<T> with the preceding example:

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 di chiave:0:numerico :1:( … :{n}:,,) è in grado di associare array 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 ValoreValue
array:entries:0array:entries:0 value0value0
array:entries:1array:entries:1 value1value1
array:entries:2array:entries:2 value2value2
array:entries:4array:entries:4 value4value4
array:entries:5array:entries:5 value5value5

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

missing_value.json:missing_value.json:

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

In ConfigureAppConfiguration:In ConfigureAppConfiguration:

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

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

ChiaveKey ValoreValue
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 ArrayExample.Entries ValoreArrayExample.Entries Value
00 value0value0
11 value1value1
22 value2value2
33 value3value3
44 value4value4
55 value5value5

Elaborazione di matrice JSONJSON array processing

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

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

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

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

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

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

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

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

Provider di configurazione personalizzatoCustom configuration provider

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Action<DbContextOptionsBuilder> OptionsAction { get; }

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

        OptionsAction(builder);

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

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

    private static IDictionary<string, string> CreateAndSaveDefaultValues(
        EFConfigurationContext dbContext)
    {
        // Quotes (c)2005 Universal Pictures: Serenity
        // https://www.uphe.com/movies/serenity
        var configValues = 
            new Dictionary<string, string>(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 Razor una pagina di pagine o in una visualizzazione MVCAccess configuration in a Razor Pages page or MVC view

Per accedere alle impostazioni di configurazione Razor in una pagina di pagine o in una visualizzazione MVC, aggiungere una direttiva using (riferimenti per C#: direttiva using) per lo spazio dei nomi Microsoft. Extensions. Configuration e inserire IConfiguration nella pagina o nella vista.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 Razor pagina di pagine: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 altre 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