Configuration dans ASP.NET CoreConfiguration in ASP.NET Core

Par Rick Anderson et Kirk LarkinBy Rick Anderson and Kirk Larkin

La configuration dans ASP.NET Core est effectuée à l’aide d’un ou de plusieurs fournisseurs de configuration.Configuration in ASP.NET Core is performed using one or more configuration providers. Les fournisseurs de configuration lisent les données de configuration des paires clé-valeur à l’aide d’une variété de sources de configuration :Configuration providers read configuration data from key-value pairs using a variety of configuration sources:

  • Les fichiers de paramètres, tels que appsettings.jsonSettings files, such as appsettings.json
  • Variables d'environnementEnvironment variables
  • Azure Key VaultAzure Key Vault
  • Azure App ConfigurationAzure App Configuration
  • Arguments de ligne de commandeCommand-line arguments
  • Fournisseurs personnalisés, installés ou créésCustom providers, installed or created
  • Fichiers de répertoireDirectory files
  • Objets .NET en mémoireIn-memory .NET objects

Cette rubrique fournit des informations sur la configuration dans ASP.NET Core.This topic provides information on configuration in ASP.NET Core. Pour plus d’informations sur l’utilisation de la configuration dans les applications console, consultez Configuration .net.For information on using configuration in console apps, see .NET Configuration.

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

Configuration par défautDefault configuration

ASP.NET Core les applications Web créées avec dotnet New ou Visual Studio génèrent le code suivant :ASP.NET Core web apps created with dotnet new or Visual Studio generate the following code:

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

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

CreateDefaultBuilder fournit la configuration par défaut de l’application dans l’ordre suivant :CreateDefaultBuilder provides default configuration for the app in the following order:

  1. ChainedConfigurationProvider : ajoute un existant IConfiguration en tant que source.ChainedConfigurationProvider : Adds an existing IConfiguration as a source. Dans le cas de configuration par défaut, ajoute la configuration d' hôte et la définit en tant que première source de la configuration de l' application .In the default configuration case, adds the host configuration and setting it as the first source for the app configuration.
  2. appsettings.json utilisation du fournisseur de configuration JSON.appsettings.json using the JSON configuration provider.
  3. appSettings. Environment . JSON à l’aide du fournisseur de configuration JSON.appsettings.Environment.json using the JSON configuration provider. Par exemple, appSettings. Production * * _._json et appSettings. * * * développement _.json *.For example, appsettings.***Production**._json* and appsettings.***Development** _._json*.
  4. Secrets d’application lorsque l’application s’exécute dans l' Development environnement.App secrets when the app runs in the Development environment.
  5. Variables d’environnement à l’aide du fournisseur de configuration des variables d’environnement.Environment variables using the Environment Variables configuration provider.
  6. Arguments de ligne de commande à l’aide du fournisseur de configuration de ligne de commande.Command-line arguments using the Command-line configuration provider.

Les fournisseurs de configuration ajoutés ultérieurement remplacent les paramètres de clé précédents.Configuration providers that are added later override previous key settings. Par exemple, si MyKey est défini à la fois dans appsettings.json et dans l’environnement, la valeur d’environnement est utilisée.For example, if MyKey is set in both appsettings.json and the environment, the environment value is used. À l’aide des fournisseurs de configuration par défaut, le fournisseur de configuration de ligne de commande remplace tous les autres fournisseurs.Using the default configuration providers, the Command-line configuration provider overrides all other providers.

Pour plus d’informations sur CreateDefaultBuilder , consultez paramètres par défaut du générateur.For more information on CreateDefaultBuilder, see Default builder settings.

Le code suivant affiche les fournisseurs de configuration activés dans l’ordre dans lequel ils ont été ajoutés :The following code displays the enabled configuration providers in the order they were added:

public class Index2Model : PageModel
{
    private IConfigurationRoot ConfigRoot;

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

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

        return Content(str);
    }
}

appsettings.json

Prenons le appsettings.json fichier suivant :Consider the following appsettings.json file:

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

Le code suivant de l' exemple de téléchargement affiche plusieurs des paramètres de configuration précédents :The following code from the sample download displays several of the preceding configurations settings:

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

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

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


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

La configuration par défaut JsonConfigurationProvider charge dans l’ordre suivant :The default JsonConfigurationProvider loads configuration in the following order:

  1. appsettings.json
  2. appSettings. Environment . JSON : par exemple, appSettings. Les fichiers de production * * _._json et appSettings. * * * Development _.json *.appsettings.Environment.json : For example, the appsettings.***Production**._json* and appsettings.***Development** _._json* files. La version de l’environnement du fichier est chargée à partir de IHostingEnvironment. EnvironmentName.The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName. Pour plus d’informations, consultez Utiliser plusieurs environnements dans ASP.NET Core.For more information, see Utiliser plusieurs environnements dans ASP.NET Core.

appSettings. Environment . les valeurs JSON remplacent les clés dans appsettings.json .appsettings.Environment.json values override keys in appsettings.json. Par exemple, par défaut :For example, by default:

  • Dans le développement, appSettings. *Development _._json * configuration remplace les valeurs trouvées dans appsettings.json .In development, appsettings.Development _._json configuration overwrites values found in appsettings.json.
  • En production, appSettings. *production _._json * configuration remplace les valeurs trouvées dans appsettings.json .In production, appsettings.Production _._json configuration overwrites values found in appsettings.json. Par exemple, lors du déploiement de l’application sur Azure.For example, when deploying the app to Azure.

Lier des données de configuration hiérarchiques à l’aide du modèle optionsBind hierarchical configuration data using the options pattern

La méthode recommandée pour lire les valeurs de configuration associées utilise le modèle d’options.The preferred way to read related configuration values is using the options pattern. Par exemple, pour lire les valeurs de configuration suivantes :For example, to read the following configuration values:

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

Créez la PositionOptions classe suivante :Create the following PositionOptions class:

public class PositionOptions
{
    public const string Position = "Position";

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

Une classe d’options :An options class:

  • Doit être non abstract avec un constructeur sans paramètre public.Must be non-abstract with a public parameterless constructor.
  • Toutes les propriétés publiques en lecture/écriture du type sont liées.All public read-write properties of the type are bound.
  • Les champs ne sont pas liés.Fields are not bound. Dans le code précédent, Position n’est pas lié.In the preceding code, Position is not bound. La Position propriété est utilisée afin que la chaîne "Position" ne doive pas être codée en dur dans l’application lors de la liaison de la classe à un fournisseur de configuration.The Position property is used so the string "Position" doesn't need to be hard coded in the app when binding the class to a configuration provider.

Le code suivant :The following code:

  • Appelle ConfigurationBinder. bind pour lier la PositionOptions classe à la Position section.Calls ConfigurationBinder.Bind to bind the PositionOptions class to the Position section.
  • Affiche les Position données de configuration.Displays the Position configuration data.
public class Test22Model : PageModel
{
    private readonly IConfiguration Configuration;

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

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

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

Dans le code précédent, par défaut, les modifications apportées au fichier de configuration JSON après le démarrage de l’application sont lues.In the preceding code, by default, changes to the JSON configuration file after the app has started are read.

ConfigurationBinder.Get<T> lie et retourne le type spécifié.ConfigurationBinder.Get<T> binds and returns the specified type. ConfigurationBinder.Get<T> peut être plus pratique que l’utilisation de ConfigurationBinder.Bind .ConfigurationBinder.Get<T> may be more convenient than using ConfigurationBinder.Bind. Le code suivant montre comment utiliser ConfigurationBinder.Get<T> avec la PositionOptions classe :The following code shows how to use ConfigurationBinder.Get<T> with the PositionOptions class:

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

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

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

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

Dans le code précédent, par défaut, les modifications apportées au fichier de configuration JSON après le démarrage de l’application sont lues.In the preceding code, by default, changes to the JSON configuration file after the app has started are read.

Une autre approche qui consiste à utiliser le modèle d’options* consiste à lier la Position section et à l’ajouter au conteneur du service d’injection de dépendances.An alternative approach when using the *options pattern _ is to bind the Position section and add it to the dependency injection service container. Dans le code suivant, PositionOptions est ajouté au conteneur de services avec <xref:Microsoft.Extensions.DependencyInjection.OptionsConfigurationServiceCollectionExtensions.Configure_> et lié à la configuration :In the following code, PositionOptions is added to the service container with <xref:Microsoft.Extensions.DependencyInjection.OptionsConfigurationServiceCollectionExtensions.Configure_> and bound to configuration:

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

À l’aide du code précédent, le code suivant lit les options de position :Using the preceding code, the following code reads the position options:

public class Test2Model : PageModel
{
    private readonly PositionOptions _options;

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

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

Dans le code précédent, les modifications apportées au fichier de configuration JSON après le démarrage de l’application ne sont pas lues.In the preceding code, changes to the JSON configuration file after the app has started are not read. Pour lire les modifications une fois l’application démarrée, utilisez IOptionsSnapshot.To read changes after the app has started, use IOptionsSnapshot.

À l’aide de la configuration par défaut , de appsettings.json et de appSettings. Environment les fichiers . JSON sont activés avec reloadOnChange : true.Using the default configuration, the appsettings.json and appsettings.Environment.json files are enabled with reloadOnChange: true. Modifications apportées appsettings.json aux appSettings et. Environment le fichier . JSON après le démarrage de l’application est lu par le fournisseur de configuration JSON.Changes made to the appsettings.json and appsettings.Environment.json file after the app starts are read by the JSON configuration provider.

Pour plus d’informations sur l’ajout de fichiers de configuration JSON supplémentaires, consultez fournisseur de configuration JSON dans ce document.See JSON configuration provider in this document for information on adding additional JSON configuration files.

Combinaison de la collection de servicesCombining service collection

Considérez la ConfigureServices méthode suivante, qui inscrit les services et configure les options :Consider the following ConfigureServices method, which registers services and configures options:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<PositionOptions>(
        Configuration.GetSection(PositionOptions.Position));
    services.Configure<ColorOptions>(
        Configuration.GetSection(ColorOptions.Color));

    services.AddScoped<IMyDependency, MyDependency>();
    services.AddScoped<IMyDependency2, MyDependency2>();

    services.AddRazorPages();
}

Les groupes d’inscriptions associés peuvent être déplacés vers une méthode d’extension pour inscrire les services.Related groups of registrations can be moved to an extension method to register services. Par exemple, les services de configuration sont ajoutés à la classe suivante :For example, the configuration services are added to the following class:

using ConfigSample.Options;
using Microsoft.Extensions.Configuration;

namespace Microsoft.Extensions.DependencyInjection
{
    public static class MyConfigServiceCollectionExtensions
    {
        public static IServiceCollection AddConfig(
             this IServiceCollection services, IConfiguration config)
        {
            services.Configure<PositionOptions>(
                config.GetSection(PositionOptions.Position));
            services.Configure<ColorOptions>(
                config.GetSection(ColorOptions.Color));

            return services;
        }
    }
}

Les services restants sont inscrits dans une classe similaire.The remaining services are registered in a similar class. La ConfigureServices méthode suivante utilise les nouvelles méthodes d’extension pour inscrire les services :The following ConfigureServices method uses the new extension methods to register the services:

public void ConfigureServices(IServiceCollection services)
{
    services.AddConfig(Configuration)
            .AddMyDependencyGroup();

    services.AddRazorPages();
}

Remarque : Chaque services.Add{GROUP_NAME} méthode d’extension ajoute et configure éventuellement des services.Note: Each services.Add{GROUP_NAME} extension method adds and potentially configures services. Par exemple, AddControllersWithViews ajoute les services MVC dont les vues ont besoin et AddRazorPages ajoute les pages de services Razor requis.For example, AddControllersWithViews adds the services MVC controllers with views require, and AddRazorPages adds the services Razor Pages requires. Nous vous recommandons d’appliquer cette Convention d’affectation de noms aux applications.We recommended that apps follow this naming convention. Placez les méthodes d’extension dans l’espace de noms Microsoft.Extensions.DependencyInjection pour encapsuler des groupes d’inscriptions de service.Place extension methods in the Microsoft.Extensions.DependencyInjection namespace to encapsulate groups of service registrations.

Sécurité et secrets de l’utilisateurSecurity and user secrets

Instructions relatives aux données de configuration :Configuration data guidelines:

  • 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. L’outil Gestionnaire de secret peut être utilisé pour stocker les secrets en développement.The Secret Manager tool can be used to store secrets in development.
  • 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.

Par défaut, la source de configuration des secrets de l’utilisateur est inscrite après les sources de configuration JSON.By default, the user secrets configuration source is registered after the JSON configuration sources. Par conséquent, les clés de secrets d’utilisateur sont prioritaires sur les clés dans appsettings.json et appSettings. Environment . JSON.Therefore, user secrets keys take precedence over keys in appsettings.json and appsettings.Environment.json.

Pour plus d’informations sur le stockage des mots de passe ou d’autres données sensibles :For more information on storing passwords or other sensitive data:

Azure Key Vault stocke en toute sécurité des secrets d’application pour les applications ASP.NET Core.Azure Key Vault safely stores app secrets for ASP.NET Core apps. 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.

Variables d'environnementEnvironment variables

À l’aide de la configuration par défaut , le EnvironmentVariablesConfigurationProvider charge la configuration à partir des paires clé-valeur de variable d’environnement après la lecture appsettings.json , appSettings. Environment . JSON et les secretsde l’utilisateur.Using the default configuration, the EnvironmentVariablesConfigurationProvider loads configuration from environment variable key-value pairs after reading appsettings.json, appsettings.Environment.json, and user secrets. Par conséquent, les valeurs de clés lues à partir de l’environnement remplacent les valeurs lues à partir de appsettings.json appSettings. Environment . JSON et les secrets de l’utilisateur.Therefore, key values read from the environment override values read from appsettings.json, appsettings.Environment.json, and user secrets.

Le : séparateur ne fonctionne pas avec les clés hiérarchiques de variable d’environnement sur toutes les plateformes.The : separator doesn't work with environment variable hierarchical keys on all platforms. __, le double trait de soulignement, est :__, the double underscore, is:

  • Pris en charge par toutes les plateformes.Supported by all platforms. Par exemple, le : séparateur n’est pas pris en charge par bash, mais __ est.For example, the : separator is not supported by Bash, but __ is.
  • Automatiquement remplacé par un :Automatically replaced by a :

Les set commandes suivantes :The following set commands:

  • Définissez les clés et les valeurs d’environnement de l' exemple précédent sur Windows.Set the environment keys and values of the preceding example on Windows.
  • Testez les paramètres lors de l’utilisation de l' exemple de téléchargement.Test the settings when using the sample download. La dotnet run commande doit être exécutée dans le répertoire du projet.The dotnet run command must be run in the project directory.
set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run

Paramètres d’environnement précédents :The preceding environment settings:

  • Sont uniquement définies dans les processus lancés à partir de la fenêtre de commande dans laquelle ils ont été définis.Are only set in processes launched from the command window they were set in.
  • Ne seront pas lues par les navigateurs lancés avec Visual Studio.Won't be read by browsers launched with Visual Studio.

Les commandes setx suivantes peuvent être utilisées pour définir les clés et les valeurs d’environnement sur Windows.The following setx commands can be used to set the environment keys and values on Windows. Contrairement à set , setx les paramètres sont conservés.Unlike set, setx settings are persisted. /M définit la variable dans l’environnement système./M sets the variable in the system environment. Si le /M commutateur n’est pas utilisé, une variable d’environnement utilisateur est définie.If the /M switch isn't used, a user environment variable is set.

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

Pour vérifier que les commandes précédentes remplacent appsettings.json et appSettings. Environment . JSON:To test that the preceding commands override appsettings.json and appsettings.Environment.json:

  • Avec Visual Studio : quittez et redémarrez Visual Studio.With Visual Studio: Exit and restart Visual Studio.
  • Avec l’interface CLI : démarrez une nouvelle fenêtre de commande et entrez dotnet run .With the CLI: Start a new command window and enter dotnet run.

Appelez AddEnvironmentVariables avec une chaîne pour spécifier un préfixe pour les variables d’environnement :Call AddEnvironmentVariables with a string to specify a prefix for environment variables:

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

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

Dans le code précédent :In the preceding code:

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

Les commandes suivantes testent le préfixe personnalisé :The following commands test the custom prefix:

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

La configuration par défaut charge les variables d’environnement et les arguments de ligne de commande préfixé avec DOTNET_ et ASPNETCORE_ .The default configuration loads environment variables and command line arguments prefixed with DOTNET_ and ASPNETCORE_. Les DOTNET_ ASPNETCORE_ préfixes et sont utilisés par ASP.net Core pour la configuration de l' hôte etde l’application, mais pas pour la configuration de l’utilisateur.The DOTNET_ and ASPNETCORE_ prefixes are used by ASP.NET Core for host and app configuration, but not for user configuration. Pour plus d’informations sur la configuration de l’hôte et de l’application, consultez hôte générique .net.For more information on host and app configuration, see .NET Generic Host.

Dans Azure App service, sélectionnez nouveau paramètre d’application dans la page paramètres > configuration .On Azure App Service, select New application setting on the Settings > Configuration page. Azure App Service paramètres de l’application sont les suivants :Azure App Service application settings are:

  • Chiffré au repos et transmis sur un canal chiffré.Encrypted at rest and transmitted over an encrypted channel.
  • Exposés en tant que variables d’environnement.Exposed as environment variables.

Pour plus d’informations, consultez Azure Apps : remplacer la configuration de l’application à l’aide du portail Azure.For more information, see Azure Apps: Override app configuration using the Azure Portal.

Consultez préfixes de chaîne de connexion pour plus d’informations sur les chaînes de connexion de base de données Azure.See Connection string prefixes for information on Azure database connection strings.

Affectation des noms de variables d’environnementNaming of environment variables

Les noms des variables d’environnement reflètent la structure d’un appsettings.json fichier.Environment variable names reflect the structure of an appsettings.json file. Chaque élément de la hiérarchie est séparé par un trait de soulignement double (préférable) ou par deux-points.Each element in the hierarchy is separated by a double underscore (preferable) or a colon. Lorsque la structure de l’élément comprend un tableau, l’index du tableau doit être traité comme un nom d’élément supplémentaire dans ce chemin d’accès.When the element structure includes an array, the array index should be treated as an additional element name in this path. Considérez le appsettings.json fichier suivant et ses valeurs équivalentes représentées sous la forme de variables d’environnement.Consider the following appsettings.json file and its equivalent values represented as environment variables.

appsettings.json

{
    "SmtpServer": "smtp.example.com",
    "Logging": [
        {
            "Name": "ToEmail",
            "Level": "Critical",
            "Args": {
                "FromAddress": "MySystem@example.com",
                "ToAddress": "SRE@example.com"
            }
        },
        {
            "Name": "ToConsole",
            "Level": "Information"
        }
    ]
}

variables d’environnementenvironment variables

setx SmtpServer=smtp.example.com
setx Logging__0__Name=ToEmail
setx Logging__0__Level=Critical
setx Logging__0__Args__FromAddress=MySystem@example.com
setx Logging__0__Args__ToAddress=SRE@example.com
setx Logging__1__Name=ToConsole
setx Logging__1__Level=Information

Variables d’environnement définies dans les launchSettings.jsgénérées surEnvironment variables set in generated launchSettings.json

Les variables d’environnement définies dans launchSettings.jslors de la substitution de celles définies dans l’environnement système.Environment variables set in launchSettings.json override those set in the system environment. Par exemple, les modèles Web ASP.NET Core génèrent un launchSettings.jssur un fichier qui définit la configuration du point de terminaison sur :For example, the ASP.NET Core web templates generate a launchSettings.json file that sets the endpoint configuration to:

"applicationUrl": "https://localhost:5001;http://localhost:5000"

La configuration de applicationUrl définit la ASPNETCORE_URLS variable d’environnement et remplace les valeurs définies dans l’environnement.Configuring the applicationUrl sets the ASPNETCORE_URLS environment variable and overrides values set in the environment.

Variables d’environnement d’échappement sur LinuxEscape environment variables on Linux

Sur Linux, la valeur des variables d’environnement URL doit être placée dans une séquence d’échappement pour systemd pouvoir être analysée.On Linux, the value of URL environment variables must be escaped so systemd can parse it. Utiliser l’outil Linux systemd-escape qui génère http:--localhost:5001Use the linux tool systemd-escape which yields http:--localhost:5001

groot@terminus:~$ systemd-escape http://localhost:5001
http:--localhost:5001

Afficher les variables d’environnementDisplay environment variables

Le code suivant affiche les variables d’environnement et les valeurs au démarrage de l’application, ce qui peut être utile lors du débogage des paramètres d’environnement :The following code displays the environment variables and values on application startup, which can be helpful when debugging environment settings:

public static void Main(string[] args)
{
    var host = CreateHostBuilder(args).Build();

    var config = host.Services.GetRequiredService<IConfiguration>();

    foreach (var c in config.AsEnumerable())
    {
        Console.WriteLine(c.Key + " = " + c.Value);
    }
    host.Run();
}

Ligne de commandeCommand-line

À l’aide de la configuration par défaut , le CommandLineConfigurationProvider charge la configuration à partir de paires clé-valeur d’argument de ligne de commande après les sources de configuration suivantes :Using the default configuration, the CommandLineConfigurationProvider loads configuration from command-line argument key-value pairs after the following configuration sources:

  • appsettings.json et appSettings. Environment . fichiers JSON .appsettings.json and appsettings.Environment.json files.
  • Secrets de l’application dans l’environnement de développement.App secrets in the Development environment.
  • Variables d'environnement.Environment variables.

Par défaut, les valeurs de configuration définies sur la ligne de commande remplacent les valeurs de configuration définies avec tous les autres fournisseurs de configuration.By default, configuration values set on the command-line override configuration values set with all the other configuration providers.

Arguments de ligne de commandeCommand-line arguments

La commande suivante définit des clés et des valeurs à l’aide de = :The following command sets keys and values using =:

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

La commande suivante définit des clés et des valeurs à l’aide de / :The following command sets keys and values using /:

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

La commande suivante définit des clés et des valeurs à l’aide de -- :The following command sets keys and values using --:

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

Valeur de la clé :The key value:

  • Doit suivre = ou la clé doit avoir un préfixe -- ou / lorsque la valeur suit un espace.Must follow =, or the key must have a prefix of -- or / when the value follows a space.
  • N’est pas obligatoire si = est utilisé.Isn't required if = is used. Par exemple : MySetting=.For example, MySetting=.

Dans la même commande, ne mélangez pas les paires clé-valeur d’argument de ligne de commande qui utilisent = des paires clé-valeur utilisant un espace.Within the same command, don't mix command-line argument key-value pairs that use = with key-value pairs that use a space.

Correspondances de commutateurSwitch mappings

Les mappages de commutateur autorisent la logique de remplacement de nom de clé .Switch mappings allow key name replacement logic. Fournissez un dictionnaire de remplacements de commutateur dans la AddCommandLine méthode.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 est retourné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 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 - ou -- .Switches must start with - or --.
  • Le dictionnaire de correspondances de commutateur ne doit pas contenir de clés en double.The switch mappings dictionary must not contain duplicate keys.

Pour utiliser un dictionnaire de mappages de commutateur, transmettez-le à l’appel à AddCommandLine :To use a switch mappings dictionary, pass it into the call to AddCommandLine:

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

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

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

Le code suivant montre les valeurs de clé pour les clés remplacées :The following code shows the key values for the replaced keys:

public class Test3Model : PageModel
{
    private readonly IConfiguration Config;

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

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

La commande suivante fonctionne pour tester le remplacement de la clé :The following command works to test key replacement:

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

Pour les applications qui utilisent des mappages de commutateurs, l’appel à CreateDefaultBuilder ne doit pas passer d’arguments.For apps that use switch mappings, the call to CreateDefaultBuilder shouldn't pass arguments. L' CreateDefaultBuilder appel de la méthode AddCommandLine n’inclut pas de commutateurs mappés, et il n’existe aucun moyen de passer le dictionnaire de mappage de commutateur à CreateDefaultBuilder .The CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and there's no way to pass the switch-mapping dictionary to CreateDefaultBuilder. La solution ne consiste pas à passer les arguments à CreateDefaultBuilder , mais à autoriser la méthode de la ConfigurationBuilder méthode AddCommandLine à traiter à la fois 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.

Données de configuration hiérarchiquesHierarchical configuration data

L’API de configuration lit les données de configuration hiérarchiques en aplatit les données hiérarchiques à l’aide d’un délimiteur dans les clés de configuration.The Configuration API reads hierarchical configuration data by flattening the hierarchical data with the use of a delimiter in the configuration keys.

L' exemple de téléchargement contient le appsettings.json fichier suivant :The sample download contains the following appsettings.json file:

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

Le code suivant de l' exemple de téléchargement affiche plusieurs des paramètres de configuration :The following code from the sample download displays several of the configurations settings:

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

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

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


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

La meilleure façon de lire des données de configuration hiérarchiques consiste à utiliser le modèle d’options.The preferred way to read hierarchical configuration data is using the options pattern. Pour plus d’informations, consultez lier des données de configuration hiérarchiques dans ce document.For more information, see Bind hierarchical configuration data in this document.

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.

Clés et valeurs de configurationConfiguration keys and values

Clés de configuration :Configuration keys:

  • Ne respectent pas la casse.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 clé et une valeur sont définies dans plusieurs fournisseurs de configuration, la valeur du dernier fournisseur ajouté est utilisée.If a key and value is set in more than one configuration providers, the value from the last provider added is used. Pour plus d’informations, consultez configuration par défaut.For more information, see Default configuration.
  • 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 est automatiquement converti en deux-points : .A double underscore, __, is supported by all platforms and is automatically converted into a colon :.
    • Dans Azure Key Vault, les clés hiérarchiques utilisent -- comme séparateur.In Azure Key Vault, hierarchical keys use -- as a separator. Le fournisseur de configuration Azure Key Vault remplace automatiquement -- par un : lorsque les secrets sont chargés dans la configuration de l’application.The Azure Key Vault configuration provider automatically replaces -- with a : 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.

Valeurs de configuration :Configuration values:

  • Sont des chaînes.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.

Fournisseurs de configurationConfiguration providers

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 deProvides configuration from
Fournisseur de configuration Azure Key VaultAzure Key Vault configuration provider Azure Key VaultAzure Key Vault
Fournisseur de configuration Azure AppAzure App configuration provider Azure App ConfigurationAzure App Configuration
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 des variables d’environnementEnvironment Variables configuration provider Variables d'environnementEnvironment variables
Fournisseur de configuration de fichierFile configuration provider Fichiers INI, JSON et XMLINI, JSON, and XML files
Fournisseur de configuration de clé par fichierKey-per-file configuration provider Fichiers de répertoireDirectory files
Fournisseur de configuration de la mémoireMemory configuration provider Collections en mémoireIn-memory collections
Secrets utilisateurUser secrets Fichier dans le répertoire de profil utilisateurFile in the user profile directory

Les sources de configuration sont lues dans l’ordre dans lequel leurs fournisseurs de configuration sont spécifiés.Configuration sources are read in the order that their configuration providers are specified. Commandez des fournisseurs de configuration dans le code pour répondre aux priorités des sources de configuration sous-jacentes requises par l’application.Order configuration providers in code to suit the priorities for the underlying configuration sources that the app requires.

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

  1. appsettings.json
  2. appSettings. Environment . JSONappsettings.Environment.json
  3. Secrets utilisateurUser secrets
  4. Variables d’environnement à l’aide du fournisseur de configuration des variables d’environnement.Environment variables using the Environment Variables configuration provider.
  5. Arguments de ligne de commande à l’aide du fournisseur de configuration de ligne de commande.Command-line arguments using the Command-line configuration provider.

Une pratique courante consiste à ajouter le dernier fournisseur de configuration de ligne de commande dans une série de fournisseurs pour permettre aux arguments de ligne de commande de remplacer la configuration définie par les autres fournisseurs.A common practice is to add the Command-line configuration provider last in a series of providers to allow command-line arguments to override configuration set by the other providers.

La séquence de fournisseurs précédente est utilisée dans la configuration par défaut.The preceding sequence of providers is used in the default configuration.

Préfixes des chaînes de connexionConnection string prefixes

L’API de configuration a des règles de traitement spéciales pour quatre variables d’environnement de chaîne de connexion.The Configuration API has special processing rules for four connection string environment variables. Ces chaînes de connexion sont impliquées dans la configuration des chaînes de connexion Azure pour l’environnement de l’application.These connection strings are 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 avec la configuration par défaut ou lorsqu’aucun préfixe n’est fourni à AddEnvironmentVariables .Environment variables with the prefixes shown in the table are loaded into the app with the default configuration or when no prefix is supplied to AddEnvironmentVariables.

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 dérivent de FileConfigurationProvider :The following configuration providers derive from FileConfigurationProvider:

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.

Le code suivant efface tous les fournisseurs de configuration et ajoute plusieurs fournisseurs de configuration :The following code clears all the configuration providers and adds several configuration providers:

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

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

                var env = hostingContext.HostingEnvironment;

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

                config.AddEnvironmentVariables();

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

Dans le code précédent, les paramètres des MyIniConfig.ini et MyIniConfig. Environment les fichiers ini sont remplacés par les paramètres dans le :In the preceding code, settings in the MyIniConfig.ini and MyIniConfig.Environment.ini files are overridden by settings in the:

L' exemple de téléchargement contient le fichier MyIniConfig.ini suivant :The sample download contains the following MyIniConfig.ini file:

MyKey="MyIniConfig.ini Value"

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

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Le code suivant de l' exemple de téléchargement affiche plusieurs des paramètres de configuration précédents :The following code from the sample download displays several of the preceding configurations settings:

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

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

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


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

Fournisseur de configuration JSONJSON configuration provider

Le JsonConfigurationProvider charge la configuration à partir de paires clé-valeur de fichier JSON.The JsonConfigurationProvider loads configuration from JSON file key-value pairs.

Les surcharges peuvent spécifier :Overloads can specify:

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

Considérez le code suivant :Consider the following code:

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

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

Le code précédent :The preceding code:

En général, vous ne souhaitez pas qu’une valeur de substitution de fichier JSON personnalisée soit définie dans le fournisseur de configuration des variables d’environnement et dans le fournisseur de configuration de ligne de commande.You typically don't want a custom JSON file overriding values set in the Environment variables configuration provider and the Command-line configuration provider.

Le code suivant efface tous les fournisseurs de configuration et ajoute plusieurs fournisseurs de configuration :The following code clears all the configuration providers and adds several configuration providers:

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

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

                var env = hostingContext.HostingEnvironment;

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

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

                config.AddEnvironmentVariables();

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

Dans le code précédent, les paramètres de la MyConfig.jssur et MyConfig. Environment . fichiers JSON :In the preceding code, settings in the MyConfig.json and MyConfig.Environment.json files:

L' exemple de téléchargement contient les MyConfig.jssuivantes sur le fichier :The sample download contains the following MyConfig.json file:

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

Le code suivant de l' exemple de téléchargement affiche plusieurs des paramètres de configuration précédents :The following code from the sample download displays several of the preceding configurations settings:

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

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

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


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

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.

Le code suivant efface tous les fournisseurs de configuration et ajoute plusieurs fournisseurs de configuration :The following code clears all the configuration providers and adds several configuration providers:

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

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

                var env = hostingContext.HostingEnvironment;

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

                config.AddEnvironmentVariables();

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

Dans le code précédent, les paramètres des MyXMLFile.xml et MyXMLFile. Environment les fichiers XML sont remplacés par les paramètres dans le :In the preceding code, settings in the MyXMLFile.xml and MyXMLFile.Environment.xml files are overridden by settings in the:

L' exemple de téléchargement contient le fichier MyXMLFile.xml suivant :The sample download contains the following MyXMLFile.xml file:

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

Le code suivant de l' exemple de téléchargement affiche plusieurs des paramètres de configuration précédents :The following code from the sample download displays several of the preceding configurations settings:

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

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

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


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

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

Le code suivant lit le fichier de configuration précédent et affiche les clés et les valeurs :The following code reads the previous configuration file and displays the keys and values:

public class IndexModel : PageModel
{
    private readonly IConfiguration Configuration;

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

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

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

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

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 de 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 par fichier clé est utilisé dans les scénarios d’hébergement de l’ancrage.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:

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

Fournisseur de configuration de la 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.

Le code suivant ajoute une collection de mémoire au système de configuration :The following code adds a memory collection to the configuration system:

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

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

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

Le code suivant de l' exemple de téléchargement affiche les paramètres de configuration précédents :The following code from the sample download displays the preceding configurations settings:

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

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

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


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

Dans le code précédent, config.AddInMemoryCollection(Dict) est ajouté après les fournisseurs de configuration par défaut.In the preceding code, config.AddInMemoryCollection(Dict) is added after the default configuration providers. Pour obtenir un exemple de classement des fournisseurs de configuration, consultez fournisseur de configuration JSON.For an example of ordering the configuration providers, see JSON configuration provider.

Pour un autre exemple, consultez lier un tableau à l’aide de MemoryConfigurationProvider .See Bind an array for another example using MemoryConfigurationProvider.

Configuration de point de terminaison KestrelKestrel endpoint configuration

La configuration de point de terminaison spécifique à Kestrel remplace toutes les configurations de point de terminaison inter-serveurs .Kestrel specific endpoint configuration overrides all cross-server endpoint configurations. Les configurations de point de terminaison entre serveurs sont les suivantes :Cross-server endpoint configurations include:

Considérez le appsettings.json fichier suivant utilisé dans une application web ASP.net Core :Consider the following appsettings.json file used in an ASP.NET Core web app:

{
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://localhost:9999"
      }
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
} 

Lorsque le balisage en surbrillance précédent est utilisé dans une application Web ASP.NET Core et que l’application est lancée sur la ligne de commande avec la configuration de point de terminaison inter-serveurs suivante :When the preceding highlighted markup is used in an ASP.NET Core web app and the app is launched on the command line with the following cross-server endpoint configuration:

dotnet run --urls="https://localhost:7777"

Kestrel crée une liaison avec le point de terminaison configuré spécifiquement pour Kestrel dans le appsettings.json fichier ( https://localhost:9999 ) et non https://localhost:7777 .Kestrel binds to the endpoint configured specifically for Kestrel in the appsettings.json file (https://localhost:9999) and not https://localhost:7777.

Considérez le point de terminaison spécifique à Kestrel configuré comme une variable d’environnement :Consider the Kestrel specific endpoint configured as an environment variable:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

Dans la variable d’environnement précédente, Https est le nom du point de terminaison spécifique à Kestrel.In the preceding environment variable, Https is the name of the Kestrel specific endpoint. Le appsettings.json fichier précédent définit également un point de terminaison spécifique à Kestrel nommé Https .The preceding appsettings.json file also defines a Kestrel specific endpoint named Https. Par défaut, les variables d’environnement utilisant le fournisseur de configuration des variables d’environnement sont lues après appSettings. Environment . JSON, par conséquent, la variable d’environnement précédente est utilisée pour le Https point de terminaison.By default, environment variables using the Environment Variables configuration provider are read after appsettings.Environment.json, therefore, the preceding environment variable is used for the Https endpoint.

GetValueGetValue

ConfigurationBinder.GetValue<T> extrait une valeur unique de la configuration avec une clé spécifiée et la convertit en type spécifié :ConfigurationBinder.GetValue<T> extracts a single value from configuration with a specified key and converts it to the specified type:

public class TestNumModel : PageModel
{
    private readonly IConfiguration Configuration;

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

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

Dans le code précédent, si est NumberKey introuvable dans la configuration, la valeur par défaut de 99 est utilisée.In the preceding code, if NumberKey isn't found in the configuration, the default value of 99 is used.

GetSection, GetChildren et ExistsGetSection, GetChildren, and Exists

Pour les exemples qui suivent, prenez en compte les MySubsection.jssuivantes sur le fichier :For the examples that follow, consider the following MySubsection.json file:

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

Le code suivant ajoute MySubsection.js aux fournisseurs de configuration :The following code adds MySubsection.json to the configuration providers:

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

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

GetSectionGetSection

IConfiguration. GetSection retourne une sous-section de configuration avec la clé de sous-section spécifiée.IConfiguration.GetSection returns a configuration subsection with the specified subsection key.

Le code suivant retourne des valeurs pour section1 :The following code returns values for section1:

public class TestSectionModel : PageModel
{
    private readonly IConfiguration Config;

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

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

Le code suivant retourne des valeurs pour section2:subsection0 :The following code returns values for section2:subsection0:

public class TestSection2Model : PageModel
{
    private readonly IConfiguration Config;

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

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

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

Quand GetSection retourne une section correspondante, Value n’est pas rempli.When GetSection returns a matching section, Value isn't populated. Key et Path sont retournés quand la section existe.A Key and Path are returned when the section exists.

GetChildren et EXISTSGetChildren and Exists

Le code suivant appelle IConfiguration. GetChildren et retourne des valeurs pour section2:subsection0 :The following code calls IConfiguration.GetChildren and returns values for section2:subsection0:

public class TestSection4Model : PageModel
{
    private readonly IConfiguration Config;

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

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

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

Le code précédent appelle ConfigurationExtensions. Exists pour vérifier l’existence de la section :The preceding code calls ConfigurationExtensions.Exists to verify the section exists:

Lier un tableauBind an array

ConfigurationBinder. bind prend en charge les tableaux de liaison aux objets à l’aide d’index de tableau dans les clés de configuration.The ConfigurationBinder.Bind supports binding arrays to objects using array indices in configuration keys. Tout format de tableau qui expose un segment de clé numérique est capable d’effectuer une liaison de tableau à un tableau de classes poco .Any array format that exposes a numeric key segment is capable of array binding to a POCO class array.

Prenez MyArray.js à partir de l' exemple de téléchargement:Consider MyArray.json from the sample download:

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

Le code suivant ajoute MyArray.js aux fournisseurs de configuration :The following code adds MyArray.json to the configuration providers:

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

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

Le code suivant lit la configuration et affiche les valeurs :The following code reads the configuration and displays the values:

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

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

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

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

        return Content(s);
    }
}

Le code précédent retourne la sortie suivante :The preceding code returns the following output:

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

Dans la sortie précédente, l’index 3 a la valeur value40 , ce qui correspond à "4": "value40", dans MyArray.jssur.In the preceding output, Index 3 has value value40, corresponding to "4": "value40", in MyArray.json. Les index de tableau liés sont continus et non liés à l’index de clé de configuration.The bound array indices are continuous and not bound to the configuration key index. Le Binder de configuration n’est pas en capacité à lier des valeurs null ou à créer des entrées NULL dans des objets liésThe configuration binder isn't capable of binding null values or creating null entries in bound objects

Le code suivant charge la array:entries configuration avec la AddInMemoryCollection méthode d’extension :The following code loads the array:entries configuration with the AddInMemoryCollection extension method:

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

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

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

Le code suivant lit la configuration dans arrayDict Dictionary et affiche les valeurs :The following code reads the configuration in the arrayDict Dictionary and displays the values:

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

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

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

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

        return Content(s);
    }
}

Le code précédent retourne la sortie suivante :The preceding code returns the following output:

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

L’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 les données de configuration contenant un tableau sont liées, les index de tableau dans les clés de configuration sont 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 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' ArrayExample instance par n’importe quel fournisseur de configuration qui lit la # paire clé/valeur de l’index 3.The missing configuration item for index #3 can be supplied before binding to the ArrayExample instance by any configuration provider that reads the index #3 key/value pair. Examinez le Value3.jssuivant sur le fichier à partir de l’exemple de téléchargement :Consider the following Value3.json file from the sample download:

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

Le code suivant comprend la configuration de Value3.jssur et arrayDict Dictionary :The following code includes configuration for Value3.json and the arrayDict Dictionary:

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

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

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

Le code suivant lit la configuration précédente et affiche les valeurs :The following code reads the preceding configuration and displays the values:

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

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

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

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

        return Content(s);
    }
}

Le code précédent retourne la sortie suivante :The preceding code returns the following output:

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

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.

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

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:

// using Microsoft.EntityFrameworkCore;

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:

// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;

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. Étant donné que les clés de configuration nerespectent pas la casse, le dictionnaire utilisé pour initialiser la base de données est créé avec le comparateur ne respectant pas la casse (StringComparer. OrdinalIgnoreCase).Since configuration keys are case-insensitive, the dictionary used to initialize the database is created with the case-insensitive comparer (StringComparer.OrdinalIgnoreCase).

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

// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;

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

    Action<DbContextOptionsBuilder> OptionsAction { get; }

    public override void Load()
    {
        var builder = new DbContextOptionsBuilder<EFConfigurationContext>();

        OptionsAction(builder);

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

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

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

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

        dbContext.SaveChanges();

        return configValues;
    }
}

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:

// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;

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:

// using Microsoft.EntityFrameworkCore;

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddEFConfiguration(
                options => options.UseInMemoryDatabase("InMemoryDb"));
        })

Configuration de l’accès au démarrageAccess configuration in Startup

Le code suivant affiche les données de configuration dans les Startup méthodes :The following code displays configuration data in Startup methods:

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

    public IConfiguration Configuration { get; }

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

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

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

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

        app.UseRouting();

        app.UseAuthorization();

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

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.

Configuration de l’accès dans les Razor pagesAccess configuration in Razor Pages

Le code suivant affiche les données de configuration dans une Razor page :The following code displays configuration data in a Razor Page:

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

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

Dans le code suivant, MyOptions est ajouté au conteneur de services avec Configure et lié à la configuration :In the following code, MyOptions is added to the service container with Configure and bound to configuration:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<MyOptions>(Configuration.GetSection("MyOptions"));

    services.AddRazorPages();
}

La balise suivante utilise la @inject Razor directive pour résoudre et afficher les valeurs des options :The following markup uses the @inject Razor directive to resolve and display the options values:

@page
@model SampleApp.Pages.Test3Model
@using Microsoft.Extensions.Options
@inject IOptions<MyOptions> optionsAccessor


<p><b>Option1:</b> @optionsAccessor.Value.Option1</p>
<p><b>Option2:</b> @optionsAccessor.Value.Option2</p>

Configuration de l’accès dans un fichier de vue MVCAccess configuration in a MVC view file

Le code suivant affiche les données de configuration dans une vue MVC :The following code displays configuration data in a MVC view:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

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

Configurer des options avec un déléguéConfigure options with a delegate

Les options configurées dans un délégué remplacent les valeurs définies dans les fournisseurs de configuration.Options configured in a delegate override values set in the configuration providers.

La configuration d’options avec un délégué est illustrée dans l’exemple 2 de l’exemple d’application.Configuring options with a delegate is demonstrated as Example 2 in the sample app.

Dans le code suivant, un IConfigureOptions<TOptions> service est ajouté au conteneur de services.In the following code, an IConfigureOptions<TOptions> service is added to the service container. Il utilise un délégué pour configurer des valeurs pour MyOptions :It uses a delegate to configure values for MyOptions:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<MyOptions>(myOptions =>
    {
        myOptions.Option1 = "Value configured in delegate";
        myOptions.Option2 = 500;
    });

    services.AddRazorPages();
}

Le code suivant affiche les valeurs des options :The following code displays the options values:

public class Test2Model : PageModel
{
    private readonly IOptions<MyOptions> _optionsDelegate;

    public Test2Model(IOptions<MyOptions> optionsDelegate )
    {
        _optionsDelegate = optionsDelegate;
    }

    public ContentResult OnGet()
    {
        return Content($"Option1: {_optionsDelegate.Value.Option1} \n" +
                       $"Option2: {_optionsDelegate.Value.Option2}");
    }
}

Dans l’exemple précédent, les valeurs de Option1 et Option2 sont spécifiées dans, appsettings.json puis remplacées par le délégué configuré.In the preceding example, the values of Option1 and Option2 are specified in appsettings.json and then overridden by the configured delegate.

Configuration de l’hôte ou configuration de l’applicationHost versus 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 sont également incluses dans la configuration de l’application.Host configuration key-value pairs are also included in the app's 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 Notions de base d’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 Notions de base d’ASP.NET Core.

Configuration de l’hôte par défautDefault host configuration

Pour plus de détails sur la configuration par défaut lors de l’utilisation de l’hôte Web, consultez la version ASP.NET Core 2.2. de cette rubrique.For details on the default configuration when using the Web Host, see the ASP.NET Core 2.2 version of this topic.

  • La configuration de l’hôte est fournie à partir des éléments suivants :Host configuration is provided from:
  • La configuration par défaut de l’hôte Web est établie (ConfigureWebHostDefaults) :Web Host default configuration is established (ConfigureWebHostDefaults):
    • Kestrel est utilisé comme serveur web et configuré à l’aide des fournisseurs de configuration de l’application.Kestrel is used as the web server and configured using the app's configuration providers.
    • Ajoutez l’intergiciel de filtrage d’hôtes.Add Host Filtering Middleware.
    • Ajoutez l’intergiciel d’en-têtes transférés si la variable d'environnement ASPNETCORE_FORWARDEDHEADERS_ENABLED est définie sur true.Add Forwarded Headers Middleware if the ASPNETCORE_FORWARDEDHEADERS_ENABLED environment variable is set to true.
    • Activez l’intégration d’IIS.Enable IIS integration.

Autre configurationOther configuration

Cette rubrique se rapporte uniquement à la configuration de l' application.This topic only pertains to app configuration. D’autres aspects de l’exécution et de l’hébergement des applications ASP.NET Core sont configurés à l’aide des fichiers de configuration non traités dans cette rubrique :Other aspects of running and hosting ASP.NET Core apps are configured using configuration files not covered in this topic:

  • launch.js / launchSettings.jssur sont des fichiers de configuration d’outils pour l’environnement de développement, décrits ci-après :launch.json/launchSettings.json are tooling configuration files for the Development environment, described:
  • web.config est un fichier de configuration de serveur, décrit dans les rubriques suivantes :web.config is a server configuration file, described in the following topics:

Les variables d’environnement définies dans launchSettings.jslors de la substitution de celles définies dans l’environnement système.Environment variables set in launchSettings.json override those set in the system environment.

Pour plus d’informations sur la migration de la configuration d’application à partir de versions antérieures de ASP.NET, consultez Migrer d’ASP.NET vers ASP.NET Core .For more information on migrating app configuration from earlier versions of ASP.NET, see Migrer d’ASP.NET vers ASP.NET Core.

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

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
  • Azure App ConfigurationAzure App Configuration
  • 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

Les packages de configuration pour les scénarios de fournisseur de configuration courants (Microsoft.Extensions.Configuration) sont inclus implicitement dans le métapaquet Microsoft.AspNetCore.App.Configuration packages for common configuration provider scenarios (Microsoft.Extensions.Configuration) are included in the Microsoft.AspNetCore.App metapackage.

Les exemples de code qui suivent et dans l’échantillon d’application utilisent l’espace de noms Microsoft.Extensions.Configuration :Code examples that follow and in the sample app use the Microsoft.Extensions.Configuration namespace:

using Microsoft.Extensions.Configuration;

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. Les options utilisent des classes pour représenter les groupes de paramètres associés.Options use classes to represent groups of related settings. 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.

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

Configuration de l’hôte ou configuration de l’applicationHost versus 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 sont également incluses dans la configuration de l’application.Host configuration key-value pairs are also included in the app's 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 Notions de base d’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 Notions de base d’ASP.NET Core.

Autre configurationOther configuration

Cette rubrique se rapporte uniquement à la configuration de l' application.This topic only pertains to app configuration. D’autres aspects de l’exécution et de l’hébergement des applications ASP.NET Core sont configurés à l’aide des fichiers de configuration non traités dans cette rubrique :Other aspects of running and hosting ASP.NET Core apps are configured using configuration files not covered in this topic:

  • launch.js / launchSettings.jssur sont des fichiers de configuration d’outils pour l’environnement de développement, décrits ci-après :launch.json/launchSettings.json are tooling configuration files for the Development environment, described:
  • web.config est un fichier de configuration de serveur, décrit dans les rubriques suivantes :web.config is a server configuration file, described in the following topics:

Pour plus d’informations sur la migration de la configuration d’application à partir de versions antérieures de ASP.NET, consultez Migrer d’ASP.NET vers ASP.NET Core .For more information on migrating app configuration from earlier versions of ASP.NET, see Migrer d’ASP.NET vers ASP.NET Core.

Configuration par défautDefault configuration

Les applications web basées sur les modèles ASP.NET Core dotnet new appellent CreateDefaultBuilder pendant la création d’un hôte.Web apps based on the ASP.NET Core dotnet new templates call CreateDefaultBuilder when building a host. CreateDefaultBuilder fournit la configuration par défaut de l’application dans l’ordre suivant :CreateDefaultBuilder provides default configuration for the app in the following order:

Les éléments suivants s’appliquent aux applications qui utilisent l’hôte web.The following applies to apps using the Web Host. Pour plus de détails sur la configuration par défaut lors de l’utilisation de l’hôte générique, consultez la dernière version de cette rubrique.For details on the default configuration when using the Generic Host, see the latest version of this topic.

SécuritéSecurity

Adoptez les pratiques suivantes pour sécuriser les données de configuration sensibles :Adopt the following practices to secure sensitive configuration data:

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

Pour plus d'informations, voir les rubriques suivantes :For more information, see the following topics:

Azure Key Vault stocke en toute sécurité des secrets d’application pour les applications ASP.NET Core.Azure Key Vault safely stores app secrets for ASP.NET Core apps. 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

Sources et fournisseursSources and providers

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 qui implémentent la détection des modifications peuvent recharger la configuration lorsqu’un paramètre sous-jacent est modifié.Configuration providers that implement change detection have the ability to reload configuration when an underlying setting is changed. Par exemple, le fournisseur de configuration de fichier (décrit plus loin dans cette rubrique) et le fournisseur de configuration Azure Key Vault implémentent la détection des modifications.For example, the File Configuration Provider (described later in this topic) and the Azure Key Vault Configuration Provider implement change detection.

IConfiguration est disponible dans le conteneur d’injection de dépendances de l’application.IConfiguration is available in the app's dependency injection (DI) container. IConfiguration peut être injecté dans une Razor page PageModel ou un MVC Controller pour obtenir la configuration de la classe.IConfiguration can be injected into a Razor Pages PageModel or MVC Controller to obtain configuration for the class.

Dans les exemples suivants, le _config champ est utilisé pour accéder aux valeurs de configuration :In the following examples, the _config field is used to access configuration values:

public class IndexModel : PageModel
{
    private readonly IConfiguration _config;

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

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

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.

KeysKeys

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. Pour plus d’informations sur les clés JSON en double, consultez ce problème GitHub.For more information on duplicate JSON keys, see this GitHub issue.
  • 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 automatiquement transformé en signe deux-points.A double underscore (__) is supported by all platforms and is automatically converted into 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. Écrivez du code pour remplacer les tirets par un signe deux-points lorsque les secrets sont chargés dans la configuration de l’application.Write 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.

ValeursValues

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 Azure App Configuration (documentation Azure)Azure App Configuration Provider (Azure documentation) Azure App ConfigurationAzure App Configuration
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 de l’utilisateur (rubriques relatives à la sécurité )User secrets (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 par ordre alphabétique, et non pas dans l’ordre dans lequel le code les réorganise.The configuration providers described in this topic are described in alphabetical order, not in the order that the code arranges them. Commandez des fournisseurs de configuration dans le code pour répondre aux priorités des sources de configuration sous-jacentes requises par l’application.Order configuration providers in code to suit the priorities for the underlying configuration sources that the app requires.

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 de l’utilisateur (environnement de développement uniquement)User secrets (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.A common practice is to position the Command-line Configuration Provider last in a series of providers to allow command-line arguments to override configuration set by the other providers.

La séquence de fournisseurs précédente est utilisée lors de l’initialisation d’un nouveau générateur d’hôte CreateDefaultBuilder .The preceding sequence of providers is used when a new host builder is initialized with CreateDefaultBuilder. Pour plus d’informations, consultez la section Configuration par défaut.For more information, see the Default configuration section.

Configurer le générateur d’ordinateur hôte avec UseConfigurationConfigure the host builder with UseConfiguration

Pour configurer le générateur d’ordinateur hôte, appelez UseConfiguration sur le générateur d’hôte avec la configuration.To configure the host builder, call UseConfiguration on the host builder with the configuration.

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

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

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

ConfigureAppConfigurationConfigureAppConfiguration

Appelez ConfigureAppConfiguration quand vous créez l’hôte pour spécifier les fournisseurs de configuration de l’application en plus de ceux ajoutés automatiquement par CreateDefaultBuilder :Call ConfigureAppConfiguration when building the host to specify the app's configuration providers in addition to those added automatically by CreateDefaultBuilder:

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

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

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

Remplacez la configuration précédente par des arguments de ligne de commandeOverride previous configuration with command-line arguments

Pour fournir une configuration d’application pouvant être remplacée par des arguments de ligne de commande, appelez AddCommandLine en dernier :To provide app configuration that can be overridden with command-line arguments, call AddCommandLine last:

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

Supprimer les fournisseurs ajoutés par CreateDefaultBuilderRemove providers added by CreateDefaultBuilder

Pour supprimer les fournisseurs ajoutés par CreateDefaultBuilder , appelez d’abord Clear sur IConfigurationBuilder. sources :To remove the providers added by CreateDefaultBuilder, call Clear on the IConfigurationBuilder.Sources first:

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

Utiliser la configuration lors du démarrage de l’applicationConsume configuration during app startup

La configuration fournie à l’application dans ConfigureAppConfiguration est disponible lors du démarrage de l’application, notamment Startup.ConfigureServices.Configuration supplied to the app in ConfigureAppConfiguration is available during the app's startup, including Startup.ConfigureServices. Pour plus d’informations, consultez la section Accéder à la configuration lors du démarrage.For more information, see the Access configuration during startup section.

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 quand CreateDefaultBuilder(string []) est appelé.AddCommandLine is automatically called when CreateDefaultBuilder(string []) is called. Pour plus d’informations, consultez la section Configuration par défaut.For more information, see the Default configuration section.

CreateDefaultBuilder charge également :CreateDefaultBuilder also loads:

  • Configuration facultative à partir de appsettings.json et appSettings. { Fichiers Environment}. JSON .Optional configuration from appsettings.json and appsettings.{Environment}.json files.
  • Secrets de l’utilisateur dans l’environnement de développement.User secrets 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.

Pour les applications basées sur les modèles ASP.NET Core, AddCommandLine a déjà été appelé par CreateDefaultBuilder.For apps based on the ASP.NET Core templates, AddCommandLine has already been called by CreateDefaultBuilder. Pour ajouter des fournisseurs de configuration supplémentaires et conserver la capacité de remplacer leur configuration par des arguments de ligne de commande, appelez les fournisseurs supplémentaires de l’application dans ConfigureAppConfiguration et appelez AddCommandLine en dernier.To add additional configuration providers and maintain the ability to override configuration from those providers with command-line arguments, call the app's additional providers in ConfigureAppConfiguration and call AddCommandLine last.

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

ExempleExample

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

  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 n’est pas requise si un signe égal est utilisé (par exemple, CommandLineKey=).The value isn't required 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. Lors de la génération manuelle d’une configuration avec un ConfigurationBuilder , fournissez un dictionnaire de remplacements de commutateur à la AddCommandLine méthode.When manually building configuration with a ConfigurationBuilder, 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.

Créez un dictionnaire des mappages de commutateurs.Create a switch mappings dictionary. Dans l’exemple suivant, deux mappages de commutateurs sont créés :In the following example, two switch mappings are created:

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

Lorsque l’hôte est généré, appelez AddCommandLine avec le dictionnaire de mappages de commutateurs :When the host is built, call AddCommandLine with the switch mappings dictionary:

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

Pour les applications qui utilisent des mappages de commutateurs, l’appel à CreateDefaultBuilder ne doit pas passer d’arguments.For apps that use switch mappings, the call to CreateDefaultBuilder shouldn't pass arguments. 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.The CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and there's no way to pass the switch mapping dictionary to CreateDefaultBuilder. La 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.

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.

CléKey ValeurValue
-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.

CléKey ValeurValue
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.

Le : séparateur ne fonctionne pas avec les clés hiérarchiques de variable d’environnement sur toutes les plateformes.The : separator doesn't work with environment variable hierarchical keys on all platforms. __, le double trait de soulignement, est :__, the double underscore, is:

  • Pris en charge par toutes les plateformes.Supported by all platforms. Par exemple, le : séparateur n’est pas pris en charge par bash, mais __ est.For example, the : separator is not supported by Bash, but __ is.
  • Automatiquement remplacé par un :Automatically replaced by a :

Azure App service permet de définir des variables d’environnement dans le portail Azure qui peuvent remplacer la configuration de l’application à l’aide du fournisseur de configuration des variables d’environnement.Azure App Service permits setting environment variables in the Azure Portal that can override app configuration using the Environment Variables Configuration Provider. Pour plus d’informations, consultez Azure Apps : 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 sert à charger les variables d’environnement préfixées avec ASPNETCORE_ pour la configuration hôte lorsqu’un nouveau générateur d’hôte est initialisé avec l’hôte web et que CreateDefaultBuilder est appelé.AddEnvironmentVariables is used to load environment variables prefixed with ASPNETCORE_ for host configuration when a new host builder is initialized with the Web Host and CreateDefaultBuilder is called. Pour plus d’informations, consultez la section Configuration par défaut.For more information, see the Default configuration section.

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 de appsettings.json et appSettings. { Fichiers Environment}. JSON .Optional configuration from appsettings.json and appsettings.{Environment}.json files.
  • Secrets de l’utilisateur dans l’environnement de développement.User secrets 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.

Pour fournir la configuration d’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 :To provide app configuration from additional environment variables, call the app's additional providers in ConfigureAppConfiguration and call AddEnvironmentVariables with the prefix:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddEnvironmentVariables(prefix: "PREFIX_");
})

Appelez AddEnvironmentVariables Last pour autoriser les variables d’environnement avec le préfixe spécifié à substituer des valeurs d’autres fournisseurs.Call AddEnvironmentVariables last to allow environment variables with the given prefix to override values from other providers.

ExempleExample

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

  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.To keep the list of environment variables rendered by the app short, the app filters environment variables. Consultez le fichier Pages/Index.cshtml.cs de l’exemple d’application.See the sample app's Pages/Index.cshtml.cs file.

Pour exposer toutes les variables d’environnement disponibles pour l’application, remplacez FilteredConfiguration dans pages/index. cshtml. cs par ce qui suit :To expose all of the environment variables available to the app, change the FilteredConfiguration in Pages/Index.cshtml.cs to the following:

FilteredConfiguration = _config.AsEnumerable();

PréfixesPrefixes

Les variables d’environnement chargées dans la configuration de l’application sont filtrées lors de la spécification d’un préfixe à la AddEnvironmentVariables méthode.Environment variables loaded into the app's configuration are filtered when supplying 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.

Lorsque le générateur d’hôte est créé, la configuration de l’hôte est fournie par des variables d’environnement.When the host builder is created, host configuration is provided by environment variables. Pour plus d’informations sur le préfixe utilisé pour ces variables d’environnement, consultez la section Configuration par défaut.For more information on the prefix used for these environment variables, see the Default configuration section.

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

ExempleExample

Une variable d’environnement de chaîne de connexion personnalisée est créée sur le serveur :A custom connection string environment variable is created on the server:

  • Nom : CUSTOMCONNSTR_ReleaseDBName: CUSTOMCONNSTR_ReleaseDB
  • Valeur: Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=TrueValue: Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True

Si IConfiguration est injecté et affecté à un champ nommé _config , lisez la valeur :If IConfiguration is injected and assigned to a field named _config, read the value:

_config["ConnectionStrings:ReleaseDB"]

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:

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

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 lors de l’initialisation d’un nouveau générateur d’hôte CreateDefaultBuilder .AddJsonFile is automatically called twice when a new host builder is initialized 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 appsettings.json fichier.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 de IHostingEnvironment. EnvironmentName.appsettings.{Environment}.json: The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName.

Pour plus d’informations, consultez la section Configuration par défaut.For more information, see the Default configuration section.

CreateDefaultBuilder charge également :CreateDefaultBuilder also loads:

  • Variables d'environnement.Environment variables.
  • Secrets de l’utilisateur dans l’environnement de développement.User secrets in the Development environment.
  • Arguments de ligne de commandeCommand-line arguments.

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 génération de l’hôte pour spécifier la configuration de l’application pour les fichiers autres que appsettings.json et appSettings. { Environnement}. JSON:Call ConfigureAppConfiguration when building the host to specify the app's configuration for files other than appsettings.json and appsettings.{Environment}.json:

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

ExempleExample

L’exemple d’application tire parti de la méthode de commodité statique CreateDefaultBuilder pour créer l’hôte, ce qui comprend deux appels à AddJsonFile :The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes two calls to AddJsonFile:

  • Le premier appel à AddJsonFile charge la configuration à partir de appsettings.json :The first call to AddJsonFile loads configuration from appsettings.json:

    {
      "Logging": {
        "LogLevel": {
          "Default": "Warning"
        }
      },
      "AllowedHosts": "*"
    }
    
  • Le deuxième appel à AddJsonFile charge la configuration à partir de appSettings. { Environnement}. JSON.The second call to AddJsonFile loads configuration from appsettings.{Environment}.json. Pour appsettings.Development.js dans l’exemple d’application, le fichier suivant est chargé :For appsettings.Development.json in the sample app, the following file is loaded:

    {
      "Logging": {
        "LogLevel": {
          "Default": "Debug",
          "System": "Information",
          "Microsoft": "Information"
        }
      }
    }
    
  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. La sortie contient des paires clé-valeur pour la configuration en fonction de l’environnement de l’application.The output contains key-value pairs for the configuration based on the app's environment. Le niveau de journalisation de la clé Logging:LogLevel:Default est Debug lors de l’exécution de l’application dans l’environnement de développement.The log level for the key Logging:LogLevel:Default is Debug when running the app in the Development environment.
  3. Exécutez à nouveau l’exemple d’application dans l’environnement de production :Run the sample app again in the Production environment:
    1. Ouvrez le fichier Properties/launchSettings.js .Open the Properties/launchSettings.json file.
    2. Dans le ConfigurationSample profil, remplacez la valeur de la ASPNETCORE_ENVIRONMENT variable d’environnement par Production .In the ConfigurationSample profile, change the value of the ASPNETCORE_ENVIRONMENT environment variable to Production.
    3. Enregistrez le fichier et exécutez l’application avec dotnet run dans un interpréteur de commandes.Save the file and run the app with dotnet run in a command shell.
  4. Les paramètres de la appsettings.Development.js qui ne se substituent plus aux paramètres dans appsettings.json .The settings in the appsettings.Development.json no longer override the settings in appsettings.json. Le niveau de journalisation de la clé Logging:LogLevel:Default est Warning .The log level for the key Logging:LogLevel:Default is Warning.

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:

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

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:

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

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.

Dans l’exemple suivant, un dictionnaire de configuration est créé :In the following example, a configuration dictionary is created:

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

Le dictionnaire est utilisé avec un appel à AddInMemoryCollection pour fournir la configuration :The dictionary is used with a call to AddInMemoryCollection to provide the configuration:

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

GetValueGetValue

ConfigurationBinder.GetValue<T> extrait une valeur unique de la configuration avec une clé spécifiée et la convertit en type de non-collection spécifié.ConfigurationBinder.GetValue<T> extracts a single value from configuration with a specified key and converts it to the specified noncollection type. Une surcharge accepte une valeur par défaut.An overload accepts a default value.

L’exemple suivant :The following example:

  • Extrait la valeur de chaîne de la configuration avec la clé NumberKey.Extracts the string value from configuration with the key NumberKey. Si NumberKey est introuvable dans les clés de configuration, la valeur par défaut de 99 est utilisée.If NumberKey isn't found in the configuration keys, the default value of 99 is used.
  • Tape la valeur comme int.Types the value as an int.
  • Stocke la valeur dans la propriété NumberConfig pour une utilisation par la page.Stores the value in the NumberConfig property for use by the page.
public class IndexModel : PageModel
{
    public IndexModel(IConfiguration config)
    {
        _config = config;
    }

    public int NumberConfig { get; private set; }

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

GetSection, GetChildren 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");

configSection n’a pas de valeur, seulement une clé et un chemin.The configSection doesn't have a value, only a key and a path.

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.

Quand GetSection retourne une section correspondante, Value n’est pas rempli.When GetSection returns a matching section, Value isn't populated. Key et Path sont retournés quand la section existe.A Key and Path are returned when the section exists.

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

ExistsExists

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.

É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. Comme pour la liaison d’un objet simple, seules les propriétés accessibles en lecture/écriture publiques sont liées.As with binding a simple object, only public read/write properties are bound.

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

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>

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;

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 :The following code shows how to use Get<T> with the preceding example:

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 une liaison de tableau à 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.

Notes

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.

CléKey ValeurValue
array:entries:0array:entries:0 value0value0
array:entries:1array:entries:1 valeur1value1
array:entries:2array:entries:2 valeur2value2
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.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>();
}

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

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

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

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 valeur1value1
22 valeur2value2
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);

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.

CléKey ValeurValue
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 valeur1value1
22 valeur2value2
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"
    ]
  }
}

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:

CléKey ValeurValue
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; }
}

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

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

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

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>(StringComparer.OrdinalIgnoreCase)
            {
                { "quote1", "I aim to misbehave." },
                { "quote2", "I swallowed a bug." },
                { "quote3", "You can't stop the signal, Mal." }
            };

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

        dbContext.SaveChanges();

        return configValues;
    }
}

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

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

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.

Configuration de l’accès dans une Razor page pages ou une vue MVCAccess configuration in a Razor Pages page or MVC view

Pour accéder aux paramètres de configuration dans une Razor page pages ou une vue MVC, ajoutez une directive using (référence C# : directive using) pour l' espace de nomsMicrosoft.Extensions.Configfiguration 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 Razor page pages :In a Razor Pages page:

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

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

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