Configuration dans ASP.NET CoreConfiguration in ASP.NET Core

Par Luke LathamBy Luke Latham

La configuration d’application dans ASP.NET Core est basée sur des paires clé-valeur établies par les fournisseurs de configuration.App configuration in ASP.NET Core is based on key-value pairs established by configuration providers. Les fournisseurs de configuration lisent les données de configuration dans les paires clé-valeur à partir de diverses sources de configuration :Configuration providers read configuration data into key-value pairs from a variety of configuration sources:

  • Azure Key VaultAzure Key Vault
  • Arguments de ligne de commandeCommand-line arguments
  • Fournisseurs personnalisés (installés ou créés)Custom providers (installed or created)
  • Fichiers de répertoireDirectory files
  • Variables d’environnementEnvironment variables
  • Objets .NET en mémoireIn-memory .NET objects
  • Fichiers de paramètresSettings files
  • Azure Key VaultAzure Key Vault
  • Arguments de ligne de commandeCommand-line arguments
  • Fournisseurs personnalisés (installés ou créés)Custom providers (installed or created)
  • Variables d’environnementEnvironment variables
  • Objets .NET en mémoireIn-memory .NET objects
  • Fichiers de paramètresSettings files
  • Arguments de ligne de commandeCommand-line arguments
  • Fournisseurs personnalisés (installés ou créés)Custom providers (installed or created)
  • Variables d’environnementEnvironment variables
  • Objets .NET en mémoireIn-memory .NET objects
  • Fichiers de paramètresSettings files

Le modèle d’options est une extension des concepts de configuration décrits dans cette rubrique.The options pattern is an extension of the configuration concepts described in this topic. Le modèle d’options utilise des classes pour représenter les groupes de paramètres associés.Options uses classes to represent groups of related settings. Pour plus d’informations sur l’utilisation du modèle d’options, consultez Modèle d’options dans ASP.NET Core.For more information on using the options pattern, see Modèle d’options dans ASP.NET Core.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

Les exemples fournis dans cette rubrique s’appuient sur :The examples provided in this topic rely upon:

Ces trois packages sont inclus dans le métapackage Microsoft.AspNetCore.App.These three packages are included in the Microsoft.AspNetCore.App metapackage.

Ces trois packages sont inclus dans le métapackage Microsoft.AspNetCore.All.These three packages are included in the Microsoft.AspNetCore.All metapackage.

Configuration de l’hôte ou configuration de l’applicationHost vs. app configuration

Avant que l’application ne soit configurée et démarrée, un hôte est configuré et lancé.Before the app is configured and started, a host is configured and launched. L’hôte est responsable de la gestion du démarrage et de la durée de vie des applications.The host is responsible for app startup and lifetime management. L’application et l’hôte sont configurés à l’aide des fournisseurs de configuration décrits dans cette rubrique.Both the app and the host are configured using the configuration providers described in this topic. Les paires clé-valeur de la configuration de l’hôte font partie de la configuration générale de l’application.Host configuration key-value pairs become part of the app's global configuration. Pour plus d’informations sur l’utilisation des fournisseurs de configuration lors de la génération de l’hôte et l’impact des sources de configuration sur la configuration de l’hôte, consultez Hôte web et hôte générique dans 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 Hôte web et hôte générique dans ASP.NET Core.

SécuritéSecurity

Adoptez les meilleures pratiques suivantes :Adopt the following best practices:

  • Ne stockez jamais des mots de passe ou d’autres données sensibles dans le code du fournisseur de configuration ou dans les fichiers de configuration en texte clair.Never store passwords or other sensitive data in configuration provider code or in plain text configuration files.
  • N’utilisez aucun secret de production dans les environnements de développement ou de test.Don't use production secrets in development or test environments.
  • Spécifiez les secrets en dehors du projet afin qu’ils ne puissent pas être validés par inadvertance dans un référentiel de code source.Specify secrets outside of the project so that they can't be accidentally committed to a source code repository.

En savoir plus sur l’utilisation de plusieurs environnements et la gestion du stockage sécurisé des secrets d’application dans le développement avec Secret Manager (contient des conseils sur l’utilisation des variables d’environnement pour stocker les données sensibles).Learn more about how to use multiple environments and managing the safe storage of app secrets in development with the Secret Manager (includes advice on using environment variables to store sensitive data). Secret Manager utilise le fournisseur de configuration de fichier pour stocker les secrets utilisateur dans un fichier JSON sur le système local.The Secret Manager uses the File Configuration Provider to store user secrets in a JSON file on the local system. Le fournisseur de configuration de fichier est décrit plus loin dans cette rubrique.The File Configuration Provider is described later in this topic.

Azure Key Vault constitue une option pour le stockage sécurisé des secrets d’application.Azure Key Vault is one option for the safe storage of app secrets. Pour plus d'informations, consultez Fournisseur de configuration Azure Key Vault dans ASP.NET Core.For more information, see Fournisseur de configuration Azure Key Vault dans ASP.NET Core.

Données de configuration hiérarchiquesHierarchical configuration data

L’API Configuration est capable de maintenir des données de configuration hiérarchiques en aplanissant les données hiérarchiques à l’aide d’un délimiteur dans les clés de configuration.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.

Dans le fichier JSON suivant, quatre clés existent dans une structure hiérarchique à deux sections :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"
  }
}

Lorsque le fichier est lu dans la configuration, des clés uniques sont créées pour gérer la structure des données hiérarchiques d’origine de la source de configuration.When the file is read into configuration, unique keys are created to maintain the original hierarchical data structure of the configuration source. Les sections et les clés sont aplanies à l’aide d’un signe deux-points (:) pour conserver la structure d’origine :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

Les méthodes GetSection et GetChildren sont disponibles pour isoler les sections et les enfants d’une section dans les données de configuration.GetSection and GetChildren methods are available to isolate sections and children of a section in the configuration data. Ces méthodes sont décrites plus loin dans GetSection, GetChildren et Exists.These methods are described later in GetSection, GetChildren, and Exists.

ConventionsConventions

Au démarrage de l’application, les sources de configuration sont lues dans l’ordre où leurs fournisseurs de configuration sont spécifiés.At app startup, configuration sources are read in the order that their configuration providers are specified.

Les fournisseurs de configuration de fichier peuvent recharger la configuration lorsqu’un fichier de paramètres sous-jacent est modifié après le démarrage de l’application.File Configuration Providers have the ability to reload configuration when an underlying settings file is changed after app startup. Le fournisseur de configuration de fichier est décrit plus loin dans cette rubrique.The File Configuration Provider is described later in this topic.

IConfiguration est disponible dans le conteneur Dependency Injection (DI) de l’application.IConfiguration is available in the app's Dependency Injection (DI) container. Les fournisseurs de configuration ne peuvent pas utiliser le DI, car celui-ci n’est pas disponible lorsque les fournisseurs sont configurés par l’hôte.Configuration providers can't utilize DI, as it's not available when they're set up by the host.

Les clés de configuration adoptent les conventions suivantes :Configuration keys adopt the following conventions:

  • Les clés ne respectent pas la casse.Keys are case-insensitive. Par exemple, ConnectionString et connectionstring sont traités en tant que clés équivalentes.For example, ConnectionString and connectionstring are treated as equivalent keys.
  • Si une valeur pour la même clé est définie par des fournisseurs de configuration identiques ou différents, la valeur utilisée est la dernière valeur définie sur la clé.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.
  • Clés hiérarchiquesHierarchical keys
    • Dans l’API Configuration, un séparateur sous forme de signe deux-points (:) fonctionne sur toutes les plateformes.Within the Configuration API, a colon separator (:) works on all platforms.
    • Dans les variables d’environnement, un séparateur sous forme de signe deux-points peut ne pas fonctionner sur toutes les plateformes.In environment variables, a colon separator may not work on all platforms. Un trait de soulignement double (__) est pris en charge par toutes les plateformes et converti en signe deux-points.A double underscore (__) is supported by all platforms and is converted to a colon.
    • Dans Azure Key Vault, les clés hiérarchiques utilisent -- (deux tirets) comme séparateur.In Azure Key Vault, hierarchical keys use -- (two dashes) as a separator. Vous devez fournir du code pour remplacer les tirets par un signe deux-points lorsque les secrets sont chargés dans la configuration de l’application.You must provide code to replace the dashes with a colon when the secrets are loaded into the app's configuration.
  • ConfigurationBinder prend en charge la liaison de tableaux à des objets à l’aide d’index de tableau dans les clés de configuration.The ConfigurationBinder supports binding arrays to objects using array indices in configuration keys. La liaison de tableau est décrite dans la section Lier un tableau à une classe.Array binding is described in the Bind an array to a class section.

Les valeurs de configuration adoptent les conventions suivantes :Configuration values adopt the following conventions:

  • Les valeurs sont des chaînes.Values are strings.
  • Les valeurs NULL ne peuvent pas être stockées dans la configuration ou liées à des objets.Null values can't be stored in configuration or bound to objects.

FournisseursProviders

Le tableau suivant présente les fournisseurs de configuration disponibles pour les applications ASP.NET Core.The following table shows the configuration providers available to ASP.NET Core apps.

FournisseurProvider Fournit la configuration à partir de…Provides configuration from…
Fournisseur de configuration Azure Key Vault (rubrique Sécurité)Azure Key Vault Configuration Provider (Security topics) Azure Key VaultAzure Key Vault
Fournisseur de configuration de ligne de commandeCommand-line Configuration Provider Paramètres de ligne de commandeCommand-line parameters
Fournisseur de configuration personnaliséCustom configuration provider Source personnaliséeCustom source
Fournisseur de configuration de variables d’environnementEnvironment Variables Configuration Provider Variables d’environnementEnvironment variables
Fournisseur de configuration de fichierFile Configuration Provider Fichiers (INI, JSON, XML)Files (INI, JSON, XML)
Fournisseur de configuration clé par fichierKey-per-file Configuration Provider Fichiers de répertoireDirectory files
Fournisseur de configuration de mémoireMemory Configuration Provider Collections en mémoireIn-memory collections
Secrets utilisateur (Secret Manager) (rubrique Sécurité)User secrets (Secret Manager) (Security topics) Fichier dans le répertoire de profil utilisateurFile in the user profile directory
FournisseurProvider Fournit la configuration à partir de…Provides configuration from…
Fournisseur de configuration Azure Key Vault (rubrique Sécurité)Azure Key Vault Configuration Provider (Security topics) Azure Key VaultAzure Key Vault
Fournisseur de configuration de ligne de commandeCommand-line Configuration Provider Paramètres de ligne de commandeCommand-line parameters
Fournisseur de configuration personnaliséCustom configuration provider Source personnaliséeCustom source
Fournisseur de configuration de variables d’environnementEnvironment Variables Configuration Provider Variables d’environnementEnvironment variables
Fournisseur de configuration de fichierFile Configuration Provider Fichiers (INI, JSON, XML)Files (INI, JSON, XML)
Fournisseur de configuration de mémoireMemory Configuration Provider Collections en mémoireIn-memory collections
Secrets utilisateur (Secret Manager) (rubrique Sécurité)User secrets (Secret Manager) (Security topics) Fichier dans le répertoire de profil utilisateurFile in the user profile directory
FournisseurProvider Fournit la configuration à partir de…Provides configuration from…
Fournisseur de configuration de ligne de commandeCommand-line Configuration Provider Paramètres de ligne de commandeCommand-line parameters
Fournisseur de configuration personnaliséCustom configuration provider Source personnaliséeCustom source
Fournisseur de configuration de variables d’environnementEnvironment Variables Configuration Provider Variables d’environnementEnvironment variables
Fournisseur de configuration de fichierFile Configuration Provider Fichiers (INI, JSON, XML)Files (INI, JSON, XML)
Fournisseur de configuration de mémoireMemory Configuration Provider Collections en mémoireIn-memory collections
Secrets utilisateur (Secret Manager) (rubrique Sécurité)User secrets (Secret Manager) (Security topics) Fichier dans le répertoire de profil utilisateurFile in the user profile directory

Au démarrage, les sources de configuration sont lues dans l’ordre où leurs fournisseurs de configuration sont spécifiés.Configuration sources are read in the order that their configuration providers are specified at startup. Les fournisseurs de configuration décrits dans cette rubrique sont décrits dans l’ordre alphabétique, et non dans l’ordre où votre code peut les organiser.The configuration providers described in this topic are described in alphabetical order, not in the order that your code may arrange them. Organisez les fournisseurs de configuration dans votre code en fonction de vos priorités pour les sources de configuration sous-jacentes.Order configuration providers in your code to suit your priorities for the underlying configuration sources.

Une séquence type des fournisseurs de configuration est la suivante :A typical sequence of configuration providers is:

  1. Fichiers (appsettings.json, appsettings.{Environment}.json, où {Environment} est l'environnement d’hébergement actuel de l'application)Files (appsettings.json, appsettings.{Environment}.json, where {Environment} is the app's current hosting environment)
  2. Azure Key VaultAzure Key Vault
  3. Secrets utilisateur (Secret Manager) (dans l’environnement de développement uniquement)User secrets (Secret Manager) (in the Development environment only)
  4. Variables d’environnementEnvironment variables
  5. Arguments de ligne de commandeCommand-line arguments

Une pratique courante consiste à placer le Fournisseur de configuration de ligne de commande en dernier dans une série de fournisseurs pour permettre aux arguments de ligne de commande de remplacer la configuration définie par les autres fournisseurs.It's a common practice to position the Command-line Configuration Provider last in a series of providers to allow command-line arguments to override configuration set by the other providers.

Cette séquence de fournisseurs est mise en place lorsque vous initialisez un nouveau WebHostBuilder avec CreateDefaultBuilder.This sequence of providers is put into place when you initialize a new WebHostBuilder with CreateDefaultBuilder. Pour plus d’informations, consultez l’hôte web : Configurer un hôte.For more information, see Web Host: Set up a host.

Cette séquence de fournisseurs peut être créée pour l’application (pas l’hôte) avec un ConfigurationBuilder et un appel à sa méthode Build dans Startup :This sequence of providers can be created for the app (not the host) with a ConfigurationBuilder and a call to its Build method in Startup:

public Startup(IHostingEnvironment env)
{
    var builder = new ConfigurationBuilder()
        .SetBasePath(Directory.GetCurrentDirectory())
        .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
        .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, 
            reloadOnChange: true);

    var appAssembly = Assembly.Load(new AssemblyName(env.ApplicationName));

    if (appAssembly != null)
    {
        builder.AddUserSecrets(appAssembly, optional: true);
    }

    builder.AddEnvironmentVariables();

    Configuration = builder.Build();
}

public IConfiguration Configuration { get; }

public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<IConfiguration>(Configuration);
}

Dans l’exemple précédent, le nom de l’environnement (env.EnvironmentName) et le nom de l’assembly d’application (env.ApplicationName) sont fournis par IHostingEnvironment.In the preceding example, the environment name (env.EnvironmentName) and app assembly name (env.ApplicationName) are provided by the IHostingEnvironment. Pour plus d'informations, consultez Utiliser plusieurs environnements dans ASP.NET Core.For more information, see Utiliser plusieurs environnements dans ASP.NET Core.

ConfigureAppConfigurationConfigureAppConfiguration

Appelez ConfigureAppConfiguration lors de la création de l'hôte web pour spécifier les fournisseurs de configuration de l'application en plus de ceux ajoutés automatiquement par CreateDefaultBuilder :Call ConfigureAppConfiguration when building the Web Host to specify the app's configuration providers in addition to those added automatically by CreateDefaultBuilder:

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

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

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

Fournisseur de configuration de ligne de commandeCommand-line Configuration Provider

CommandLineConfigurationProvider charge la configuration à partir des paires clé-valeur de l’argument de ligne de commande lors de l’exécution.The CommandLineConfigurationProvider loads configuration from command-line argument key-value pairs at runtime.

Pour activer la configuration en ligne de commande, la méthode d’extension AddCommandLine est appelée sur une instance de ConfigurationBuilder.To activate command-line configuration, the AddCommandLine extension method is called on an instance of ConfigurationBuilder.

AddCommandLine est appelé automatiquement lorsque vous initialisez un nouveau WebHostBuilder avec CreateDefaultBuilder.AddCommandLine is automatically called when you initialize a new WebHostBuilder with CreateDefaultBuilder. Pour plus d’informations, consultez l’hôte web : Configurer un hôte.For more information, see Web Host: Set up a host.

CreateDefaultBuilder charge également :CreateDefaultBuilder also loads:

  • Configuration facultative à partir d’appsettings.json et d’appsettings.{Environment}.json.Optional configuration from appsettings.json and appsettings.{Environment}.json.
  • Secrets utilisateur (Secret Manager) (dans l’environnement de développement).User secrets (Secret Manager) (in the Development environment).
  • Variables d'environnement.Environment variables.

CreateDefaultBuilder ajoute en dernier le Fournisseur de configuration de ligne de commande.CreateDefaultBuilder adds the Command-line Configuration Provider last. Les arguments de ligne de commande passés lors de l’exécution remplacent la configuration définie par les autres fournisseurs.Command-line arguments passed at runtime override configuration set by the other providers.

CreateDefaultBuilder agit lors de la construction de l’hôte.CreateDefaultBuilder acts when the host is constructed. Par conséquent, la configuration de ligne de commande activée par CreateDefaultBuilder peut affecter la façon dont l’hôte est configuré.Therefore, command-line configuration activated by CreateDefaultBuilder can affect how the host is configured.

Appelez ConfigureAppConfiguration lors de la création de l’hôte pour spécifier la configuration de l’application.Call ConfigureAppConfiguration when building the host to specify the app's configuration.

AddCommandLine a déjà été appelé par CreateDefaultBuilder.AddCommandLine has already been called by CreateDefaultBuilder. Si vous devez fournir la configuration de l'application tout en étant capable de remplacer cette configuration par des arguments de ligne de commande, appelez les fournisseurs supplémentaires de l'application dans ConfigureAppConfiguration et appelez AddCommandLine en dernier.If you need to provide app configuration and still be able to override that configuration with command-line arguments, call the app's additional providers in ConfigureAppConfiguration and call AddCommandLine last.

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

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

Lorsque vous créez un WebHostBuilder directement, appelez UseConfiguration avec la configuration :When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Appliquez la configuration à WebHostBuilder avec la méthode UseConfiguration.Apply the configuration to WebHostBuilder with the UseConfiguration method.

AddCommandLine a déjà été appelé par CreateDefaultBuilder lorsque UseConfiguration est appelé.AddCommandLine has already been called by CreateDefaultBuilder when UseConfiguration is called. Si vous devez fournir la configuration de l'application tout en étant capable de remplacer cette configuration par des arguments de ligne de commande, appelez les fournisseurs supplémentaires de l'application sur un ConfigurationBuilder et appelez AddCommandLine en dernier.If you need to provide app configuration and still be able to override that configuration with command-line arguments, call the app's additional providers on a ConfigurationBuilder and call AddCommandLine last.

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            // Call other providers here and call AddCommandLine last.
            .AddCommandLine(args)
            .Build();

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

Lorsque vous créez un WebHostBuilder directement, appelez UseConfiguration avec la configuration :When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Pour activer la configuration en ligne de commande, appelez la méthode d’extension AddCommandLine sur une instance de ConfigurationBuilder.To activate command-line configuration, call the AddCommandLine extension method on an instance of ConfigurationBuilder.

Appelez le fournisseur en dernier pour permettre aux arguments de ligne de commande passés au moment de l’exécution de remplacer la configuration définie par les autres fournisseurs de configuration.Call the provider last to allow the command-line arguments passed at runtime to override configuration set by other configuration providers.

Appliquez la configuration à WebHostBuilder avec la méthode UseConfiguration :Apply the configuration to WebHostBuilder with the UseConfiguration method:

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

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

ExempleExample

L’exemple d’application 2.x tire parti de la méthode pratique statique CreateDefaultBuilder pour générer l’hôte, qui inclut un appel à AddCommandLine.The 2.x sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes a call to AddCommandLine.

L’exemple d’application 1.x appelle AddCommandLine sur un ConfigurationBuilder.The 1.x sample app calls AddCommandLine on a ConfigurationBuilder.

  1. Ouvrez une invite de commandes dans le répertoire du projet.Open a command prompt in the project's directory.
  2. Fournissez un argument de ligne de commande à la commande dotnet run, dotnet run CommandLineKey=CommandLineValue.Supply a command-line argument to the dotnet run command, dotnet run CommandLineKey=CommandLineValue.
  3. Une fois que l’application est en cours d’exécution, ouvrez un navigateur à l’application à l’adresse http://localhost:5000.After the app is running, open a browser to the app at http://localhost:5000.
  4. Notez que la sortie contient la paire clé-valeur pour l’argument de ligne de commande de configuration fourni à dotnet run.Observe that the output contains the key-value pair for the configuration command-line argument provided to dotnet run.

ArgumentsArguments

La valeur doit suivre un signe égal (=) ou la clé doit avoir un préfixe (-- ou /) lorsque la valeur suit un espace.The value must follow an equals sign (=), or the key must have a prefix (-- or /) when the value follows a space. La valeur peut être null si un signe égal est utilisé (par exemple, CommandLineKey=).The value can be null if an equals sign is used (for example, CommandLineKey=).

Préfixe de cléKey prefix ExempleExample
Aucun préfixeNo prefix CommandLineKey1=value1
Deux tirets (--)Two dashes (--) --CommandLineKey2=value2, --CommandLineKey2 value2--CommandLineKey2=value2, --CommandLineKey2 value2
Barre oblique (/)Forward slash (/) /CommandLineKey3=value3, /CommandLineKey3 value3/CommandLineKey3=value3, /CommandLineKey3 value3

Dans la même commande, ne mélangez pas des paires clé-valeur de l’argument de ligne de commande qui utilisent un signe égal avec des paires clé-valeur qui utilisent un espace.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.

Exemples de commandes :Example commands:

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

Correspondances de commutateurSwitch mappings

Les correspondances de commutateur permettent une logique de remplacement des noms de clés.Switch mappings allow key name replacement logic. Lorsque vous générez manuellement la configuration avec un ConfigurationBuilder, vous pouvez fournir un dictionnaire des remplacements de commutateur à la méthode AddCommandLine.When you manually build configuration with a ConfigurationBuilder, you can provide a dictionary of switch replacements to the AddCommandLine method.

Quand le dictionnaire de correspondances de commutateur est utilisé, il est vérifié afin de déterminer s’il contient une clé correspondant à celle fournie par un argument de ligne de commande.When the switch mappings dictionary is used, the dictionary is checked for a key that matches the key provided by a command-line argument. Si la clé de ligne de commande est trouvée dans le dictionnaire, la valeur du dictionnaire (le remplacement de la clé) est repassée pour définir la paire clé-valeur dans la configuration de l’application.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. Une correspondance de commutateur est nécessaire pour chaque clé de ligne de commande préfixée avec un tiret unique (-).A switch mapping is required for any command-line key prefixed with a single dash (-).

Règles des clés du dictionnaire de correspondances de commutateur :Switch mappings dictionary key rules:

  • Les commutateurs doivent commencer par un tiret (-) ou un double tiret (--).Switches must start with a dash (-) or double-dash (--).
  • Le dictionnaire de correspondances de commutateur ne doit pas contenir de clés en double.The switch mappings dictionary must not contain duplicate keys.

Appelez ConfigureAppConfiguration lors de la création de l’hôte pour spécifier la configuration de l’application :Call ConfigureAppConfiguration when building the host to specify the app's configuration:

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

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

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

Comme indiqué dans l’exemple précédent, l’appel à CreateDefaultBuilder ne doit pas passer des arguments lorsque des correspondances de commutateur sont utilisées.As shown in the preceding example, the call to CreateDefaultBuilder shouldn't pass arguments when switch mappings are used. L’appel AddCommandLine de la méthode CreateDefaultBuilder n’inclut pas de commutateurs mappés et il n’existe aucun moyen de transmettre le dictionnaire de correspondance de commutateur à CreateDefaultBuilder.CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and there's no way to pass the switch mapping dictionary to CreateDefaultBuilder. Si les arguments incluent un commutateur mappé et sont passés à CreateDefaultBuilder, son fournisseur AddCommandLine ne parvient pas à s’initialiser avec un FormatException.If the arguments include a mapped switch and are passed to CreateDefaultBuilder, its AddCommandLine provider fails to initialize with a FormatException. La solution ne consiste pas à transmettre les arguments à CreateDefaultBuilder, mais plutôt à permettre à la méthode AddCommandLine de la méthode ConfigurationBuilder de traiter les arguments et le dictionnaire de mappage de commutateur.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.

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var switchMappings = new Dictionary<string, string>
            {
                { "-CLKey1", "CommandLineKey1" },
                { "-CLKey2", "CommandLineKey2" }
            };

        var config = new ConfigurationBuilder()
            .AddCommandLine(args, switchMappings)
            .Build();

        // Do not pass the args to CreateDefaultBuilder
        return WebHost.CreateDefaultBuilder()
            .UseConfiguration(config)
            .UseStartup<Startup>();
    }
}

Comme indiqué dans l’exemple précédent, l’appel à CreateDefaultBuilder ne doit pas passer des arguments lorsque des correspondances de commutateur sont utilisées.As shown in the preceding example, the call to CreateDefaultBuilder shouldn't pass arguments when switch mappings are used. L’appel AddCommandLine de la méthode CreateDefaultBuilder n’inclut pas de commutateurs mappés et il n’existe aucun moyen de transmettre le dictionnaire de correspondance de commutateur à CreateDefaultBuilder.CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and there's no way to pass the switch mapping dictionary to CreateDefaultBuilder. Si les arguments incluent un commutateur mappé et sont passés à CreateDefaultBuilder, son fournisseur AddCommandLine ne parvient pas à s’initialiser avec un FormatException.If the arguments include a mapped switch and are passed to CreateDefaultBuilder, its AddCommandLine provider fails to initialize with a FormatException. La solution ne consiste pas à transmettre les arguments à CreateDefaultBuilder, mais plutôt à permettre à la méthode AddCommandLine de la méthode ConfigurationBuilder de traiter les arguments et le dictionnaire de mappage de commutateur.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.

public static void Main(string[] args)
{
    var switchMappings = new Dictionary<string, string>
        {
            { "-CLKey1", "CommandLineKey1" },
            { "-CLKey2", "CommandLineKey2" }
        };

    var config = new ConfigurationBuilder()
        .AddCommandLine(args, switchMappings)
        .Build();

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

    using (host)
    {
        Console.ReadLine();
    }
}

Une fois le dictionnaire de correspondances de commutateur créé, il contient les données affichées dans le tableau suivant.After the switch mappings dictionary is created, it contains the data shown in the following table.

ToucheKey ValueValue
-CLKey1 CommandLineKey1
-CLKey2 CommandLineKey2

Si les clés mappées au commutateur sont utilisées lors du démarrage de l’application, la configuration reçoit la valeur de configuration sur la clé fournie par le dictionnaire :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

Après avoir exécuté la commande précédente, la configuration contient les valeurs indiquées dans le tableau suivant.After running the preceding command, configuration contains the values shown in the following table.

ToucheKey ValueValue
CommandLineKey1 value1
CommandLineKey2 value2

Fournisseur de configuration de variables d’environnementEnvironment Variables Configuration Provider

EnvironmentVariablesConfigurationProvider charge la configuration à partir des paires clé-valeur de la variable d’environnement lors de l’exécution.The EnvironmentVariablesConfigurationProvider loads configuration from environment variable key-value pairs at runtime.

Pour activer la configuration des variables d’environnement, appelez la méthode d’extension AddEnvironmentVariables sur une instance de ConfigurationBuilder.To activate environment variables configuration, call the AddEnvironmentVariables extension method on an instance of ConfigurationBuilder.

Lors de l’utilisation de clés hiérarchiques dans les variables d’environnement, un séparateur sous forme de signe deux-points (:) peut ne pas fonctionner sur toutes les plateformes.When working with hierarchical keys in environment variables, a colon separator (:) may not work on all platforms. Un trait de soulignement double (__) est pris en charge par toutes les plateformes et remplacé par un signe deux-points.A double underscore (__) is supported by all platforms and is replaced by a colon.

Azure App Service vous permet de définir des variables d’environnement dans le portail Azure capables de remplacer la configuration d’application à l’aide du Fournisseur de configuration de variables d’environnement.Azure App Service permits you to set environment variables in the Azure Portal that can override app configuration using the Environment Variables Configuration Provider. Pour plus d’informations, consultez les applications Azure : Remplacer la configuration de l’application à l’aide du Portail Azure.For more information, see Azure Apps: Override app configuration using the Azure Portal.

AddEnvironmentVariables est appelé automatiquement pour les variables d’environnement précédées de ASPNETCORE_ à l’initialisation d’un nouveau WebHostBuilder.AddEnvironmentVariables is automatically called for environment variables prefixed with ASPNETCORE_ when you initialize a new WebHostBuilder. Pour plus d’informations, consultez l’hôte web : Configurer un hôte.For more information, see Web Host: Set up a host.

CreateDefaultBuilder charge également :CreateDefaultBuilder also loads:

  • Configuration de l’application à partir de variables d’environnement sans préfixe en appelant AddEnvironmentVariables sans préfixe.App configuration from unprefixed environment variables by calling AddEnvironmentVariables without a prefix.
  • Configuration facultative à partir d’appsettings.json et d’appsettings.{Environment}.json.Optional configuration from appsettings.json and appsettings.{Environment}.json.
  • Secrets utilisateur (Secret Manager) (dans l’environnement de développement).User secrets (Secret Manager) (in the Development environment).
  • Arguments de ligne de commandeCommand-line arguments.

Le fournisseur de configuration de variables d’environnement est appelé une fois que la configuration est établie à partir des secrets utilisateur et des fichiers appsettings.The Environment Variables Configuration Provider is called after configuration is established from user secrets and appsettings files. Le fait d’appeler le fournisseur ainsi permet de lire les variables d’environnement pendant l’exécution pour substituer la configuration définie par les secrets utilisateur et les fichiers appsettings.Calling the provider in this position allows the environment variables read at runtime to override configuration set by user secrets and appsettings files.

Appelez ConfigureAppConfiguration lors de la création de l’hôte pour spécifier la configuration de l’application.Call ConfigureAppConfiguration when building the host to specify the app's configuration.

Si vous devez fournir la configuration de l'application à partir de variables d'environnement supplémentaires, appelez les fournisseurs supplémentaires de l'application dans ConfigureAppConfiguration et appelez AddEnvironmentVariables avec le préfixe.If you need to provide app configuration from additional environment variables, call the app's additional providers in ConfigureAppConfiguration and call AddEnvironmentVariables with the prefix.

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

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

Lorsque vous créez un WebHostBuilder directement, appelez UseConfiguration avec la configuration :When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Appelez la méthode d’extension AddEnvironmentVariables sur une instance de ConfigurationBuilder.Call the AddEnvironmentVariables extension method on an instance of ConfigurationBuilder. Appliquez la configuration à WebHostBuilder avec la méthode UseConfiguration.Apply the configuration to WebHostBuilder with the UseConfiguration method.

Si vous devez fournir la configuration de l'application à partir de variables d'environnement supplémentaires, appelez les fournisseurs supplémentaires de l'application dans ConfigureAppConfiguration et appelez AddEnvironmentVariables avec le préfixe.If you need to provide app configuration from additional environment variables, call the app's additional providers in ConfigureAppConfiguration and call AddEnvironmentVariables with the prefix.

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            // Call additional providers here as needed.
            // Call AddEnvironmentVariables last if you need to allow environment
            // variables to override values from other providers.
            .AddEnvironmentVariables(prefix: "PREFIX_")
            .Build();

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

Lorsque vous créez un WebHostBuilder directement, appelez UseConfiguration avec la configuration :When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Appliquez la configuration à WebHostBuilder avec la méthode UseConfiguration :Apply the configuration to WebHostBuilder with the UseConfiguration method:

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

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

ExempleExample

L’exemple d’application 2.x tire parti de la méthode pratique statique CreateDefaultBuilder pour générer l’hôte, qui inclut un appel à AddEnvironmentVariables.The 2.x sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes a call to AddEnvironmentVariables.

L’exemple d’application 1.x appelle AddEnvironmentVariables sur un ConfigurationBuilder.The 1.x sample app calls AddEnvironmentVariables on a ConfigurationBuilder.

  1. Exécutez l’exemple d’application.Run the sample app. Ouvrez un navigateur vers l’application avec l’adresse http://localhost:5000.Open a browser to the app at http://localhost:5000.
  2. Notez que la sortie contient la paire clé-valeur pour la variable d’environnement ENVIRONMENT.Observe that the output contains the key-value pair for the environment variable ENVIRONMENT. La valeur reflète l’environnement dans lequel l’application est en cours d’exécution, en général Development lors de l’exécution locale.The value reflects the environment in which the app is running, typically Development when running locally.

Pour que la liste des variables d’environnement restituée par l’application soit courte, l’application filtre les variables d’environnement en fonction de celles qui commencent par :To keep the list of environment variables rendered by the app short, the app filters environment variables to those that start with the following:

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

Si vous souhaitez exposer toutes les variables d’environnement disponibles pour l’application, remplacez FilteredConfiguration dans Pages/Index.cshtml.cs par ce qui suit :If you wish to expose all of the environment variables available to the app, change the FilteredConfiguration in Pages/Index.cshtml.cs to the following:

Si vous souhaitez exposer toutes les variables d’environnement disponibles pour l’application, remplacez FilteredConfiguration dans Controllers/HomeController.cs par ce qui suit :If you wish to expose all of the environment variables available to the app, change the FilteredConfiguration in Controllers/HomeController.cs to the following:

FilteredConfiguration = _config.AsEnumerable();

PréfixesPrefixes

Les variables d’environnement chargées dans la configuration de l’application sont filtrées lorsque vous fournissez un préfixe pour la méthode AddEnvironmentVariables.Environment variables loaded into the app's configuration are filtered when you supply a prefix to the AddEnvironmentVariables method. Par exemple, pour filtrer les variables d’environnement sur le préfixe CUSTOM_, fournissez le préfixe au fournisseur de configuration :For example, to filter environment variables on the prefix CUSTOM_, supply the prefix to the configuration provider:

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

Le préfixe est supprimé lorsque les paires clé-valeur de la configuration sont créées.The prefix is stripped off when the configuration key-value pairs are created.

La méthode pratique statique CreateDefaultBuilder crée un WebHostBuilder pour établir l’hôte de l’application.The static convenience method CreateDefaultBuilder creates a WebHostBuilder to establish the app's host. Lorsque WebHostBuilder est créé, il trouve la configuration de son hôte dans les variables d’environnement avec le préfixe ASPNETCORE_.When WebHostBuilder is created, it finds its host configuration in environment variables prefixed with ASPNETCORE_.

Préfixes des chaînes de connexionConnection string prefixes

L’API Configuration possède des règles de traitement spéciales pour quatre variables d’environnement de chaîne de connexion impliquées dans la configuration des chaînes de connexion Azure pour l’environnement de l’application.The Configuration API has special processing rules for four connection string environment variables involved in configuring Azure connection strings for the app environment. Les variables d’environnement avec les préfixes indiqués dans le tableau sont chargées dans l’application si aucun préfixe n’est fourni à AddEnvironmentVariables.Environment variables with the prefixes shown in the table are loaded into the app if no prefix is supplied to AddEnvironmentVariables.

Préfixe de la chaîne de connexionConnection string prefix FournisseurProvider
CUSTOMCONNSTR_ Fournisseur personnaliséCustom provider
MYSQLCONNSTR_ MySQLMySQL
SQLAZURECONNSTR_ Azure SQL DatabaseAzure SQL Database
SQLCONNSTR_ SQL ServerSQL Server

Quand une variable d’environnement est découverte et chargée dans la configuration avec l’un des quatre préfixes indiqués dans le tableau :When an environment variable is discovered and loaded into configuration with any of the four prefixes shown in the table:

  • La clé de configuration est créée en supprimant le préfixe de la variable d’environnement et en ajoutant une section de clé de configuration (ConnectionStrings).The configuration key is created by removing the environment variable prefix and adding a configuration key section (ConnectionStrings).
  • Une nouvelle paire clé-valeur de configuration est créée qui représente le fournisseur de connexion de base de données (à l’exception de CUSTOMCONNSTR_, qui ne possède aucun fournisseur indiqué).A new configuration key-value pair is created that represents the database connection provider (except for CUSTOMCONNSTR_, which has no stated provider).
Clé de variable d’environnementEnvironment variable key Clé de configuration convertieConverted configuration key Entrée de configuration de fournisseurProvider configuration entry
CUSTOMCONNSTR_<KEY> ConnectionStrings:<KEY> Entrée de configuration non créée.Configuration entry not created.
MYSQLCONNSTR_<KEY> ConnectionStrings:<KEY> Clé : ConnectionStrings:<KEY>_ProviderName :Key: ConnectionStrings:<KEY>_ProviderName:
Valeur : MySql.Data.MySqlClientValue: MySql.Data.MySqlClient
SQLAZURECONNSTR_<KEY> ConnectionStrings:<KEY> Clé : ConnectionStrings:<KEY>_ProviderName :Key: ConnectionStrings:<KEY>_ProviderName:
Valeur : System.Data.SqlClientValue: System.Data.SqlClient
SQLCONNSTR_<KEY> ConnectionStrings:<KEY> Clé : ConnectionStrings:<KEY>_ProviderName :Key: ConnectionStrings:<KEY>_ProviderName:
Valeur : System.Data.SqlClientValue: System.Data.SqlClient

Fournisseur de configuration de fichierFile Configuration Provider

FileConfigurationProvider est la classe de base pour charger la configuration à partir du système de fichiers.FileConfigurationProvider is the base class for loading configuration from the file system. Les fournisseurs de configuration suivants sont dédiés à des types de fichiers spécifiques :The following configuration providers are dedicated to specific file types:

Fournisseur de configuration INIINI Configuration Provider

IniConfigurationProvider charge la configuration à partir des paires clé-valeur du fichier INI lors de l’exécution.The IniConfigurationProvider loads configuration from INI file key-value pairs at runtime.

Pour activer la configuration du fichier INI, appelez la méthode d’extension AddIniFile sur une instance de ConfigurationBuilder.To activate INI file configuration, call the AddIniFile extension method on an instance of ConfigurationBuilder.

Le signe deux-points peut servir de délimiteur de section dans la configuration d’un fichier INI.The colon can be used to as a section delimiter in INI file configuration.

Les surcharges permettent de spécifier :Overloads permit specifying:

  • Si le fichier est facultatif.Whether the file is optional.
  • Si la configuration est rechargée quand le fichier est modifié.Whether the configuration is reloaded if the file changes.
  • Le IFileProvider utilisé pour accéder au fichier.The IFileProvider used to access the file.

Appelez ConfigureAppConfiguration lors de la création de l’hôte pour spécifier la configuration de l’application :Call ConfigureAppConfiguration when building the host to specify the app's configuration:

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

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

Lorsque vous créez un WebHostBuilder directement, appelez UseConfiguration avec la configuration :When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Lors de l’appel de CreateDefaultBuilder, appelez UseConfiguration avec la configuration :When calling CreateDefaultBuilder, call UseConfiguration with the configuration:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddIniFile("config.ini", optional: true, reloadOnChange: true)
            .Build();

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

Lorsque vous créez un WebHostBuilder directement, appelez UseConfiguration avec la configuration :When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Appliquez la configuration à WebHostBuilder avec la méthode UseConfiguration :Apply the configuration to WebHostBuilder with the UseConfiguration method:

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

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

Exemple générique d’un fichier de configuration 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

Le fichier de configuration précédent charge les clés suivantes avec 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

Fournisseur de configuration JSONJSON Configuration Provider

JsonConfigurationProvider charge la configuration à partir des paires clé-valeur du fichier JSON lors de l’exécution.The JsonConfigurationProvider loads configuration from JSON file key-value pairs during runtime.

Pour activer la configuration du fichier JSON, appelez la méthode d’extension AddJsonFile sur une instance de ConfigurationBuilder.To activate JSON file configuration, call the AddJsonFile extension method on an instance of ConfigurationBuilder.

Les surcharges permettent de spécifier :Overloads permit specifying:

  • Si le fichier est facultatif.Whether the file is optional.
  • Si la configuration est rechargée quand le fichier est modifié.Whether the configuration is reloaded if the file changes.
  • Le IFileProvider utilisé pour accéder au fichier.The IFileProvider used to access the file.

AddJsonFile est appelé automatiquement deux fois lorsque vous initialisez un nouveau WebHostBuilder avec CreateDefaultBuilder.AddJsonFile is automatically called twice when you initialize a new WebHostBuilder with CreateDefaultBuilder. La méthode est appelée pour charger la configuration à partir de :The method is called to load configuration from:

  • appSettings.JSON – Ce fichier est lu en premier.appsettings.json – This file is read first. La version de l’environnement du fichier peut remplacer les valeurs fournies par le fichier appsettings.json.The environment version of the file can override the values provided by the appsettings.json file.
  • appsettings.{Environment}.json – La version de l’environnement du fichier est chargée à partir du fichier IHostingEnvironment.EnvironmentName.appsettings.{Environment}.json – The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName.

Pour plus d’informations, consultez l’hôte web : Configurer un hôte.For more information, see Web Host: Set up a host.

CreateDefaultBuilder charge également :CreateDefaultBuilder also loads:

Le Fournisseur de configuration JSON est établi en premier.The JSON Configuration Provider is established first. Par conséquent, les secrets utilisateur, les variables d’environnement et les arguments de ligne de commande remplacent la configuration définie par les fichiers appsettings.Therefore, user secrets, environment variables, and command-line arguments override configuration set by the appsettings files.

Appelez ConfigureAppConfiguration lors de la création de l’hôte pour spécifier la configuration de l’application pour les fichiers autres qu’appsettings.json et appsettings. {Environment} .json :Call ConfigureAppConfiguration when building the host to specify the app's configuration for files other than appsettings.json and appsettings.{Environment}.json:

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

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

Lorsque vous créez un WebHostBuilder directement, appelez UseConfiguration avec la configuration :When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Vous pouvez aussi appeler directement la méthode d’extension AddJsonFile sur une instance de ConfigurationBuilder.You can also directly call the AddJsonFile extension method on an instance of ConfigurationBuilder.

Lors de l’appel de CreateDefaultBuilder, appelez UseConfiguration avec la configuration :When calling CreateDefaultBuilder, call UseConfiguration with the configuration:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("config.json", optional: true, reloadOnChange: true)
            .Build();

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

Lorsque vous créez un WebHostBuilder directement, appelez UseConfiguration avec la configuration :When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Appliquez la configuration à WebHostBuilder avec la méthode UseConfiguration :Apply the configuration to WebHostBuilder with the UseConfiguration method:

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

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

ExempleExample

L’exemple d’application 2.x tire parti de la méthode pratique statique CreateDefaultBuilder pour générer l’hôte, qui inclut deux appels à AddJsonFile.The 2.x sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes two calls to AddJsonFile. La configuration est chargée à partir d’appsettings.json et d’appsettings{Environment}.json.Configuration is loaded from appsettings.json and appsettings.{Environment}.json.

L’exemple d’application 1.x appelle AddJsonFile deux fois sur un ConfigurationBuilder.The 1.x sample app calls AddJsonFile twice on a ConfigurationBuilder. La configuration est chargée à partir d’appsettings.json et d’appsettings{Environment}.json.Configuration is loaded from appsettings.json and appsettings.{Environment}.json.

  1. Exécutez l’exemple d’application.Run the sample app. Ouvrez un navigateur vers l’application avec l’adresse http://localhost:5000.Open a browser to the app at http://localhost:5000.
  2. Notez que la sortie contient des paires clé-valeur pour la configuration représentée dans le tableau en fonction de l’environnement.Observe that the output contains key-value pairs for the configuration shown in the table depending on the environment. Les clés de configuration de la journalisation utilisent le signe deux-points (:) comme séparateur hiérarchique.Logging configuration keys use the colon (:) as a hierarchical separator.
ToucheKey Valeur de développementDevelopment Value Valeur de productionProduction Value
Logging:LogLevel:SystemLogging:LogLevel:System InformationInformation InformationInformation
Logging:LogLevel:MicrosoftLogging:LogLevel:Microsoft InformationInformation InformationInformation
Logging:LogLevel:DefaultLogging:LogLevel:Default DébogageDebug ErrorError
AllowedHostsAllowedHosts * *

Fournisseur de configuration XMLXML Configuration Provider

XmlConfigurationProvider charge la configuration à partir des paires clé-valeur du fichier XML lors de l’exécution.The XmlConfigurationProvider loads configuration from XML file key-value pairs at runtime.

Pour activer la configuration du fichier XML, appelez la méthode d’extension AddXmlFile sur une instance de ConfigurationBuilder.To activate XML file configuration, call the AddXmlFile extension method on an instance of ConfigurationBuilder.

Les surcharges permettent de spécifier :Overloads permit specifying:

  • Si le fichier est facultatif.Whether the file is optional.
  • Si la configuration est rechargée quand le fichier est modifié.Whether the configuration is reloaded if the file changes.
  • Le IFileProvider utilisé pour accéder au fichier.The IFileProvider used to access the file.

Le nœud racine du fichier de configuration est ignoré lorsque les paires clé-valeur de la configuration sont créées.The root node of the configuration file is ignored when the configuration key-value pairs are created. Ne spécifiez pas une définition de type de document (DTD) ou un espace de noms dans le fichier.Don't specify a Document Type Definition (DTD) or namespace in the file.

Appelez ConfigureAppConfiguration lors de la création de l’hôte pour spécifier la configuration de l’application :Call ConfigureAppConfiguration when building the host to specify the app's configuration:

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

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

Lorsque vous créez un WebHostBuilder directement, appelez UseConfiguration avec la configuration :When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Lors de l’appel de CreateDefaultBuilder, appelez UseConfiguration avec la configuration :When calling CreateDefaultBuilder, call UseConfiguration with the configuration:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddXmlFile("config.xml", optional: true, reloadOnChange: true)
            .Build();

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

Lorsque vous créez un WebHostBuilder directement, appelez UseConfiguration avec la configuration :When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Appliquez la configuration à WebHostBuilder avec la méthode UseConfiguration :Apply the configuration to WebHostBuilder with the UseConfiguration method:

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

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

Les fichiers de configuration XML peuvent utiliser des noms d’éléments distincts pour les sections répétitives :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>

Le fichier de configuration précédent charge les clés suivantes avec value :The previous configuration file loads the following keys with value:

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

Les éléments répétitifs qui utilisent le même nom d’élément fonctionnent si l’attribut name est utilisé pour distinguer les éléments :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>

Le fichier de configuration précédent charge les clés suivantes avec 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

Les attributs peuvent être utilisés pour fournir des valeurs :Attributes can be used to supply values:

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

Le fichier de configuration précédent charge les clés suivantes avec value :The previous configuration file loads the following keys with value:

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

Fournisseur de configuration clé par fichierKey-per-file Configuration Provider

Le KeyPerFileConfigurationProvider utilise les fichiers d’un répertoire en tant que paires clé-valeur de configuration.The KeyPerFileConfigurationProvider uses a directory's files as configuration key-value pairs. La clé est le nom de fichier.The key is the file name. La valeur contient le contenu du fichier.The value contains the file's contents. Le Fournisseur de configuration Clé par fichier est utilisé dans les scénarios d’hébergement de Docker.The Key-per-file Configuration Provider is used in Docker hosting scenarios.

Pour activer la configuration clé par fichier, appelez la méthode d’extension AddKeyPerFile sur une instance de ConfigurationBuilder.To activate key-per-file configuration, call the AddKeyPerFile extension method on an instance of ConfigurationBuilder. Le directoryPath aux fichiers doit être un chemin d’accès absolu.The directoryPath to the files must be an absolute path.

Les surcharges permettent de spécifier :Overloads permit specifying:

  • Un délégué Action<KeyPerFileConfigurationSource> qui configure la source.An Action<KeyPerFileConfigurationSource> delegate that configures the source.
  • Si le répertoire est facultatif et le chemin d’accès au répertoire.Whether the directory is optional and the path to the directory.

Le double trait de soulignement (__) est utilisé comme un délimiteur de clé de configuration dans les noms de fichiers.The double-underscore (__) is used as a configuration key delimiter in file names. Par exemple, le nom de fichier Logging__LogLevel__System génère la clé de configuration Logging:LogLevel:System.For example, the file name Logging__LogLevel__System produces the configuration key Logging:LogLevel:System.

Appelez ConfigureAppConfiguration lors de la création de l’hôte pour spécifier la configuration de l’application :Call ConfigureAppConfiguration when building the host to specify the app's configuration:

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

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

Lorsque vous créez un WebHostBuilder directement, appelez UseConfiguration avec la configuration :When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

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

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

Fournisseur de configuration de mémoireMemory Configuration Provider

Le MemoryConfigurationProvider utilise une collection en mémoire en tant que paires clé-valeur de configuration.The MemoryConfigurationProvider uses an in-memory collection as configuration key-value pairs.

Pour activer la configuration de la collection en mémoire, appelez la méthode d’extension AddInMemoryCollection sur une instance de ConfigurationBuilder.To activate in-memory collection configuration, call the AddInMemoryCollection extension method on an instance of ConfigurationBuilder.

Le fournisseur de configuration peut être initialisé avec un IEnumerable<KeyValuePair<String,String>>.The configuration provider can be initialized with an IEnumerable<KeyValuePair<String,String>>.

Appelez ConfigureAppConfiguration lors de la création de l’hôte pour spécifier la configuration de l’application :Call ConfigureAppConfiguration when building the host to specify the app's configuration:

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

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

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

Lorsque vous créez un WebHostBuilder directement, appelez UseConfiguration avec la configuration :When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Lors de l’appel de CreateDefaultBuilder, appelez UseConfiguration avec la configuration :When calling CreateDefaultBuilder, call UseConfiguration with the configuration:

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

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

Lorsque vous créez un WebHostBuilder directement, appelez UseConfiguration avec la configuration :When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Appliquez la configuration à WebHostBuilder avec la méthode UseConfiguration :Apply the configuration to WebHostBuilder with the UseConfiguration method:

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

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

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

GetValueGetValue

ConfigurationBinder.GetValue<T> extrait une valeur à partir de la configuration avec une clé spécifiée et la convertit selon le type spécifié.ConfigurationBinder.GetValue<T> extracts a value from configuration with a specified key and converts it to the specified type. Une surcharge vous permet de fournir une valeur par défaut si la clé est introuvable.An overload permits you to provide a default value if the key isn't found.

L’exemple suivant extrait la valeur de la chaîne à partir de la configuration avec la clé NumberKey, tape la valeur en tant que int et stocke la valeur dans la variable intValue.The following example extracts the string value from configuration with the key NumberKey, types the value as an int, and stores the value in the variable intValue. Si NumberKey est introuvable dans les clés de configuration, intValue reçoit la valeur par défaut 99 :If NumberKey isn't found in the configuration keys, intValue receives the default value of 99:

var intValue = config.GetValue<int>("NumberKey", 99);

GetSection, GetChildren et ExistsGetSection, GetChildren, and Exists

Pour les exemples qui suivent, utilisez le fichier JSON suivant.For the examples that follow, consider the following JSON file. Quatre clés se trouvent dans deux sections, dont l’une inclut deux sous-sections :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"
    }
  }
}

Lorsque le fichier est lu dans la configuration, les clés hiérarchiques uniques suivantes sont créées pour stocker les valeurs de la configuration :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 extrait une sous-section de la configuration avec la clé de sous-section spécifiée.IConfiguration.GetSection extracts a configuration subsection with the specified subsection key.

Pour retourner un IConfigurationSection contenant uniquement les paires clé-valeur dans section1, appelez GetSection et fournissez le nom de section :To return an IConfigurationSection containing only the key-value pairs in section1, call GetSection and supply the section name:

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

De même, pour obtenir les valeurs des clés dans section2:subsection0, appelez GetSection et fournissez le chemin d’accès de la section :Similarly, to obtain the values for keys in section2:subsection0, call GetSection and supply the section path:

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

GetSection ne retourne jamais null.GetSection never returns null. Si aucune section correspondante n’est trouvée, une valeur IConfigurationSection vide est retournée.If a matching section isn't found, an empty IConfigurationSection is returned.

GetChildrenGetChildren

Un appel à IConfiguration.GetChildren sur section2 obtient un IEnumerable<IConfigurationSection> qui inclut :A call to IConfiguration.GetChildren on section2 obtains an IEnumerable<IConfigurationSection> that includes:

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

var children = configSection.GetChildren();

ExisteExists

Utilisez ConfigurationExtensions.Exists pour déterminer si une section de configuration existe :Use ConfigurationExtensions.Exists to determine if a configuration section exists:

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

Compte tenu des données d’exemple, sectionExists est false, car il n’y a pas de section section2:subsection2 dans les données de configuration.Given the example data, sectionExists is false because there isn't a section2:subsection2 section in the configuration data.

Lier à une classeBind to a class

La configuration peut être liée à des classes qui représentent des groupes de paramètres associés à l’aide du modèle d’options.Configuration can be bound to classes that represent groups of related settings using the options pattern. Pour plus d'informations, consultez Modèle d’options dans ASP.NET Core.For more information, see Modèle d’options dans ASP.NET Core.

Les valeurs de configuration sont retournées sous forme de chaînes, mais le fait d’appeler Bind permet la construction d’objets POCO.Configuration values are returned as strings, but calling Bind enables the construction of POCO objects.

L’exemple d’application contient un modèle Starship (Models/Starship.cs) :The sample app contains a Starship model (Models/Starship.cs):

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

La section starship du fichier starship.json crée la configuration lorsque l’exemple d’application utilise le Fournisseur de configuration JSON pour charger la configuration :The starship section of the starship.json file creates the configuration when the sample app uses the JSON Configuration Provider to load the configuration:

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

Les paires clé-valeur de configuration suivantes sont créées :The following configuration key-value pairs are created:

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

L’exemple d’application appelle GetSection avec la clé starship.The sample app calls GetSection with the starship key. Les paires clé-valeur starship sont isolées.The starship key-value pairs are isolated. La méthode Bind est appelée sur la sous-section passant une instance de la classe Starship.The Bind method is called on the subsection passing in an instance of the Starship class. Après avoir lié les valeurs d’instance, l’instance est affectée à une propriété pour le rendu :After binding the instance values, the instance is assigned to a property for rendering:

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

Établir une liaison à un graphe d’objetsBind to an object graph

Bind est capable de lier l’intégralité d’un graphe d’objets POCO.Bind is capable of binding an entire POCO object graph.

L’exemple contient un modèle TvShow dont le graphe d’objets inclut les classes Metadata et Actors (Models/TvShow.cs) :The sample contains a TvShow model whose object graph includes Metadata and Actors classes (Models/TvShow.cs):

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

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

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

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

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

L’exemple d’application a un fichier tvshow.xml contenant les données de configuration :The sample app has a tvshow.xml file containing the configuration data:

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

La configuration est liée à l’intégralité du graphe d’objets TvShow avec la méthode Bind.Configuration is bound to the entire TvShow object graph with the Bind method. L’instance liée est affectée à une propriété pour le rendu :The bound instance is assigned to a property for rendering:

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

ConfigurationBinder.Get<T> lie et retourne le type spécifié.ConfigurationBinder.Get<T> binds and returns the specified type. Il est plus pratique d’utiliser Get<T> que Bind.Get<T> is more convenient than using Bind. Le code suivant montre comment utiliser Get<T> avec l’exemple précédent, ce qui permet à l’instance liée d’être directement affectée à la propriété utilisée pour le rendu :The following code shows how to use Get<T> with the preceding example, which allows the bound instance to be directly assigned to the property used for rendering:

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

Lier un tableau à une classeBind an array to a class

L’exemple d’application illustre les concepts abordés dans cette section.The sample app demonstrates the concepts explained in this section.

Bind prend en charge la liaison de tableaux à des objets à l’aide d’index de tableau dans les clés de configuration.The Bind supports binding arrays to objects using array indices in configuration keys. Tout format de tableau qui expose un segment de clé numérique (:0:, :1:, … :{n}:) est capable d’effectuer la liaison de tableau avec un tableau de classes POCO.Any array format that exposes a numeric key segment (:0:, :1:, … :{n}:) is capable of array binding to a POCO class array.

Note

La liaison est fournie par convention.Binding is provided by convention. Les fournisseurs de configuration personnalisés ne sont pas obligés d’implémenter la liaison de tableau.Custom configuration providers aren't required to implement array binding.

Traitement de tableau en mémoireIn-memory array processing

Observez les valeurs et les clés de configuration indiquées dans le tableau suivant.Consider the configuration keys and values shown in the following table.

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

Ces clés et valeurs sont chargées dans l’exemple d’application à l’aide du Fournisseur de configuration de mémoire :These keys and values are loaded in the sample app using the Memory Configuration Provider:

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

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

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

        var builder = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddInMemoryCollection(arrayDict)
            .AddJsonFile("json_array.json", optional: false, reloadOnChange: false)
            .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
            .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, 
                reloadOnChange: true)
            .AddEnvironmentVariables()
            .AddJsonFile("starship.json", optional: false, reloadOnChange: false)
            .AddXmlFile("tvshow.xml", optional: false, reloadOnChange: false)
            .AddEFConfiguration(options => options.UseInMemoryDatabase("InMemoryDb"))
            .AddCommandLine(Program.Args);

        Configuration = builder.Build();
    }

Le tableau ignore une valeur pour l’index #3.The array skips a value for index #3. Le binder de configuration n’est pas capable de lier des valeurs null ou de créer des entrées null dans les objets liés, ce qui deviendra clair dans un moment lorsque le résultat de liaison de ce tableau à un objet est illustré.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.

Dans l’exemple d’application, une classe POCO est disponible pour contenir les données de configuration liées :In the sample app, a POCO class is available to hold the bound configuration data:

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

Les données de configuration sont liées à l’objet :The configuration data is bound to the object:

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

La syntaxe ConfigurationBinder.Get<T> peut également être utilisée, ce qui aboutit à un code plus compact :ConfigurationBinder.Get<T> syntax can also be used, which results in more compact code:

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

L’objet lié, une instance de ArrayExample, reçoit les données de tableau à partir de la configuration.The bound object, an instance of ArrayExample, receives the array data from configuration.

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

L’index #3 dans l’objet lié contient les données de configuration pour la clé de configuration array:4 et sa valeur de value4.Index #3 in the bound object holds the configuration data for the array:4 configuration key and its value of value4. Lorsque des données de configuration contenant un tableau sont liées, les index de tableau dans les clés de configuration sont simplement utilisés pour itérer les données de configuration lors de la création de l’objet.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. Une valeur null ne peut pas être conservée dans des données de configuration, et une entrée à valeur null n’est pas créée dans un objet lié quand un tableau dans des clés de configuration ignore un ou plusieurs index.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’élément de configuration manquant pour l’index #3 peut être fourni avant la liaison à l’instance ArrayExample par n’importe quel fournisseur de configuration qui génère la paire clé-valeur correcte dans la configuration.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. Si l’exemple inclut un Fournisseur de configuration JSON supplémentaire avec la paire clé-valeur manquante, ArrayExample.Entries correspond à l’intégralité du tableau de configuration :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"
}

Dans ConfigureAppConfiguration:In ConfigureAppConfiguration:

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

Dans le constructeur Startup :In the Startup constructor:

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

La paire clé-valeur indiquée dans le tableau est chargée dans la configuration.The key-value pair shown in the table is loaded into configuration.

ToucheKey ValueValue
array:entries:3array:entries:3 valeur3value3

Si l’instance de classe ArrayExample est liée une fois que le Fournisseur de configuration JSON inclut l’entrée pour l’index #3, le tableau ArrayExample.Entries inclut la valeur.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.

Index ArrayExample.EntriesArrayExample.Entries Index Valeur ArrayExample.EntriesArrayExample.Entries Value
00 value0value0
11 value1value1
22 value2value2
33 valeur3value3
44 value4value4
55 value5value5

Traitement de tableau JSONJSON array processing

Si un fichier JSON contient un tableau, les clés de configuration sont créés pour les éléments du tableau avec un index de section basé sur zéro.If a JSON file contains an array, configuration keys are created for the array elements with a zero-based section index. Dans le fichier de configuration suivant, subsection est un tableau :In the following configuration file, subsection is an array:

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

Le Fournisseur de configuration JSON lit les données de configuration dans les paires clé-valeur suivantes :The JSON Configuration Provider reads the configuration data into the following key-value pairs:

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

Dans l’exemple d’application, la classe POCO suivante est disponible pour lier les paires clé-valeur de configuration :In the sample app, the following POCO class is available to bind the configuration key-value pairs:

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

Après la liaison, JsonArrayExample.Key contient la valeur valueA.After binding, JsonArrayExample.Key holds the value valueA. Les valeurs de la sous-section sont stockées dans la propriété de tableau POCO, Subsection.The subsection values are stored in the POCO array property, Subsection.

Index JsonArrayExample.SubsectionJsonArrayExample.Subsection Index Valeur JsonArrayExample.SubsectionJsonArrayExample.Subsection Value
00 valueBvalueB
11 valueCvalueC
22 valueDvalueD

Fournisseur de configuration personnaliséCustom configuration provider

L’exemple d’application montre comment créer un fournisseur de configuration de base qui lit les paires clé-valeur de configuration à partir d’une base de données à l’aide d’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).

Le fournisseur présente les caractéristiques suivantes :The provider has the following characteristics:

  • La base de données en mémoire EF est utilisée à des fins de démonstration.The EF in-memory database is used for demonstration purposes. Pour utiliser une base de données qui nécessite une chaîne de connexion, implémentez un autre ConfigurationBuilder pour fournir la chaîne de connexion à partir d’un autre fournisseur de configuration.To use a database that requires a connection string, implement a secondary ConfigurationBuilder to supply the connection string from another configuration provider.
  • Le fournisseur lit une table de base de données dans la configuration au démarrage.The provider reads a database table into configuration at startup. Le fournisseur n’interroge pas la base de données par clé.The provider doesn't query the database on a per-key basis.
  • Le rechargement en cas de changement n’est pas implémenté, par conséquent, la mise à jour la base de données après le démarrage de l’application n’a aucun effet sur la configuration de l’application.Reload-on-change isn't implemented, so updating the database after the app starts has no effect on the app's configuration.

Définissez une entité EFConfigurationValue pour le stockage des valeurs de configuration dans la base de données.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; }
}
public class EFConfigurationValue
{
    public string Id { get; set; }
    public string Value { get; set; }
}

Ajoutez un EFConfigurationContext pour stocker les valeurs configurées et y accéder.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; }
}
public class EFConfigurationContext : DbContext
{
    public EFConfigurationContext(DbContextOptions options) : base(options)
    {
    }

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

Créez une classe qui implémente 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);
    }
}
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);
    }
}

Créez le fournisseur de configuration personnalisé en héritant de ConfigurationProvider.Create the custom configuration provider by inheriting from ConfigurationProvider. Le fournisseur de configuration initialise la base de données quand elle est vide.The configuration provider initializes the database when it's empty.

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

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

    Action<DbContextOptionsBuilder> OptionsAction { get; }

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

        OptionsAction(builder);

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

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

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

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

        dbContext.SaveChanges();

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

    Action<DbContextOptionsBuilder> OptionsAction { get; }

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

        OptionsAction(builder);

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

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

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

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

        dbContext.SaveChanges();

        return configValues;
    }
}

Une méthode d’extension AddEFConfiguration permet d’ajouter la source de configuration à 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));
    }
}
public static class EntityFrameworkExtensions
{
    public static IConfigurationBuilder AddEFConfiguration(
        this IConfigurationBuilder builder, 
        Action<DbContextOptionsBuilder> optionsAction)
    {
        return builder.Add(new EFConfigurationSource(optionsAction));
    }
}

Le code suivant montre comment utiliser le EFConfigurationProvider personnalisé dans Program.cs :The following code shows how to use the custom EFConfigurationProvider in Program.cs:

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

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

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

        var builder = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddInMemoryCollection(arrayDict)
            .AddJsonFile("json_array.json", optional: false, reloadOnChange: false)
            .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
            .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, 
                reloadOnChange: true)
            .AddEnvironmentVariables()
            .AddJsonFile("starship.json", optional: false, reloadOnChange: false)
            .AddXmlFile("tvshow.xml", optional: false, reloadOnChange: false)
            .AddEFConfiguration(options => options.UseInMemoryDatabase("InMemoryDb"))
            .AddCommandLine(Program.Args);

        Configuration = builder.Build();
    }

Accéder à la configuration lors du démarrageAccess configuration during startup

Injectez IConfiguration dans le constructeur Startup pour accéder aux valeurs de configuration dans Startup.ConfigureServices.Inject IConfiguration into the Startup constructor to access configuration values in Startup.ConfigureServices. Pour accéder à la configuration dans Startup.Configure, injectez IConfiguration directement dans la méthode ou utilisez l’instance à partir du constructeur :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"];
    }
}

Pour obtenir un exemple d’accès à la configuration à l’aide des méthodes pratiques de démarrage, consultez Démarrage de l’application : méthodes pratiques.For an example of accessing configuration using startup convenience methods, see App startup: Convenience methods.

Accéder à la configuration dans une page Razor Pages ou une vue MVCAccess configuration in a Razor Pages page or MVC view

Pour accéder aux paramètres de configuration dans une page Pages Razor ou une vue MVC, ajoutez une directive using (Informations de référence sur C# : directive using) pour l’espace de noms Microsoft.Extensions.Configuration et injectez IConfiguration dans la page ou la vue.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.

Dans une page Pages Razor :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>

Dans une vue 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>

Ajouter la configuration à partir d’un assembly externeAdd configuration from an external assembly

Une implémentation de IHostingStartup permet d’ajouter des améliorations à une application au démarrage à partir d’un assembly externe, en dehors de la classe Startup de l’application.An IHostingStartup implementation allows adding enhancements to an app at startup from an external assembly outside of the app's Startup class. Pour plus d'informations, consultez Utiliser des assemblys de démarrage d’hébergement dans ASP.NET Core.For more information, see Utiliser des assemblys de démarrage d’hébergement dans ASP.NET Core.

Ressources supplémentairesAdditional resources