Configuration dans ASP.NET CoreConfiguration in ASP.NET Core

Par Rick Anderson, Mark Michaelis, Steve Smith, Daniel Roth et Luke LathamBy Rick Anderson, Mark Michaelis, Steve Smith, Daniel Roth, and Luke Latham

L’API de configuration fournit un moyen de configurer une application web ASP.NET Core basé sur une liste de paires nom/valeur.The Configuration API provides a way to configure an ASP.NET Core web app based on a list of name-value pairs. La configuration est lue au moment de l’exécution à partir de plusieurs sources.Configuration is read at runtime from multiple sources. Les paires nom/valeur peuvent être regroupées dans une hiérarchie à plusieurs niveaux.Name-value pairs can be grouped into a multi-level hierarchy.

Il existe des fournisseurs de configuration pour les éléments suivants :There are configuration providers for:

  • Formats de fichiers (INI, JSON et XML).File formats (INI, JSON, and XML).
  • Arguments de ligne de commandeCommand-line arguments.
  • Variables d'environnement.Environment variables.
  • Objets .NET en mémoire.In-memory .NET objects.
  • Stockage Secret Manager non chiffré.The unencrypted Secret Manager storage.
  • Magasin utilisateur chiffré comme Azure Key Vault.An encrypted user store, such as Azure Key Vault.
  • Fournisseurs personnalisés (installés ou créés).Custom providers (installed or created).

Chaque valeur de configuration correspond à une clé de chaîne.Each configuration value maps to a string key. Une liaison intégrée est prise en charge pour désérialiser les paramètres dans un objet POCO personnalisé (une classe .NET simple avec des propriétés).There's built-in binding support to deserialize settings into a custom POCO object (a simple .NET class with properties).

Le modèle d’options utilise des classes d’options pour représenter les groupes de paramètres associés.The options pattern uses options classes to represent groups of related settings. Pour plus d’informations sur l’utilisation du modèle d’options, consultez la rubrique Options.For more information on using the options pattern, see the Options topic.

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

Configuration JSONJSON configuration

L’application console suivante utilise le fournisseur de configuration JSON :The following console app uses the JSON configuration provider:

using System;
using System.IO;
// Requires NuGet package
// Microsoft.Extensions.Configuration.Json
using Microsoft.Extensions.Configuration;

public class Program
{
    public static IConfiguration Configuration { get; set; }

    public static void Main(string[] args = null)
    {
        var builder = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json");

        Configuration = builder.Build();

        Console.WriteLine($"option1 = {Configuration["Option1"]}");
        Console.WriteLine($"option2 = {Configuration["option2"]}");
        Console.WriteLine(
            $"suboption1 = {Configuration["subsection:suboption1"]}");
        Console.WriteLine();

        Console.WriteLine("Wizards:");
        Console.Write($"{Configuration["wizards:0:Name"]}, ");
        Console.WriteLine($"age {Configuration["wizards:0:Age"]}");
        Console.Write($"{Configuration["wizards:1:Name"]}, ");
        Console.WriteLine($"age {Configuration["wizards:1:Age"]}");
        Console.WriteLine();

        Console.WriteLine("Press a key...");
        Console.ReadKey();
    }
}

L’application lit et affiche les paramètres de configuration suivants :The app reads and displays the following configuration settings:

{
  "option1": "value1_from_json",
  "option2": 2,

  "subsection": {
    "suboption1": "subvalue1_from_json"
  },
  "wizards": [
    {
      "Name": "Gandalf",
      "Age": "1000"
    },
    {
      "Name": "Harry",
      "Age": "17"
    }
  ]
}

La configuration est constituée d’une liste hiérarchique de paires nom/valeur, dans laquelle les nœuds sont séparés par un signe deux-points (:).Configuration consists of a hierarchical list of name-value pairs in which the nodes are separated by a colon (:). Pour récupérer une valeur, accédez à l’indexeur Configuration avec la clé de l’élément correspondant :To retrieve a value, access the Configuration indexer with the corresponding item's key:

Console.WriteLine(
    $"suboption1 = {Configuration["subsection:suboption1"]}");

Pour utiliser des tableaux dans des sources de configuration au format JSON, utilisez un index de tableau comme partie d’une chaîne séparée par des signes deux-points.To work with arrays in JSON-formatted configuration sources, use an array index as part of the colon-separated string. L’exemple suivant obtient le nom du premier élément dans le tableau wizards précédent :The following example gets the name of the first item in the preceding wizards array:

Console.Write($"{Configuration["wizards:0:Name"]}");
// Output: Gandalf

Les paires nom/valeur écrites dans les fournisseurs Configuration intégrés ne sont pas conservées.Name-value pairs written to the built-in Configuration providers are not persisted. Toutefois, un fournisseur personnalisé qui enregistre les valeurs peut être créé.However, a custom provider that saves values can be created. Consultez la section relative à la création d’un fournisseur de configuration personnalisé.See custom configuration provider.

L’exemple précédent utilise l’indexeur de configuration pour lire des valeurs.The preceding sample uses the configuration indexer to read values. Pour accéder à la configuration en dehors de Startup, utilisez le modèle d’options.To access configuration outside of Startup, use the options pattern. Pour plus d’informations, consultez la rubrique Options.For more information, see the Options topic.

Configuration XMLXML configuration

Pour utiliser des tableaux dans des sources de configuration au format XML, fournissez un index name à chaque élément.To work with arrays in XML-formatted configuration sources, provide a name index to each element. Utilisez l’index pour accéder aux valeurs :Use the index to access the values:

<wizards>
  <wizard name="Gandalf">
    <age>1000</age>
  </wizard>
  <wizard name="Harry">
    <age>17</age>
  </wizard>
</wizards>
Console.Write($"{Configuration["wizard:Harry:age"]}");
// Output: 17

Configuration par environnementConfiguration by environment

Il est courant d’avoir des paramètres de configuration différents pour différents environnements, par exemple pour l’environnement de développement, de test et de production.It's typical to have different configuration settings for different environments, for example, development, testing, and production. La méthode d’extension CreateDefaultBuilder dans une application ASP.NET Core 2.x (ou l’utilisation de AddJsonFile et de AddEnvironmentVariables directement dans une application ASP.NET Core 1.x) ajoute des fournisseurs de configuration pour la lecture des fichiers JSON et des sources de configuration système :The CreateDefaultBuilder extension method in an ASP.NET Core 2.x app (or using AddJsonFile and AddEnvironmentVariables directly in an ASP.NET Core 1.x app) adds configuration providers for reading JSON files and system configuration sources:

  • appsettings.jsonappsettings.json
  • appsettings.<nom_environnement>.jsonappsettings.<EnvironmentName>.json
  • Variables d’environnementEnvironment variables

Les applications ASP.NET Core 1.x doivent appeler AddJsonFile et AddEnvironmentVariables.ASP.NET Core 1.x apps need to call AddJsonFile and AddEnvironmentVariables.

Consultez AddJsonFile pour obtenir une explication des paramètres.See AddJsonFile for an explanation of the parameters. reloadOnChange est pris en charge uniquement dans ASP.NET Core 1.1 et ultérieur.reloadOnChange is only supported in ASP.NET Core 1.1 and later.

Les sources de configuration sont lues dans l’ordre où elles sont spécifiées.Configuration sources are read in the order that they're specified. Dans le code précédent, les variables d’environnement sont lues en dernier.In the preceding code, the environment variables are read last. Toutes les valeurs de configuration définies dans l’environnement remplacent celles définies dans les deux fournisseurs précédents.Any configuration values set through the environment replace those set in the two previous providers.

Considérez le fichier appsettings.Staging.json suivant :Consider the following appsettings.Staging.json file:

{
  "Logging": {
    "IncludeScopes": false,
    "LogLevel": {
      "System": "Information",
      "Microsoft": "Information"
    }
  },
  "MyConfig": "My Config Value for staging."
}

Lorsque l’environnement a la valeur Staging, la méthode Configure suivante lit la valeur de MyConfig :When the environment is set to Staging, the following Configure method reads the value of MyConfig:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    var myConfig = Configuration["MyConfig"];
    // use myConfig
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
        app.UseBrowserLink();
    }

    if (env.IsProduction() || env.IsStaging())
    {
        app.UseExceptionHandler("/Error");
    }

    app.UseStaticFiles();
    app.UseMvcWithDefaultRoute();
}

L’environnement est généralement défini sur Development, Staging ou Production.The environment is typically set to Development, Staging, or Production. Pour plus d’informations, consultez Utiliser plusieurs environnements.For more information, see Use multiple environments.

Points à prendre en considération pour la configuration :Configuration considerations:

  • IOptionsSnapshot peut recharger les données de configuration quand elles changent.IOptionsSnapshot can reload configuration data when it changes.
  • Les clés de configuration ne respectent pas la casse.Configuration keys are not case-sensitive.
  • 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. Découvrez plus en détail comment utiliser plusieurs environnements et gérer le stockage sécurisé des secrets des applications lors du développement.Learn more about how to use multiple environments and managing safe storage of app secrets in development.
  • Pour les valeurs de configuration hiérarchiques spécifiées dans des variables d’environnement, un signe deux-points (:) peut ne pas fonctionner sur toutes les plateformes.For hierarchical config values specified in environment variables, a colon (:) may not work on all platforms. Le trait de soulignement double (__) est pris en charge par toutes les plateformes.Double underscore (__) is supported by all platforms.
  • Pour l’interaction avec l’API de configuration, un signe deux-points (:) fonctionne sur toutes les plateformes.When interacting with the configuration API, a colon (:) works on all platforms.

Fournisseur en mémoire et liaison à une classe POCOIn-memory provider and binding to a POCO class

L’exemple suivant montre comment utiliser le fournisseur en mémoire et le lier à une classe :The following sample shows how to use the in-memory provider and bind to a class:

using System;
using System.Collections.Generic;
using Microsoft.Extensions.Configuration;

public class Program
{   
    public static IConfiguration Configuration { get; set; }

    public static void Main(string[] args = null)
    {
        var dict = new Dictionary<string, string>
            {
                {"Profile:MachineName", "Rick"},
                {"App:MainWindow:Height", "11"},
                {"App:MainWindow:Width", "11"},
                {"App:MainWindow:Top", "11"},
                {"App:MainWindow:Left", "11"}
            };

        var builder = new ConfigurationBuilder();
        builder.AddInMemoryCollection(dict);

        Configuration = builder.Build();

        Console.WriteLine($"Hello {Configuration["Profile:MachineName"]}");

        var window = new MyWindow();
        // Bind requrires NuGet package
        // Microsoft.Extensions.Configuration.Binder
        Configuration.GetSection("App:MainWindow").Bind(window);
        Console.WriteLine($"Left {window.Left}");
        Console.WriteLine();

        Console.WriteLine("Press any key...");
        Console.ReadKey();
    }
}

public class MyWindow
{
    public int Height { get; set; }
    public int Width { get; set; }
    public int Top { get; set; }
    public int Left { get; set; }
}

Les valeurs de configuration sont retournées sous forme de chaînes, mais la liaison permet la construction d’objets.Configuration values are returned as strings, but binding enables the construction of objects. En effet, la liaison permet la récupération des objets POCO ou même des graphes d’objets entiers.Binding allows the retrieval of POCO objects or even entire object graphs.

GetValueGetValue

L’exemple suivant illustre la méthode d’extension GetValue<T> :The following sample demonstrates the GetValue<T> extension method:

using System;
using System.Collections.Generic;
using Microsoft.Extensions.Configuration;

public class Program
{   
    public static IConfiguration Configuration { get; set; }

    public static void Main(string[] args = null)
    {
        var dict = new Dictionary<string, string>
            {
                {"Profile:MachineName", "Rick"},
                {"App:MainWindow:Height", "11"},
                {"App:MainWindow:Width", "11"},
                {"App:MainWindow:Top", "11"},
                {"App:MainWindow:Left", "11"}
            };

        var builder = new ConfigurationBuilder();
        builder.AddInMemoryCollection(dict);

        Configuration = builder.Build();

        Console.WriteLine($"Hello {Configuration["Profile:MachineName"]}");

        // Show GetValue overload and set the default value to 80
        // Requires NuGet package "Microsoft.Extensions.Configuration.Binder"
        var left = Configuration.GetValue<int>("App:MainWindow:Left", 80);
        Console.WriteLine($"Left {left}");

        var window = new MyWindow();
        Configuration.GetSection("App:MainWindow").Bind(window);
        Console.WriteLine($"Left {window.Left}");
        Console.WriteLine();

        Console.WriteLine("Press a key...");
        Console.ReadKey();
    }
}

public class MyWindow
{
    public int Height { get; set; }
    public int Width { get; set; }
    public int Top { get; set; }
    public int Left { get; set; }
}

La méthode GetValue<T> de ConfigurationBinder permet de spécifier une valeur par défaut (80 dans l’exemple).The ConfigurationBinder's GetValue<T> method allows the specification of a default value (80 in the sample). GetValue<T> est destiné aux scénarios simples et n’établit pas de liaison à des sections entières.GetValue<T> is for simple scenarios and doesn't bind to entire sections. GetValue<T> obtient les valeurs scalaires de GetSection(key).Value converties en un type spécifique.GetValue<T> obtains scalar values from GetSection(key).Value converted to a specific type.

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

Chaque objet d’une classe peut se voir établir une liaison récursive.Each object in a class can be recursively bound. Considérez la classe AppSettings suivante :Consider the following AppSettings class:

public class AppSettings
{
    public Window Window { get; set; }
    public Connection Connection { get; set; }
    public Profile Profile { get; set; }
}

public class Window
{
    public int Height { get; set; }
    public int Width { get; set; }
}

public class Connection
{
    public string Value { get; set; }
}

public class Profile
{
    public string Machine { get; set; }
}

L’exemple suivant crée une liaison à la classe AppSettings :The following sample binds to the AppSettings class:

using System;
using System.IO;
using Microsoft.Extensions.Configuration;

public class Program
{
    public static void Main(string[] args = null)
    {
        var builder = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json");

        var config = builder.Build();

        var appConfig = new AppSettings();
        config.GetSection("App").Bind(appConfig);

        Console.WriteLine($"Height {appConfig.Window.Height}");
        Console.WriteLine();

        Console.WriteLine("Press a key...");
        Console.ReadKey();
    }
}

ASP.NET Core 1.1 et les versions ultérieures peuvent utiliser Get<T>, qui fonctionne avec des sections entières.ASP.NET Core 1.1 and higher can use Get<T>, which works with entire sections. Il peut être plus pratique d’utiliser Get<T> que Bind.Get<T> can be 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 sample:

var appConfig = config.GetSection("App").Get<AppSettings>();

En utilisant le fichier appsettings.json suivant :Using the following appsettings.json file:

{
  "App": {
    "Profile": {
      "Machine": "Rick"
    },
    "Connection": {
      "Value": "connectionstring"
    },
    "Window": {
      "Height": "11",
      "Width": "11"
    }
  }
}

Le programme affiche Height 11.The program displays Height 11.

Le code suivant peut être utilisé pour effectuer un test unitaire sur la configuration :The following code can be used to unit test the configuration:

[Fact]
public void CanBindObjectTree()
{
    var dict = new Dictionary<string, string>
        {
            {"App:Profile:Machine", "Rick"},
            {"App:Connection:Value", "connectionstring"},
            {"App:Window:Height", "11"},
            {"App:Window:Width", "11"}
        };
    var builder = new ConfigurationBuilder();
    builder.AddInMemoryCollection(dict);
    var config = builder.Build();

    var settings = new AppSettings();
    config.GetSection("App").Bind(settings);

    Assert.Equal("Rick", settings.Profile.Machine);
    Assert.Equal(11, settings.Window.Height);
    Assert.Equal(11, settings.Window.Width);
    Assert.Equal("connectionstring", settings.Connection.Value);
}

Créer un fournisseur personnalisé Entity FrameworkCreate an Entity Framework custom provider

Dans cette section, un fournisseur de configuration de base qui lit des paires nom/valeur à partir d’une base de données utilisant Entity Framework est créé.In this section, a basic configuration provider that reads name-value pairs from a database using EF is created.

Définissez une entité ConfigurationValue pour le stockage des valeurs de configuration dans la base de données :Define a ConfigurationValue entity for storing configuration values in the database:

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

Ajoutez un ConfigurationContext pour stocker les valeurs configurées et y accéder :Add a ConfigurationContext to store and access the configured values:

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

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

Créez une classe qui implémente IConfigurationSource :Create a class that implements IConfigurationSource:

using System;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;

namespace CustomConfigurationProvider
{
    public class EFConfigSource : IConfigurationSource
    {
        private readonly Action<DbContextOptionsBuilder> _optionsAction;

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

        public IConfigurationProvider Build(IConfigurationBuilder builder)
        {
            return new EFConfigProvider(_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:

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;

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

        Action<DbContextOptionsBuilder> OptionsAction { get; }

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

            using (var dbContext = new ConfigurationContext(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(
            ConfigurationContext dbContext)
        {
            var configValues = new Dictionary<string, string>
                {
                    { "key1", "value_from_ef_1" },
                    { "key2", "value_from_ef_2" }
                };
            dbContext.Values.AddRange(configValues
                .Select(kvp => new ConfigurationValue { Id = kvp.Key, Value = kvp.Value })
                .ToArray());
            dbContext.SaveChanges();
            return configValues;
        }
    }
}

Les valeurs en surbrillance provenant de la base de données ("value_from_ef_1" et "value_from_ef_2") sont affichées quand l’exemple est exécuté.The highlighted values from the database ("value_from_ef_1" and "value_from_ef_2") are displayed when the sample is run.

Vous pouvez utiliser une méthode d’extension EFConfigSource pour l’ajout de la source de configuration :An EFConfigSource extension method for adding the configuration source can be used:

using System;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;

namespace CustomConfigurationProvider
{
    public static class EntityFrameworkExtensions
    {
        public static IConfigurationBuilder AddEntityFrameworkConfig(
            this IConfigurationBuilder builder, Action<DbContextOptionsBuilder> setup)
        {
            return builder.Add(new EFConfigSource(setup));
        }
    }
}

Le code suivant montre comment utiliser l’EFConfigProvider personnalisé :The following code shows how to use the custom EFConfigProvider:

using System;
using System.IO;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;
using CustomConfigurationProvider;

public static class Program
{
    public static void Main()
    {
        var builder = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json");

        var connectionStringConfig = builder.Build();

        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            // Add "appsettings.json" to bootstrap EF config.
            .AddJsonFile("appsettings.json")
            // Add the EF configuration provider, which will override any
            // config made with the JSON provider.
            .AddEntityFrameworkConfig(options =>
                options.UseSqlServer(connectionStringConfig.GetConnectionString(
                    "DefaultConnection"))
            )
            .Build();

        Console.WriteLine("key1={0}", config["key1"]);
        Console.WriteLine("key2={0}", config["key2"]);
        Console.WriteLine("key3={0}", config["key3"]);
        Console.WriteLine();

        Console.WriteLine("Press a key...");
        Console.ReadKey();
    }
}

Notez que l’exemple ajoute l’EFConfigProvider personnalisé après le fournisseur JSON. Par conséquent, tous les paramètres de la base de données substituent les paramètres du fichier appsettings.json.Note the sample adds the custom EFConfigProvider after the JSON provider, so any settings from the database will override settings from the appsettings.json file.

En utilisant le fichier appsettings.json suivant :Using the following appsettings.json file:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\mssqllocaldb;Database=CustomConfigurationProvider;Trusted_Connection=True;MultipleActiveResultSets=true"
  },
  "key1": "value_from_json_1",
  "key2": "value_from_json_2",
  "key3": "value_from_json_3"
}

La sortie suivante s’affiche :The following output is displayed:

key1=value_from_ef_1
key2=value_from_ef_2
key3=value_from_json_3

Fournisseur de configuration CommandLineCommandLine configuration provider

Le fournisseur de configuration CommandLine reçoit des paires clé/valeur d’arguments de ligne de commande pour la configuration au moment de l’exécution.The CommandLine configuration provider receives command-line argument key-value pairs for configuration at runtime.

Afficher ou télécharger l’exemple de configuration CommandLineView or download the CommandLine configuration sample

Configurer et utiliser le fournisseur de configuration CommandLineSetup and use the CommandLine configuration provider

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

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.Extensions.Configuration;

public class Program
{
    public static IConfiguration Configuration { get; set; }

    public static void Main(string[] args = null)
    {
        var dict = new Dictionary<string, string>
            {
                {"Profile:MachineName", "MairaPC"},
                {"App:MainWindow:Left", "1980"}
            };

        var builder = new ConfigurationBuilder();

        builder.AddInMemoryCollection(dict)
            .AddCommandLine(args);

        Configuration = builder.Build();

        Console.WriteLine($"MachineName: {Configuration["Profile:MachineName"]}");
        Console.WriteLine($"Left: {Configuration["App:MainWindow:Left"]}");
        Console.WriteLine();

        Console.WriteLine("Press a key...");
        Console.ReadKey();
    }
}

Quand le code est exécuté, la sortie suivante s’affiche :Running the code, the following output is displayed:

MachineName: MairaPC
Left: 1980

Le passage de paires clé/valeur d’arguments sur la ligne de commande modifie les valeurs de Profile:MachineName et de App:MainWindow:Left :Passing argument key-value pairs on the command line changes the values of Profile:MachineName and App:MainWindow:Left:

dotnet run Profile:MachineName=BartPC App:MainWindow:Left=1979

La fenêtre de console s’affiche :The console window displays:

MachineName: BartPC
Left: 1979

Pour substituer la configuration fournie par d’autres fournisseurs de configuration avec la configuration en ligne de commande, appelez AddCommandLine en dernier sur ConfigurationBuilder :To override configuration provided by other configuration providers with command-line configuration, call AddCommandLine last on ConfigurationBuilder:

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

ArgumentsArguments

Les arguments passés sur la ligne de commande doivent être conformes à l’un des deux formats indiqués dans le tableau suivant :Arguments passed on the command line must conform to one of two formats shown in the following table:

Format d’argumentArgument format ExempleExample
Argument unique : une paire clé/valeur séparée par un signe égal (=)Single argument: a key-value pair separated by an equals sign (=) key1=value
Séquence de deux arguments : une paire clé/valeur séparée par un espaceSequence of two arguments: a key-value pair separated by a space /key1 value1

Argument uniqueSingle argument

La valeur doit suivre un signe égal (=).The value must follow an equals sign (=). La valeur peut être null (par exemple, mykey=).The value can be null (for example, mykey=).

La clé peut avoir un préfixe.The key may have a prefix.

Préfixe de cléKey prefix ExempleExample
Aucun préfixeNo prefix key1=value1
Un seul tiret (-)†Single dash (-)† -key2=value2
Deux tirets (--)Two dashes (--) --key3=value3
Barre oblique (/)Forward slash (/) /key4=value4

†Une clé avec un préfixe composé d’un seul préfixe (-) doit être fournie dans les correspondances de commutateur, décrits ci-dessous.†A key with a single dash prefix (-) must be provided in switch mappings, described below.

Exemple de commande :Example command:

dotnet run key1=value1 -key2=value2 --key3=value3 /key4=value4

Remarque : Si -key2 n’est pas présent dans les correspondances de commutateur donnés au fournisseur de configuration, un FormatException est levé.Note: If -key2 isn't present in the switch mappings given to the configuration provider, a FormatException is thrown.

Séquence de deux argumentsSequence of two arguments

La valeur ne peut pas être null et doit suivre la clé, séparée par un espace.The value can't be null and must follow the key separated by a space.

La clé doit avoir un préfixe.The key must have a prefix.

Préfixe de cléKey prefix ExempleExample
Un seul tiret (-)†Single dash (-)† -key1 value1
Deux tirets (--)Two dashes (--) --key2 value2
Barre oblique (/)Forward slash (/) /key3 value3

†Une clé avec un préfixe composé d’un seul préfixe (-) doit être fournie dans les correspondances de commutateur, décrits ci-dessous.†A key with a single dash prefix (-) must be provided in switch mappings, described below.

Exemple de commande :Example command:

dotnet run -key1 value1 --key2 value2 /key3 value3

Remarque : Si -key1 n’est pas présent dans les correspondances de commutateur donnés au fournisseur de configuration, un FormatException est levé.Note: If -key1 isn't present in the switch mappings given to the configuration provider, a FormatException is thrown.

Clés en doubleDuplicate keys

Si des clés en double sont fournies, la dernière paire clé/valeur est utilisée.If duplicate keys are provided, the last key-value pair is used.

Correspondances de commutateurSwitch mappings

Lors de la génération manuelle d’une configuration avec ConfigurationBuilder, un dictionnaire de correspondances de commutateur peut être ajouté à la méthode AddCommandLine.When manually building configuration with ConfigurationBuilder, a switch mappings dictionary can be added to the AddCommandLine method. Les correspondances de commutateur permettent une logique de remplacement des noms de clés.Switch mappings allow key name replacement logic.

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 configuration.If the command-line key is found in the dictionary, the dictionary value (the key replacement) is passed back to set the 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.

Dans l’exemple suivant, la méthode GetSwitchMappings permet aux arguments de ligne de commande d’utiliser un préfixe de clé composé d’un tiret unique (-) et d’éviter les préfixes de sous-clés.In the following example, the GetSwitchMappings method allows command-line arguments to use a single dash (-) key prefix and avoid leading subkey prefixes.

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.Extensions.Configuration;

public class Program
{
    public static IConfiguration Configuration { get; set; }

    public static Dictionary<string, string> GetSwitchMappings(
        IReadOnlyDictionary<string, string> configurationStrings)
    {
        return configurationStrings.Select(item =>
            new KeyValuePair<string, string>(
                "-" + item.Key.Substring(item.Key.LastIndexOf(':') + 1),
                item.Key))
                .ToDictionary(
                    item => item.Key, item => item.Value);
    }

    public static void Main(string[] args = null)
    {
        var dict = new Dictionary<string, string>
            {
                {"Profile:MachineName", "RickPC"},
                {"App:MainWindow:Left", "1980"}
            };

        var builder = new ConfigurationBuilder();

        builder.AddInMemoryCollection(dict)
            .AddCommandLine(args, GetSwitchMappings(dict));

        Configuration = builder.Build();

        Console.WriteLine($"MachineName: {Configuration["Profile:MachineName"]}");
        Console.WriteLine($"Left: {Configuration["App:MainWindow:Left"]}");
        Console.WriteLine();

        Console.WriteLine("Press a key...");
        Console.ReadKey();
    }
}

Si aucun argument de ligne de commande n’est spécifié, le dictionnaire fourni à AddInMemoryCollection définit les valeurs de configuration.Without providing command-line arguments, the dictionary provided to AddInMemoryCollection sets the configuration values. Exécutez l’application avec la commande suivante :Run the app with the following command:

dotnet run

La fenêtre de console s’affiche :The console window displays:

MachineName: RickPC
Left: 1980

Utilisez le code suivant pour passer des paramètres de configuration :Use the following to pass in configuration settings:

dotnet run /Profile:MachineName=DahliaPC /App:MainWindow:Left=1984

La fenêtre de console s’affiche :The console window displays:

MachineName: DahliaPC
Left: 1984

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

ToucheKey ValueValue
-MachineName Profile:MachineName
-Left App:MainWindow:Left

Pour illustrer le remplacement des clés à l’aide du dictionnaire, exécutez la commande suivante :To demonstrate key switching using the dictionary, run the following command:

dotnet run -MachineName=ChadPC -Left=1988

Les clés de ligne de commande sont remplacées.The command-line keys are swapped. La fenêtre de console affiche les valeurs de configuration pour Profile:MachineName et App:MainWindow:Left :The console window displays the configuration values for Profile:MachineName and App:MainWindow:Left:

MachineName: ChadPC
Left: 1988

fichier web.configweb.config file

Un fichier web.config est nécessaire pour héberger l’application dans IIS ou IIS Express.A web.config file is required when hosting the app in IIS or IIS Express. Les paramètres de web.config permettent au module ASP.NET Core de lancer l’application et de configurer d’autres modules et paramètres IIS.Settings in web.config enable the ASP.NET Core Module to launch the app and configure other IIS settings and modules. Si le fichier web.config n’est pas présent et que le fichier projet contient <Project Sdk="Microsoft.NET.Sdk.Web">, la publication du projet crée un fichier web.config dans la sortie publiée (le dossier publish).If the web.config file isn't present and the project file includes <Project Sdk="Microsoft.NET.Sdk.Web">, publishing the project creates a web.config file in the published output (the publish folder). Pour plus d’informations, consultez Héberger ASP.NET Core sur Windows avec IIS.For more information, see Host ASP.NET Core on Windows with IIS.

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

Pour accéder à la configuration dans ConfigureServices ou Configure au démarrage, consultez les exemples dans la rubrique Démarrage de l’application.To access configuration within ConfigureServices or Configure during startup, see the examples in the Application startup topic.

Ajout de la configuration à partir d’un assembly externeAdding configuration from an external assembly

L’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 Améliorer une application à partir d’un assembly externe.For more information, see Enhance an app from an external assembly.

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

Pour accéder aux paramètres de configuration dans une page Pages Razor ou une vue MVC, ajoutez une directive using (Informations de référence sur C# : directive using) pour l’espace de noms Microsoft.Extensions.Configuration et injectez IConfiguration dans la page ou la vue.To access configuration settings in a Razor Pages page or an MVC view, add a using directive (C# reference: using directive) for the Microsoft.Extensions.Configuration namespace and inject IConfiguration into the page or view.

Dans une page Pages Razor :In a Razor Pages page:

@page
@model IndexModel

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Index Page</title>
</head>
<body>
    <h1>Access configuration in a Razor Pages page</h1>
    <p>Configuration[&quot;key&quot;]: @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[&quot;key&quot;]: @Configuration["key"]</p>
</body>
</html>

Remarques supplémentairesAdditional notes

  • L’injection de dépendances n’est pas définie tant que ConfigureServices n’est pas appelé.Dependency Injection (DI) isn't set up until after ConfigureServices is invoked.
  • Le système de configuration ne prend pas en charge l’injection de dépendances.The configuration system isn't DI aware.
  • IConfiguration a deux spécialisations :IConfiguration has two specializations:
    • IConfigurationRoot Utilisé pour le nœud racine.IConfigurationRoot Used for the root node. Peut déclencher un rechargement.Can trigger a reload.
    • IConfigurationSection Représente une section de valeurs de configuration.IConfigurationSection Represents a section of configuration values. Les méthodes GetSection et GetChildren retournent un IConfigurationSection.The GetSection and GetChildren methods return an IConfigurationSection.
    • Utilisez IConfigurationRoot quand vous rechargez la configuration ou accéder à chaque fournisseur.Use IConfigurationRoot when reloading configuration or for access to each provider. Aucune de ces situations n’est courante.Neither of these situations are common.

Ressources supplémentairesAdditional resources