Configuration dans ASP.NET Core

Par Rick Anderson et Kirk Larkin

La configuration dans ASP.NET Core est effectuée à l’aide d’un ou de plusieurs fournisseurs de configuration. Les fournisseurs de configuration lisent les données de configuration des paires clé-valeur à l’aide d’une variété de sources de configuration :

  • Les fichiers de paramètres, tels que appsettings.json
  • Variables d'environnement
  • Azure Key Vault
  • Azure App Configuration
  • Arguments de ligne de commande
  • Fournisseurs personnalisés, installés ou créés
  • Fichiers de répertoire
  • Objets .NET en mémoire

Cette rubrique fournit des informations sur la configuration dans ASP.NET Core. Pour plus d’informations sur l’utilisation de la configuration dans les applications console, consultez Configuration .net.

Afficher ou télécharger l’exemple de code (procédure de téléchargement)

Configuration par défaut

ASP.NET Core les applications Web créées avec dotnet New ou Visual Studio génèrent le code suivant :

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 :

  1. ChainedConfigurationProvider : ajoute un existant IConfiguration en tant que 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 .
  2. appsettings.json utilisation du fournisseur de configuration JSON.
  3. appSettings. Environment . JSON à l’aide du fournisseur de configuration JSON. Par exemple, appSettings. Production * * _._json et appSettings. * * * développement _._json *.
  4. Secrets d’application lorsque l’application s’exécute dans l' Development environnement.
  5. Variables d’environnement à l’aide du fournisseur de configuration des variables d’environnement.
  6. Arguments de ligne de commande à l’aide du fournisseur de configuration de ligne de commande.

Les fournisseurs de configuration ajoutés ultérieurement remplacent les paramètres de clé précédents. Par exemple, si MyKey est défini à la fois dans appsettings.json et dans l’environnement, la valeur d’environnement est utilisée. À l’aide des fournisseurs de configuration par défaut, le fournisseur de configuration de ligne de commande remplace tous les autres fournisseurs.

Pour plus d’informations sur CreateDefaultBuilder , consultez paramètres par défaut du générateur.

Le code suivant affiche les fournisseurs de configuration activés dans l’ordre dans lequel ils ont été ajoutés :

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 :

{
    "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 :

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 :

  1. appsettings.json
  2. appSettings. Environment . JSON : par exemple, appSettings. Les fichiers de production * * _._json et appSettings. * * * Development _._json *. La version de l’environnement du fichier est chargée à partir de IHostingEnvironment. EnvironmentName. Pour plus d’informations, consultez Utiliser plusieurs environnements dans ASP.NET Core.

appSettings. Environment . les valeurs JSON remplacent les clés dans appsettings.json . Par exemple, par défaut :

  • Dans le développement, appSettings. *Development _._json * configuration remplace les valeurs trouvées dans appsettings.json .
  • En production, appSettings. *production _._json * configuration remplace les valeurs trouvées dans appsettings.json . Par exemple, lors du déploiement de l’application sur Azure.

Si une valeur de configuration doit être garantie, consultez GetValue. L’exemple précédent lit uniquement des chaînes et ne prend pas en charge de valeur par défaut

Lier des données de configuration hiérarchiques à l’aide du modèle options

La méthode recommandée pour lire les valeurs de configuration associées utilise le modèle d’options. Par exemple, pour lire les valeurs de configuration suivantes :

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

Créez la PositionOptions classe suivante :

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

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

Une classe d’options :

  • Doit être non abstract avec un constructeur sans paramètre public.
  • Toutes les propriétés publiques en lecture/écriture du type sont liées.
  • Les champs ne sont pas liés. Dans le code précédent, Position n’est pas lié. 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.

Le code suivant :

  • Appelle ConfigurationBinder. bind pour lier la PositionOptions classe à la Position section.
  • Affiche les Position données de configuration.
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.

ConfigurationBinder.Get<T> lie et retourne le type spécifié. ConfigurationBinder.Get<T> peut être plus pratique que l’utilisation de ConfigurationBinder.Bind . Le code suivant montre comment utiliser ConfigurationBinder.Get<T> avec la PositionOptions classe :

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.

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. Dans le code suivant, PositionOptions est ajouté au conteneur de services avec <xref:Microsoft.Extensions.DependencyInjection.OptionsConfigurationServiceCollectionExtensions.Configure_> et lié à la 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 :

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. Pour lire les modifications une fois l’application démarrée, utilisez 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. 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.

Pour plus d’informations sur l’ajout de fichiers de configuration JSON supplémentaires, consultez fournisseur de configuration JSON dans ce document.

Combinaison de la collection de services

Considérez la ConfigureServices méthode suivante, qui inscrit les services et configure les 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. Par exemple, les services de configuration sont ajoutés à la classe suivante :

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. La ConfigureServices méthode suivante utilise les nouvelles méthodes d’extension pour inscrire les 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. Par exemple, AddControllersWithViews ajoute les services MVC dont les vues ont besoin et AddRazorPages ajoute les pages de services Razor requis. Nous vous recommandons d’appliquer cette Convention d’affectation de noms aux applications. Placez les méthodes d’extension dans l’espace de noms Microsoft.Extensions.DependencyInjection pour encapsuler des groupes d’inscriptions de service.

Sécurité et secrets de l’utilisateur

Instructions relatives aux données de configuration :

  • 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. L’outil Gestionnaire de secret peut être utilisé pour stocker les secrets en développement.
  • N’utilisez aucun secret de production dans les environnements de développement ou de test.
  • 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.

Par défaut, la source de configuration des secrets de l’utilisateur est inscrite après les sources de configuration JSON. Par conséquent, les clés de secrets d’utilisateur sont prioritaires sur les clés dans appsettings.json et appSettings. Environment . JSON.

Pour plus d’informations sur le stockage des mots de passe ou d’autres données sensibles :

Azure Key Vault stocke en toute sécurité des secrets d’application pour les applications ASP.NET Core. Pour plus d’informations, consultez Fournisseur de configuration Azure Key Vault dans ASP.NET Core.

Variables d'environnement

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

Le : séparateur ne fonctionne pas avec les clés hiérarchiques de variable d’environnement sur toutes les plateformes. __, le double trait de soulignement, est :

  • Pris en charge par toutes les plateformes. Par exemple, le : séparateur n’est pas pris en charge par bash, mais __ est.
  • Automatiquement remplacé par un :

Les set commandes suivantes :

  • Définissez les clés et les valeurs d’environnement de l' exemple précédent sur Windows.
  • Testez les paramètres lors de l’utilisation de l' exemple de téléchargement. La dotnet run commande doit être exécutée dans le répertoire du projet.
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 :

  • Sont uniquement définies dans les processus lancés à partir de la fenêtre de commande dans laquelle ils ont été définis.
  • Ne seront pas lues par les navigateurs lancés avec Visual Studio.

Les commandes setx suivantes peuvent être utilisées pour définir les clés et les valeurs d’environnement sur Windows. Contrairement à set , setx les paramètres sont conservés. /M définit la variable dans l’environnement système. Si le /M commutateur n’est pas utilisé, une variable d’environnement utilisateur est définie.

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:

  • Avec Visual Studio : quittez et redémarrez Visual Studio.
  • Avec l’interface CLI : démarrez une nouvelle fenêtre de commande et entrez dotnet run .

Appelez AddEnvironmentVariables avec une chaîne pour spécifier un préfixe pour les variables d’environnement :

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 :

Le préfixe est supprimé lorsque les paires clé-valeur de configuration sont lues.

Les commandes suivantes testent le préfixe personnalisé :

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_ . 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. Pour plus d’informations sur la configuration de l’hôte et de l’application, consultez hôte générique .net.

Dans Azure App service, sélectionnez nouveau paramètre d’application dans la page paramètres > configuration . Azure App Service paramètres de l’application sont les suivants :

  • Chiffré au repos et transmis sur un canal chiffré.
  • Exposés en tant que variables d’environnement.

Pour plus d’informations, consultez Azure Apps : remplacer la configuration de l’application à l’aide du portail Azure.

Consultez préfixes de chaîne de connexion pour plus d’informations sur les chaînes de connexion de base de données Azure.

Affectation des noms de variables d’environnement

Les noms des variables d’environnement reflètent la structure d’un appsettings.json fichier. Chaque élément de la hiérarchie est séparé par un trait de soulignement double (préférable) ou par deux-points. 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. Considérez le appsettings.json fichier suivant et ses valeurs équivalentes représentées sous la forme de variables d’environnement.

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’environnement

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 sur

Les variables d’environnement définies dans launchSettings.jslors de la substitution de celles définies dans l’environnement système. 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 :

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

Variables d’environnement d’échappement sur 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. Utiliser l’outil Linux systemd-escape qui génère http:--localhost:5001

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

Afficher les variables d’environnement

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 :

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 commande

À 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 :

  • appsettings.json et appSettings. Environment . fichiers JSON .
  • Secrets de l’application dans l’environnement de développement.
  • Variables d'environnement.

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.

Arguments de ligne de commande

La commande suivante définit des clés et des valeurs à l’aide de = :

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 / :

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

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

Valeur de la clé :

  • Doit suivre = ou la clé doit avoir un préfixe -- ou / lorsque la valeur suit un espace.
  • N’est pas obligatoire si = est utilisé. Par exemple : 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.

Correspondances de commutateur

Les mappages de commutateur autorisent la logique de remplacement de nom de clé . Fournissez un dictionnaire de remplacements de commutateur dans la AddCommandLine méthode.

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. 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. Une correspondance de commutateur est nécessaire pour chaque clé de ligne de commande préfixée avec un tiret unique (-).

Règles des clés du dictionnaire de correspondances de commutateur :

  • Les commutateurs doivent commencer par - ou -- .
  • Le dictionnaire de correspondances de commutateur ne doit pas contenir de clés en double.

Pour utiliser un dictionnaire de mappages de commutateur, transmettez-le à l’appel à 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 :

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é :

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

Données de configuration hiérarchiques

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.

L' exemple de téléchargement contient le appsettings.json fichier suivant :

{
    "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 :

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. Pour plus d’informations, consultez lier des données de configuration hiérarchiques dans ce 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. Ces méthodes sont décrites plus loin dans GetSection, GetChildren et Exists.

Clés et valeurs de configuration

Clés de configuration :

  • Ne respectent pas la casse. Par exemple, ConnectionString et connectionstring sont traités en tant que clés équivalentes.
  • Si une clé et une valeur sont définies dans plusieurs fournisseurs de configuration, la valeur du dernier fournisseur ajouté est utilisée. Pour plus d’informations, consultez configuration par défaut.
  • Clés hiérarchiques
    • Dans l’API Configuration, un séparateur sous forme de signe deux-points (:) fonctionne sur toutes les plateformes.
    • Dans les variables d’environnement, un séparateur sous forme de signe deux-points peut ne pas fonctionner sur toutes les plateformes. Un trait de soulignement double, __ , est pris en charge par toutes les plateformes et est automatiquement converti en deux-points : .
    • Dans Azure Key Vault, les clés hiérarchiques utilisent -- comme séparateur. Le fournisseur de configuration Azure Key Vault remplace automatiquement -- par un : lorsque les secrets sont chargés dans la configuration de l’application.
  • ConfigurationBinder prend en charge la liaison de tableaux à des objets à l’aide d’index de tableau dans les clés de configuration. La liaison de tableau est décrite dans la section Lier un tableau à une classe.

Valeurs de configuration :

  • Sont des chaînes.
  • Les valeurs NULL ne peuvent pas être stockées dans la configuration ou liées à des objets.

Fournisseurs de configuration

Le tableau suivant présente les fournisseurs de configuration disponibles pour les applications ASP.NET Core.

Fournisseur Fournit la configuration à partir de
Fournisseur de configuration Azure Key Vault Azure Key Vault
Fournisseur de configuration Azure App Azure App Configuration
Fournisseur de configuration de ligne de commande Paramètres de ligne de commande
Fournisseur de configuration personnalisé Source personnalisée
Fournisseur de configuration des variables d’environnement Variables d'environnement
Fournisseur de configuration de fichier Fichiers INI, JSON et XML
Fournisseur de configuration de clé par fichier Fichiers de répertoire
Fournisseur de configuration de la mémoire Collections en mémoire
Secrets utilisateur Fichier dans le répertoire de profil utilisateur

Les sources de configuration sont lues dans l’ordre dans lequel leurs fournisseurs de configuration sont spécifiés. Commandez des fournisseurs de configuration dans le code pour répondre aux priorités des sources de configuration sous-jacentes requises par l’application.

Une séquence type des fournisseurs de configuration est la suivante :

  1. appsettings.json
  2. appSettings. Environment . JSON
  3. Secrets utilisateur
  4. Variables d’environnement à l’aide du fournisseur de configuration des variables d’environnement.
  5. Arguments de ligne de commande à l’aide du fournisseur de configuration de ligne de commande.

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.

La séquence de fournisseurs précédente est utilisée dans la configuration par défaut.

Préfixes des chaînes de connexion

L’API de configuration a des règles de traitement spéciales pour quatre variables d’environnement de chaîne de connexion. Ces chaînes de connexion sont impliquées dans la configuration des chaînes de connexion Azure pour l’environnement de l’application. 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 .

Préfixe de la chaîne de connexion Fournisseur
CUSTOMCONNSTR_ Fournisseur personnalisé
MYSQLCONNSTR_ MySQL
SQLAZURECONNSTR_ Azure SQL Database
SQLCONNSTR_ SQL 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 :

  • 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).
  • 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é).
Clé de variable d’environnement Clé de configuration convertie Entrée de configuration de fournisseur
CUSTOMCONNSTR_{KEY} ConnectionStrings:{KEY} Entrée de configuration non créée.
MYSQLCONNSTR_{KEY} ConnectionStrings:{KEY} Clé : ConnectionStrings:{KEY}_ProviderName :
Valeur : MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY} ConnectionStrings:{KEY} Clé : ConnectionStrings:{KEY}_ProviderName :
Valeur : System.Data.SqlClient
SQLCONNSTR_{KEY} ConnectionStrings:{KEY} Clé : ConnectionStrings:{KEY}_ProviderName :
Valeur : System.Data.SqlClient

Fournisseur de configuration de fichier

FileConfigurationProvider est la classe de base pour charger la configuration à partir du système de fichiers. Les fournisseurs de configuration suivants dérivent de FileConfigurationProvider :

Fournisseur de configuration INI

IniConfigurationProvider charge la configuration à partir des paires clé-valeur du fichier INI lors de l’exécution.

Le code suivant efface tous les fournisseurs de configuration et ajoute plusieurs fournisseurs de configuration :

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 :

L' exemple de téléchargement contient le fichier MyIniConfig.ini suivant :

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 :

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 JSON

Le JsonConfigurationProvider charge la configuration à partir de paires clé-valeur de fichier JSON.

Les surcharges peuvent spécifier :

  • Si le fichier est facultatif.
  • Si la configuration est rechargée quand le fichier est modifié.

Considérez le code suivant :

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 :

  • Configure le fournisseur de configuration JSON pour charger le MyConfig.jssur le fichier avec les options suivantes :
    • optional: true: Le fichier est facultatif.
    • reloadOnChange: true : Le fichier est rechargé lorsque des modifications sont enregistrées.
  • Lit les fournisseurs de configuration par défaut avant l' MyConfig.jssur le fichier. Les paramètres dans le MyConfig.js paramètre de remplacement de fichier dans les fournisseurs de configuration par défaut, y compris le fournisseur de configuration des variables d’environnement et le fournisseur de configuration de ligne de commande.

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.

Le code suivant efface tous les fournisseurs de configuration et ajoute plusieurs fournisseurs de configuration :

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 :

L' exemple de téléchargement contient les MyConfig.jssuivantes sur le fichier :

{
    "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 :

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 XML

XmlConfigurationProvider charge la configuration à partir des paires clé-valeur du fichier XML lors de l’exécution.

Le code suivant efface tous les fournisseurs de configuration et ajoute plusieurs fournisseurs de configuration :

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 :

L' exemple de téléchargement contient le fichier MyXMLFile.xml suivant :

<?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 :

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 :

<?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 :

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 :

<?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 :

  • key:attribute
  • section:key:attribute

Fournisseur de configuration de clé par fichier

Le KeyPerFileConfigurationProvider utilise les fichiers d’un répertoire en tant que paires clé-valeur de configuration. La clé est le nom de fichier. La valeur contient le contenu du fichier. Le fournisseur de configuration par fichier clé est utilisé dans les scénarios d’hébergement de l’ancrage.

Pour activer la configuration clé par fichier, appelez la méthode d’extension AddKeyPerFile sur une instance de ConfigurationBuilder. Le directoryPath aux fichiers doit être un chemin d’accès absolu.

Les surcharges permettent de spécifier :

  • Un délégué Action<KeyPerFileConfigurationSource> qui configure la source.
  • Si le répertoire est facultatif et le chemin d’accès au répertoire.

Le double trait de soulignement (__) est utilisé comme un délimiteur de clé de configuration dans les noms de fichiers. Par exemple, le nom de fichier Logging__LogLevel__System génère la clé de configuration Logging:LogLevel:System.

Appelez ConfigureAppConfiguration lors de la création de l’hôte pour spécifier la configuration de l’application :

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

Fournisseur de configuration de la mémoire

Le MemoryConfigurationProvider utilise une collection en mémoire en tant que paires clé-valeur de configuration.

Le code suivant ajoute une collection de mémoire au système de configuration :

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 :

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. Pour obtenir un exemple de classement des fournisseurs de configuration, consultez fournisseur de configuration JSON.

Pour un autre exemple, consultez lier un tableau à l’aide de MemoryConfigurationProvider .

Kestrel configuration du point de terminaison

Kestrel la configuration d’un point de terminaison spécifique remplace toutes les configurations de point de terminaison inter-serveurs . Les configurations de point de terminaison entre serveurs sont les suivantes :

Considérez le appsettings.json fichier suivant utilisé dans une application web ASP.net Core :

{
  "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 :

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 .

Considérez le Kestrel point de terminaison spécifique configuré comme une variable d’environnement :

set Kestrel__Endpoints__Https__Url=https://localhost:8888

Dans la variable d’environnement précédente, Https est le nom du Kestrel point de terminaison spécifique. Le appsettings.json fichier précédent définit également un Kestrel point de terminaison spécifique nommé 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.

GetValue

ConfigurationBinder.GetValue<T> extrait une valeur unique de la configuration avec une clé spécifiée et la convertit en type spécifié :

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.

GetSection, GetChildren et Exists

Pour les exemples qui suivent, prenez en compte les MySubsection.jssuivantes sur le fichier :

{
  "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 :

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

GetSection

IConfiguration. GetSection retourne une sous-section de configuration avec la clé de sous-section spécifiée.

Le code suivant retourne des valeurs pour 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 :

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. Si aucune section correspondante n’est trouvée, une valeur IConfigurationSection vide est retournée.

Quand GetSection retourne une section correspondante, Value n’est pas rempli. Key et Path sont retournés quand la section existe.

GetChildren et EXISTS

Le code suivant appelle IConfiguration. GetChildren et retourne des valeurs pour 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 :

Lier un tableau

ConfigurationBinder. bind prend en charge les tableaux de liaison aux objets à l’aide d’index de tableau dans les clés de configuration. 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 .

Prenez MyArray.js à partir de l' exemple de téléchargement:

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

Le code suivant ajoute MyArray.js aux fournisseurs de configuration :

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 :

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 :

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. Les index de tableau liés sont continus et non liés à l’index de clé de configuration. Le Binder de configuration n’est pas en capacité à lier des valeurs null ou à créer des entrées NULL dans des objets liés

Le code suivant charge la array:entries configuration avec la AddInMemoryCollection méthode d’extension :

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 :

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 :

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

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. Examinez le Value3.jssuivant sur le fichier à partir de l’exemple de téléchargement :

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

Le code suivant comprend la configuration de Value3.jssur et 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 :

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 :

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.

Fournisseur de configuration personnalisé

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

Le fournisseur présente les caractéristiques suivantes :

  • La base de données en mémoire EF est utilisée à des fins de démonstration. 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.
  • Le fournisseur lit une table de base de données dans la configuration au démarrage. Le fournisseur n’interroge pas la base de données par clé.
  • 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.

Définissez une entité EFConfigurationValue pour le stockage des valeurs de configuration dans la base de données.

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.

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.

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. Le fournisseur de configuration initialise la base de données quand elle est vide. É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).

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.

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 :

// 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émarrage

Le code suivant affiche les données de configuration dans les Startup méthodes :

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.

Configuration de l’accès dans les Razor pages

Le code suivant affiche les données de configuration dans une 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 :

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 :

@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 MVC

Le code suivant affiche les données de configuration dans une vue MVC :

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

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

Configurer des options avec un délégué

Les options configurées dans un délégué remplacent les valeurs définies dans les fournisseurs de configuration.

La configuration d’options avec un délégué est illustrée dans l’exemple 2 de l’exemple d’application.

Dans le code suivant, un IConfigureOptions<TOptions> service est ajouté au conteneur de services. Il utilise un délégué pour configurer des valeurs pour 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 :

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

Configuration de l’hôte ou configuration de l’application

Avant que l’application ne soit configurée et démarrée, un hôte est configuré et lancé. L’hôte est responsable de la gestion du démarrage et de la durée de vie des applications. L’application et l’hôte sont configurés à l’aide des fournisseurs de configuration décrits dans cette rubrique. Les paires clé-valeur de la configuration de l’hôte sont également incluses dans la configuration de l’application. 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.

Configuration de l’hôte par défaut

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.

  • La configuration de l’hôte est fournie à partir des éléments suivants :
  • La configuration par défaut de l’hôte Web est établie (ConfigureWebHostDefaults) :
    • Kestrel est utilisé en tant que serveur Web et configuré à l’aide des fournisseurs de configuration de l’application.
    • Ajoutez l’intergiciel de filtrage d’hôtes.
    • Ajoutez l’intergiciel d’en-têtes transférés si la variable d'environnement ASPNETCORE_FORWARDEDHEADERS_ENABLED est définie sur true.
    • Activez l’intégration d’IIS.

Autre configuration

Cette rubrique se rapporte uniquement à la configuration de l' application. 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 :

Les variables d’environnement définies dans launchSettings.jslors de la substitution de celles définies dans l’environnement système.

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 .

Ajouter la configuration à partir d’un assembly externe

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. Pour plus d’informations, consultez Utiliser des assemblys de démarrage d’hébergement dans ASP.NET Core.

Ressources supplémentaires

La configuration d’application dans ASP.NET Core est basée sur des paires clé-valeur établies par les fournisseurs de configuration. Les fournisseurs de configuration lisent les données de configuration dans les paires clé-valeur à partir de diverses sources de configuration :

  • Azure Key Vault
  • Azure App Configuration
  • Arguments de ligne de commande
  • Fournisseurs personnalisés (installés ou créés)
  • Fichiers de répertoire
  • Variables d'environnement
  • Objets .NET en mémoire
  • Fichiers de paramètres

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.

Les exemples de code qui suivent et dans l’échantillon d’application utilisent l’espace de noms Microsoft.Extensions.Configuration :

using Microsoft.Extensions.Configuration;

Le modèle d’options est une extension des concepts de configuration décrits dans cette rubrique. Les options utilisent des classes pour représenter les groupes de paramètres associés. Pour plus d’informations, consultez Modèle d’options dans ASP.NET Core.

Afficher ou télécharger l’exemple de code (procédure de téléchargement)

Configuration de l’hôte ou configuration de l’application

Avant que l’application ne soit configurée et démarrée, un hôte est configuré et lancé. L’hôte est responsable de la gestion du démarrage et de la durée de vie des applications. L’application et l’hôte sont configurés à l’aide des fournisseurs de configuration décrits dans cette rubrique. Les paires clé-valeur de la configuration de l’hôte sont également incluses dans la configuration de l’application. 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.

Autre configuration

Cette rubrique se rapporte uniquement à la configuration de l' application. 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 :

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 .

Configuration par défaut

Les applications web basées sur les modèles ASP.NET Core dotnet new appellent CreateDefaultBuilder pendant la création d’un hôte. CreateDefaultBuilder fournit la configuration par défaut de l’application dans l’ordre suivant :

Les éléments suivants s’appliquent aux applications qui utilisent l’hôte web. 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.

Sécurité

Adoptez les pratiques suivantes pour sécuriser les données de configuration sensibles :

  • 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.
  • N’utilisez aucun secret de production dans les environnements de développement ou de test.
  • 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.

Pour plus d'informations, voir les rubriques suivantes :

Azure Key Vault stocke en toute sécurité des secrets d’application pour les applications ASP.NET Core. Pour plus d’informations, consultez Fournisseur de configuration Azure Key Vault dans ASP.NET Core.

Données de configuration hiérarchiques

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.

Dans le fichier JSON suivant, quatre clés existent dans une structure hiérarchique à deux 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. Les sections et les clés sont aplanies à l’aide d’un signe deux-points (:) pour conserver la structure d’origine :

  • section0:key0
  • section0:key1
  • section1:key0
  • section1: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. Ces méthodes sont décrites plus loin dans GetSection, GetChildren et Exists.

Conventions

Sources et fournisseurs

Au démarrage de l’application, les sources de configuration sont lues dans l’ordre où leurs fournisseurs de configuration sont spécifiés.

Les fournisseurs de configuration qui implémentent la détection des modifications peuvent recharger la configuration lorsqu’un paramètre sous-jacent est modifié. 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.

IConfiguration est disponible dans le conteneur d’injection de dépendances de l’application. IConfiguration peut être injecté dans une Razor page PageModel ou un MVC Controller pour obtenir la configuration de la classe.

Dans les exemples suivants, le _config champ est utilisé pour accéder aux valeurs de configuration :

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.

Keys

Les clés de configuration adoptent les conventions suivantes :

  • Les clés ne respectent pas la casse. Par exemple, ConnectionString et connectionstring sont traités en tant que clés équivalentes.
  • 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é. Pour plus d’informations sur les clés JSON en double, consultez ce problème GitHub.
  • Clés hiérarchiques
    • Dans l’API Configuration, un séparateur sous forme de signe deux-points (:) fonctionne sur toutes les plateformes.
    • Dans les variables d’environnement, un séparateur sous forme de signe deux-points peut ne pas fonctionner sur toutes les plateformes. Un trait de soulignement double (__) est pris en charge par toutes les plateformes et automatiquement transformé en signe deux-points.
    • Dans Azure Key Vault, les clés hiérarchiques utilisent -- (deux tirets) comme séparateur. Écrivez du code pour remplacer les tirets par un signe deux-points lorsque les secrets sont chargés dans la configuration de l’application.
  • ConfigurationBinder prend en charge la liaison de tableaux à des objets à l’aide d’index de tableau dans les clés de configuration. La liaison de tableau est décrite dans la section Lier un tableau à une classe.

Valeurs

Les valeurs de configuration adoptent les conventions suivantes :

  • Les valeurs sont des chaînes.
  • Les valeurs NULL ne peuvent pas être stockées dans la configuration ou liées à des objets.

Fournisseurs

Le tableau suivant présente les fournisseurs de configuration disponibles pour les applications ASP.NET Core.

Fournisseur Fournit la configuration à partir de…
Fournisseur de configuration Azure Key Vault (rubrique Sécurité) Azure Key Vault
Fournisseur Azure App Configuration (documentation Azure) Azure App Configuration
Fournisseur de configuration de ligne de commande Paramètres de ligne de commande
Fournisseur de configuration personnalisé Source personnalisée
Fournisseur de configuration de variables d’environnement Variables d'environnement
Fournisseur de configuration de fichier Fichiers (INI, JSON, XML)
Fournisseur de configuration clé par fichier Fichiers de répertoire
Fournisseur de configuration de mémoire Collections en mémoire
Secrets de l’utilisateur (rubriques relatives à la sécurité ) Fichier dans le répertoire de profil utilisateur

Au démarrage, les sources de configuration sont lues dans l’ordre où leurs fournisseurs de configuration sont spécifiés. 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. Commandez des fournisseurs de configuration dans le code pour répondre aux priorités des sources de configuration sous-jacentes requises par l’application.

Une séquence type des fournisseurs de configuration est la suivante :

  1. Fichiers ( appsettings.json , appSettings. { Environment}. JSON, où {Environment} est l’environnement d’hébergement actuel de l’application)
  2. Azure Key Vault
  3. Secrets de l’utilisateur (environnement de développement uniquement)
  4. Variables d'environnement
  5. Arguments de ligne de commande

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.

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 . Pour plus d’informations, consultez la section Configuration par défaut.

Configurer le générateur d’ordinateur hôte avec UseConfiguration

Pour configurer le générateur d’ordinateur hôte, appelez UseConfiguration sur le générateur d’hôte avec la 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>();
}

ConfigureAppConfiguration

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 :

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 commande

Pour fournir une configuration d’application pouvant être remplacée par des arguments de ligne de commande, appelez AddCommandLine en dernier :

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

Supprimer les fournisseurs ajoutés par CreateDefaultBuilder

Pour supprimer les fournisseurs ajoutés par CreateDefaultBuilder , appelez d’abord Clear sur IConfigurationBuilder. sources :

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

Utiliser la configuration lors du démarrage de l’application

La configuration fournie à l’application dans ConfigureAppConfiguration est disponible lors du démarrage de l’application, notamment Startup.ConfigureServices. Pour plus d’informations, consultez la section Accéder à la configuration lors du démarrage.

Fournisseur de configuration de ligne de commande

CommandLineConfigurationProvider charge la configuration à partir des paires clé-valeur de l’argument de ligne de commande lors de l’exécution.

Pour activer la configuration en ligne de commande, la méthode d’extension AddCommandLine est appelée sur une instance de ConfigurationBuilder.

AddCommandLine est appelé automatiquement quand CreateDefaultBuilder(string []) est appelé. Pour plus d’informations, consultez la section Configuration par défaut.

CreateDefaultBuilder charge également :

  • Configuration facultative à partir de appsettings.json et appSettings. { Fichiers Environment}. JSON .
  • Secrets de l’utilisateur dans l’environnement de développement.
  • Variables d'environnement.

CreateDefaultBuilder ajoute en dernier le Fournisseur de configuration de ligne de commande. Les arguments de ligne de commande passés lors de l’exécution remplacent la configuration définie par les autres fournisseurs.

CreateDefaultBuilder agit lors de la construction de l’hôte. Par conséquent, la configuration de ligne de commande activée par CreateDefaultBuilder peut affecter la façon dont l’hôte est configuré.

Pour les applications basées sur les modèles ASP.NET Core, AddCommandLine a déjà été appelé par 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.

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

Exemple

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.

  1. Ouvrez une invite de commandes dans le répertoire du projet.
  2. Fournissez un argument de ligne de commande à la commande dotnet run, 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.
  4. Notez que la sortie contient la paire clé-valeur pour l’argument de ligne de commande de configuration fourni à dotnet run.

Arguments

La valeur doit suivre un signe égal (=) ou la clé doit avoir un préfixe (-- ou /) lorsque la valeur suit un espace. La valeur n’est pas requise si un signe égal est utilisé (par exemple, CommandLineKey=).

Préfixe de clé Exemple
Aucun préfixe CommandLineKey1=value1
Deux tirets (--) --CommandLineKey2=value2, --CommandLineKey2 value2
Barre oblique (/) /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.

Exemples de commandes :

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

Correspondances de commutateur

Les correspondances de commutateur permettent une logique de remplacement des noms de clés. Lors de la génération manuelle d’une configuration avec un ConfigurationBuilder , fournissez un dictionnaire de remplacements de commutateur à la AddCommandLine méthode.

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. 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. Une correspondance de commutateur est nécessaire pour chaque clé de ligne de commande préfixée avec un tiret unique (-).

Règles des clés du dictionnaire de correspondances de commutateur :

  • Les commutateurs doivent commencer par un tiret (-) ou un double tiret (--).
  • Le dictionnaire de correspondances de commutateur ne doit pas contenir de clés en double.

Créez un dictionnaire des mappages de commutateurs. Dans l’exemple suivant, deux mappages de commutateurs sont créés :

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 :

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

Une fois le dictionnaire de correspondances de commutateur créé, il contient les données affichées dans le tableau suivant.

Clé Valeur
-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 :

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.

Clé Valeur
CommandLineKey1 value1
CommandLineKey2 value2

Fournisseur de configuration de variables d’environnement

EnvironmentVariablesConfigurationProvider charge la configuration à partir des paires clé-valeur de la variable d’environnement lors de l’exécution.

Pour activer la configuration des variables d’environnement, appelez la méthode d’extension AddEnvironmentVariables sur une instance de ConfigurationBuilder.

Le : séparateur ne fonctionne pas avec les clés hiérarchiques de variable d’environnement sur toutes les plateformes. __, le double trait de soulignement, est :

  • Pris en charge par toutes les plateformes. Par exemple, le : séparateur n’est pas pris en charge par bash, mais __ est.
  • Automatiquement remplacé par un :

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. Pour plus d’informations, consultez Azure Apps : remplacer la configuration de l’application à l’aide du portail Azure.

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é. Pour plus d’informations, consultez la section Configuration par défaut.

CreateDefaultBuilder charge également :

  • Configuration de l’application à partir de variables d’environnement sans préfixe en appelant AddEnvironmentVariables sans préfixe.
  • Configuration facultative à partir de appsettings.json et appSettings. { Fichiers Environment}. JSON .
  • Secrets de l’utilisateur dans l’environnement de développement.
  • Arguments de ligne de commande

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

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 :

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

Exemple

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.

  1. Exécutez l’exemple d’application. Ouvrez un navigateur vers l’application avec l’adresse http://localhost:5000.
  2. Notez que la sortie contient la paire clé-valeur pour la variable d’environnement 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.

Pour que la liste des variables d’environnement restituée par l’application soit courte, l’application filtre les variables d’environnement. Consultez le fichier Pages/Index.cshtml.cs de l’exemple d’application.

Pour exposer toutes les variables d’environnement disponibles pour l’application, remplacez FilteredConfiguration dans pages/index. cshtml. cs par ce qui suit :

FilteredConfiguration = _config.AsEnumerable();

Préfixes

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. Par exemple, pour filtrer les variables d’environnement sur le préfixe CUSTOM_, fournissez le préfixe au fournisseur de configuration :

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

Le préfixe est supprimé lorsque les paires clé-valeur de la configuration sont créées.

Lorsque le générateur d’hôte est créé, la configuration de l’hôte est fournie par des variables d’environnement. Pour plus d’informations sur le préfixe utilisé pour ces variables d’environnement, consultez la section Configuration par défaut.

Préfixes des chaînes de connexion

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

Préfixe de la chaîne de connexion Fournisseur
CUSTOMCONNSTR_ Fournisseur personnalisé
MYSQLCONNSTR_ MySQL
SQLAZURECONNSTR_ Azure SQL Database
SQLCONNSTR_ SQL 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 :

  • 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).
  • 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é).
Clé de variable d’environnement Clé de configuration convertie Entrée de configuration de fournisseur
CUSTOMCONNSTR_{KEY} ConnectionStrings:{KEY} Entrée de configuration non créée.
MYSQLCONNSTR_{KEY} ConnectionStrings:{KEY} Clé : ConnectionStrings:{KEY}_ProviderName :
Valeur : MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY} ConnectionStrings:{KEY} Clé : ConnectionStrings:{KEY}_ProviderName :
Valeur : System.Data.SqlClient
SQLCONNSTR_{KEY} ConnectionStrings:{KEY} Clé : ConnectionStrings:{KEY}_ProviderName :
Valeur : System.Data.SqlClient

Exemple

Une variable d’environnement de chaîne de connexion personnalisée est créée sur le serveur :

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

Si IConfiguration est injecté et affecté à un champ nommé _config , lisez la valeur :

_config["ConnectionStrings:ReleaseDB"]

Fournisseur de configuration de fichier

FileConfigurationProvider est la classe de base pour charger la configuration à partir du système de fichiers. Les fournisseurs de configuration suivants sont dédiés à des types de fichiers spécifiques :

Fournisseur de configuration INI

IniConfigurationProvider charge la configuration à partir des paires clé-valeur du fichier INI lors de l’exécution.

Pour activer la configuration du fichier INI, appelez la méthode d’extension AddIniFile sur une instance de ConfigurationBuilder.

Le signe deux-points peut servir de délimiteur de section dans la configuration d’un fichier INI.

Les surcharges permettent de spécifier :

  • Si le fichier est facultatif.
  • Si la configuration est rechargée quand le fichier est modifié.
  • Le IFileProvider utilisé pour accéder au fichier.

Appelez ConfigureAppConfiguration lors de la création de l’hôte pour spécifier la configuration de l’application :

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

Exemple générique d’un fichier de configuration INI :

[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 :

  • section0:key0
  • section0:key1
  • section1:subsection:key
  • section2:subsection0:key
  • section2:subsection1:key

Fournisseur de configuration JSON

JsonConfigurationProvider charge la configuration à partir des paires clé-valeur du fichier JSON lors de l’exécution.

Pour activer la configuration du fichier JSON, appelez la méthode d’extension AddJsonFile sur une instance de ConfigurationBuilder.

Les surcharges permettent de spécifier :

  • Si le fichier est facultatif.
  • Si la configuration est rechargée quand le fichier est modifié.
  • Le IFileProvider utilisé pour accéder au fichier.

AddJsonFile est appelé automatiquement deux fois lors de l’initialisation d’un nouveau générateur d’hôte CreateDefaultBuilder . La méthode est appelée pour charger la configuration à partir de :

  • appsettings.json: Ce fichier est lu en premier. La version de l’environnement du fichier peut remplacer les valeurs fournies par le appsettings.json fichier.
  • appSettings. {Environment}. JSON: la version de l’environnement du fichier est chargée à partir de IHostingEnvironment. EnvironmentName.

Pour plus d’informations, consultez la section Configuration par défaut.

CreateDefaultBuilder charge également :

  • Variables d'environnement.
  • Secrets de l’utilisateur dans l’environnement de développement.
  • Arguments de ligne de commande

Le Fournisseur de configuration JSON est établi en premier. 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.

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:

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

Exemple

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 :

  • Le premier appel à AddJsonFile charge la configuration à partir de appsettings.json :

    {
      "Logging": {
        "LogLevel": {
          "Default": "Warning"
        }
      },
      "AllowedHosts": "*"
    }
    
  • Le deuxième appel à AddJsonFile charge la configuration à partir de appSettings. { Environnement}. JSON. Pour appsettings.Development.js dans l’exemple d’application, le fichier suivant est chargé :

    {
      "Logging": {
        "LogLevel": {
          "Default": "Debug",
          "System": "Information",
          "Microsoft": "Information"
        }
      }
    }
    
  1. Exécutez l’exemple d’application. Ouvrez un navigateur vers l’application avec l’adresse http://localhost:5000.
  2. La sortie contient des paires clé-valeur pour la configuration en fonction de l’environnement de l’application. 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.
  3. Exécutez à nouveau l’exemple d’application dans l’environnement de production :
    1. Ouvrez le fichier Properties/launchSettings.js .
    2. Dans le ConfigurationSample profil, remplacez la valeur de la ASPNETCORE_ENVIRONMENT variable d’environnement par Production .
    3. Enregistrez le fichier et exécutez l’application avec dotnet run dans un interpréteur de commandes.
  4. Les paramètres de la appsettings.Development.js qui ne se substituent plus aux paramètres dans appsettings.json . Le niveau de journalisation de la clé Logging:LogLevel:Default est Warning .

Fournisseur de configuration XML

XmlConfigurationProvider charge la configuration à partir des paires clé-valeur du fichier XML lors de l’exécution.

Pour activer la configuration du fichier XML, appelez la méthode d’extension AddXmlFile sur une instance de ConfigurationBuilder.

Les surcharges permettent de spécifier :

  • Si le fichier est facultatif.
  • Si la configuration est rechargée quand le fichier est modifié.
  • Le IFileProvider utilisé pour accéder au fichier.

Le nœud racine du fichier de configuration est ignoré lorsque les paires clé-valeur de la configuration sont créées. Ne spécifiez pas une définition de type de document (DTD) ou un espace de noms dans le fichier.

Appelez ConfigureAppConfiguration lors de la création de l’hôte pour spécifier la configuration de l’application :

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

  • section0:key0
  • section0:key1
  • section1:key0
  • section1: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 :

<?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 :

  • section:section0:key:key0
  • section:section0:key:key1
  • section:section1:key:key0
  • section:section1:key:key1

Les attributs peuvent être utilisés pour fournir des valeurs :

<?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 :

  • key:attribute
  • section:key:attribute

Fournisseur de configuration clé par fichier

Le KeyPerFileConfigurationProvider utilise les fichiers d’un répertoire en tant que paires clé-valeur de configuration. La clé est le nom de fichier. La valeur contient le contenu du fichier. Le Fournisseur de configuration Clé par fichier est utilisé dans les scénarios d’hébergement de Docker.

Pour activer la configuration clé par fichier, appelez la méthode d’extension AddKeyPerFile sur une instance de ConfigurationBuilder. Le directoryPath aux fichiers doit être un chemin d’accès absolu.

Les surcharges permettent de spécifier :

  • Un délégué Action<KeyPerFileConfigurationSource> qui configure la source.
  • Si le répertoire est facultatif et le chemin d’accès au répertoire.

Le double trait de soulignement (__) est utilisé comme un délimiteur de clé de configuration dans les noms de fichiers. Par exemple, le nom de fichier Logging__LogLevel__System génère la clé de configuration Logging:LogLevel:System.

Appelez ConfigureAppConfiguration lors de la création de l’hôte pour spécifier la configuration de l’application :

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

Fournisseur de configuration de mémoire

Le MemoryConfigurationProvider utilise une collection en mémoire en tant que paires clé-valeur de configuration.

Pour activer la configuration de la collection en mémoire, appelez la méthode d’extension AddInMemoryCollection sur une instance de ConfigurationBuilder.

Le fournisseur de configuration peut être initialisé avec un IEnumerable<KeyValuePair<String,String>>.

Appelez ConfigureAppConfiguration lors de la création de l’hôte pour spécifier la configuration de l’application.

Dans l’exemple suivant, un dictionnaire de configuration est créé :

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 :

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

GetValue

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é. Une surcharge accepte une valeur par défaut.

L’exemple suivant :

  • Extrait la valeur de chaîne de la configuration avec la clé NumberKey. Si NumberKey est introuvable dans les clés de configuration, la valeur par défaut de 99 est utilisée.
  • Tape la valeur comme int.
  • Stocke la valeur dans la propriété NumberConfig pour une utilisation par la 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 Exists

Pour les exemples qui suivent, utilisez le fichier JSON suivant. Quatre clés se trouvent dans deux sections, dont l’une inclut deux sous-sections :

{
  "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 :

  • section0:key0
  • section0:key1
  • section1:key0
  • section1:key1
  • section2:subsection0:key0
  • section2:subsection0:key1
  • section2:subsection1:key0
  • section2:subsection1:key1

GetSection

IConfiguration.GetSection extrait une sous-section de la configuration avec la clé de sous-section spécifiée.

Pour retourner un IConfigurationSection contenant uniquement les paires clé-valeur dans section1, appelez GetSection et fournissez le nom de section :

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

configSection n’a pas de valeur, seulement une clé et un chemin.

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 :

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

GetSection ne retourne jamais null. Si aucune section correspondante n’est trouvée, une valeur IConfigurationSection vide est retournée.

Quand GetSection retourne une section correspondante, Value n’est pas rempli. Key et Path sont retournés quand la section existe.

GetChildren

Un appel à IConfiguration.GetChildren sur section2 obtient un IEnumerable<IConfigurationSection> qui inclut :

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

var children = configSection.GetChildren();

Exists

Utilisez ConfigurationExtensions.Exists pour déterminer si une section de configuration existe :

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.

Établir une liaison à un graphe d’objets

Bind est capable de lier l’intégralité d’un graphe d’objets POCO. Comme pour la liaison d’un objet simple, seules les propriétés accessibles en lecture/écriture publiques sont liées.

L’exemple contient un modèle TvShow dont le graphe d’objets inclut les classes Metadata et Actors (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 :

<?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. L’instance liée est affectée à une propriété pour le rendu :

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

ConfigurationBinder.Get<T> lie et retourne le type spécifié. Il est plus pratique d’utiliser Get<T> que Bind. Le code suivant montre comment utiliser Get<T> avec l’exemple précédent :

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

Lier un tableau à une classe

L’exemple d’application illustre les concepts abordés dans cette section.

Bind prend en charge la liaison de tableaux à des objets à l’aide d’index de tableau dans les clés de configuration. 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.

Notes

La liaison est fournie par convention. Les fournisseurs de configuration personnalisés ne sont pas obligés d’implémenter la liaison de tableau.

Traitement de tableau en mémoire

Observez les valeurs et les clés de configuration indiquées dans le tableau suivant.

Clé Valeur
array:entries:0 value0
array:entries:1 valeur1
array:entries:2 valeur2
array:entries:4 value4
array:entries:5 value5

Ces clés et valeurs sont chargées dans l’exemple d’application à l’aide du Fournisseur de configuration de mémoire :

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

Dans l’exemple d’application, une classe POCO est disponible pour contenir les données de configuration liées :

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

Les données de configuration sont liées à l’objet :

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 :

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

L’objet lié, une instance de ArrayExample, reçoit les données de tableau à partir de la configuration.

Index ArrayExample.Entries Valeur ArrayExample.Entries
0 value0
1 valeur1
2 valeur2
3 value4
4 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. 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. 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.

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

missing_value.json :

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

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

Clé Valeur
array:entries:3 valeur3

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.

Index ArrayExample.Entries Valeur ArrayExample.Entries
0 value0
1 valeur1
2 valeur2
3 valeur3
4 value4
5 value5

Traitement de tableau JSON

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. Dans le fichier de configuration suivant, subsection est un tableau :

{
  "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 :

Clé Valeur
json_array:key valueA
json_array:subsection:0 valueB
json_array:subsection:1 valueC
json_array:subsection:2 valueD

Dans l’exemple d’application, la classe POCO suivante est disponible pour lier les paires clé-valeur de configuration :

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

Après la liaison, JsonArrayExample.Key contient la valeur valueA. Les valeurs de la sous-section sont stockées dans la propriété de tableau POCO, Subsection.

Index JsonArrayExample.Subsection Valeur JsonArrayExample.Subsection
0 valueB
1 valueC
2 valueD

Fournisseur de configuration personnalisé

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

Le fournisseur présente les caractéristiques suivantes :

  • La base de données en mémoire EF est utilisée à des fins de démonstration. 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.
  • Le fournisseur lit une table de base de données dans la configuration au démarrage. Le fournisseur n’interroge pas la base de données par clé.
  • 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.

Définissez une entité EFConfigurationValue pour le stockage des valeurs de configuration dans la base de données.

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.

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.

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. Le fournisseur de configuration initialise la base de données quand elle est vide.

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.

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 :

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émarrage

Injectez IConfiguration dans le constructeur Startup pour accéder aux valeurs de configuration dans Startup.ConfigureServices. Pour accéder à la configuration dans Startup.Configure, injectez IConfiguration directement dans la méthode ou utilisez l’instance à partir du constructeur :

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.

Configuration de l’accès dans une Razor page pages ou une vue MVC

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.

Dans une Razor page pages :

@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 :

@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 externe

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. Pour plus d’informations, consultez Utiliser des assemblys de démarrage d’hébergement dans ASP.NET Core.

Ressources supplémentaires