Configuration dans ASP.NET Core

Par Rick Anderson et Kirk Larkin

La configuration de l’application 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 de paires clé-valeur à l’aide de diverses sources de configuration :

• Fichiers de paramètres, comme 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

Cet article fournit des informations sur la configuration dans ASP.NET Core. Pour plus d’informations sur l’utilisation de la configuration dans des applications de console, consultez Configuration .NET.

Pour obtenir des instructions de configuration Blazor, en complément ou en remplacement des instructions de ce nœud, consultez Configuration Blazor ASP.NET Core.

Configuration de l’application et de l’hôte

Les applications ASP.NET Core configurent et lancent un hôte. L’hôte est responsable de la gestion du démarrage et de la durée de vie des applications. Les modèles ASP.NET Core créent un WebApplicationBuilder qui contient l’hôte. Une configuration peut être effectuée à la fois dans les fournisseurs de configuration de l’hôte et de l’application. Toutefois, seule la configuration nécessaire à l’hôte doit généralement être effectuée dans la configuration de l’hôte.

La configuration de l’application représente la priorité la plus élevée. Elle est détaillée dans la section suivante. La configuration de l’hôte suit la configuration de l’application. Elle est décrite dans cet article.

Sources de configuration de l’application par défaut

Les applications web ASP.NET Core créées avec dotnet new ou Visual Studio génèrent le code suivant :

C#

var builder = WebApplication.CreateBuilder(args);

WebApplication.CreateBuilder initialise une nouvelle instance de la classe WebApplicationBuilder avec les valeurs par défaut préconfigurées. Le WebApplicationBuilder (builder) initialisé fournit la configuration de l’application par défaut dans l’ordre suivant, de la priorité la plus élevée à la plus basse :

1. Arguments de ligne de commande avec le fournisseur de configuration de ligne de commande.
2. Variables d’environnement sans préfixe avec le fournisseur de configuration des variables d’environnement.
3. Les secrets utilisateur quand l’application s’exécute dans l’environnement Development
4. appsettings.{Environment}.json avec le fournisseur de configuration JSON. Par exemple : appsettings.Production.json et appsettings.Development.json.
5. appsettings.json à l’aide du fournisseur de configuration JSON.
6. Solution de secours à la configuration de l’hôte décrite dans la section suivante.

Sources de configuration de l’hôte par défaut

La liste suivante contient les sources de configuration de l’hôte par défaut de la priorité la plus élevée à la plus basse pour WebApplicationBuilder :

1. Arguments de ligne de commande avec le fournisseur de configuration de ligne de commande
2. Variables d’environnement avec le préfixe DOTNET_ avec le fournisseur de configuration des variables d’environnement.
3. Variables d’environnement avec le préfixe ASPNETCORE_ avec le fournisseur de configuration des variables d’environnement.

Pour l’hôte générique .NET et l’hôte web, les sources de configuration de l’hôte par défaut de la priorité la plus élevée à la priorité la plus basse sont les suivantes :

1. Variables d’environnement avec le préfixe ASPNETCORE_ avec le fournisseur de configuration des variables d’environnement.
2. Arguments de ligne de commande avec le fournisseur de configuration de ligne de commande
3. Variables d’environnement avec le préfixe DOTNET_ avec le fournisseur de configuration des variables d’environnement.

Quand une valeur de configuration est définie dans la configuration de l’hôte et de l’application, la configuration de l’application est utilisée.

Variables de l’hôte

Les variables suivantes sont verrouillées au début lors de l’initialisation des générateurs d’hôtes. Elles ne peuvent pas être affectées via la configuration de l’application :

• Nom de l’application
• Nom de l’environnement, par exemple Development, Production et Staging
• Racine de contenu
• Racine web
• Indique s’il faut effectuer une analyse à la recherche d’assemblys d’hébergement au démarrage et spécifie les assemblys à analyser.
• Les variables lues par le code de l’application et de la bibliothèque à partir de HostBuilderContext.Configuration dans les rappels de IHostBuilder.ConfigureAppConfiguration.

Tous les autres paramètres d’hôte sont lus à partir de la configuration de l’application et non de la configuration de l’hôte.

URLS est l’un des nombreux paramètres courants de l’hôte qui n’est pas un paramètre d’amorçage. Comme tous les autres paramètres d’hôte ne figurant pas dans la liste précédente, URLS est lu ultérieurement à partir de la configuration de l’application. La configuration de l’hôte est une solution de secours pour la configuration de l’application. La configuration de l’hôte peut donc être utilisée pour définir URLS, mais elle sera remplacée par toute source de configuration dans la configuration de l’application, comme appsettings.json.

Pour plus d’informations, consultez Modifier la racine du contenu, le nom de l’application et l’environnement et Modifier la racine du contenu, le nom de l’application et l’environnement à l’aide de variables d’environnement ou de la ligne de commande

Les sections suivantes de cet article font référence à la configuration de l’application.

Fournisseurs de configuration de l’application

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

C#

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

La liste des sources de configuration par défaut classées de la priorité la plus élevée à la plus basse précédente affiche les fournisseurs dans l’ordre inverse de leur ajout à l’application générée par le modèle. Par exemple, le fournisseur de configuration JSON est ajouté avant le fournisseur de configuration de ligne de commande.

Les fournisseurs de configuration ajoutés ultérieurement ont une priorité plus élevée. Ils remplacent les paramètres de clé précédents. Par exemple, si MyKey est défini 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 les valeurs de tous les autres fournisseurs.

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

appsettings.json

Examinons le fichier appsettings.json suivant :

JSON

{
  "Position": {
    "Title": "Editor",
    "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 certains des paramètres de configuration précédents :

C#

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

Le JsonConfigurationProvider par défaut charge la configuration dans l’ordre suivant :

1. appsettings.json
2. appsettings.{Environment}.json : par exemple les fichiers appsettings.Production.json et appsettings.Development.json. La version de l’environnement du fichier est chargée en fonction de IHostingEnvironment.EnvironmentName. Pour plus d’informations, consultez Utiliser plusieurs environnements dans ASP.NET Core.

Les valeurs appsettings.{Environment}.json remplacent les clés dans appsettings.json. Par exemple, par défaut :

• En cours de développement, la configuration appsettings.Development.json remplace les valeurs trouvées dans appsettings.json.
• En production, la configuration appsettings.Production.json 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 les chaînes. Il ne prend pas en charge de valeur par défaut.

À l’aide de la configuration par défaut , les fichiers appsettings.json et appsettings.{Environment}.json sont activés avec reloadOnChange: true. Les modifications apportées aux fichiers appsettings.json et appsettings.{Environment}.json après le démarrage de l’application sont lues par le fournisseur de configuration JSON.

Commentaires dans appsettings.json

Les commentaires dans les fichiers appsettings.json et appsettings.{Environment}.json sont pris en charge à l’aide des commentaires de style JavaScript ou C#.

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

La meilleure méthode pour lire les valeurs de configuration associées consiste à utiliser le modèle d’options. Par exemple, pour lire les valeurs de configuration suivantes :

JSON

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

Créez la classe PositionOptions suivante :

C#

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

    public string Title { get; set; } = String.Empty;
    public string Name { get; set; } = String.Empty;
}

Classe d’options :

• elle doit être non abstraite avec un constructeur public sans paramètre.
• 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é. Le champ Position est utilisé pour qu’il ne soit pas nécessaire de coder la chaîne "Position" 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 classe PositionOptions à la section Position.
• Affiche les données de configuration Position.

C#

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é. Il peut être plus pratique d’utiliser ConfigurationBinder.Get<T> que ConfigurationBinder.Bind. Le code suivant illustre la classe ConfigurationBinder.Get<T> avec la classe PositionOptions :

C#

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 lors de l’utilisation du modèle d’options consiste à lier la section Position et à l’ajouter au conteneur de service d’injection de dépendances. Dans le code suivant, PositionOptions est ajouté au conteneur de service avec Configure et lié à la configuration :

C#

using ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<PositionOptions>(
    builder.Configuration.GetSection(PositionOptions.Position));

var app = builder.Build();

À l’aide du code précédent, le code suivant lit les options de position :

C#

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 après que l’application a démarré, utilisez IOptionsSnapshot.

À l’aide de la configuration par défaut , les fichiers appsettings.json et appsettings.{Environment}.json sont activés avec reloadOnChange: true. Les modifications apportées aux fichiers appsettings.json et appsettings.{Environment}.json après le démarrage de l’application sont lues par le fournisseur de configuration JSON.

Consultez Fournisseur de configuration JSON dans ce document pour plus d’informations sur l’ajout de fichiers de configuration JSON.

Combinaison de la collection de services

Examinons les éléments suivants permettant d’inscrire les services et de configurer les options :

C#

using ConfigSample.Options;
using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<PositionOptions>(
    builder.Configuration.GetSection(PositionOptions.Position));
builder.Services.Configure<ColorOptions>(
    builder.Configuration.GetSection(ColorOptions.Color));

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

var app = builder.Build();

Les groupes d’inscriptions associés peuvent être déplacés vers une méthode d’extension pour inscrire les services. Les services de configuration sont par exemple ajoutés à la classe suivante :

C#

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

        public static IServiceCollection AddMyDependencyGroup(
             this IServiceCollection services)
        {
            services.AddScoped<IMyDependency, MyDependency>();
            services.AddScoped<IMyDependency2, MyDependency2>();

            return services;
        }
    }
}

Les services qui restent sont inscrits dans une classe similaire. Le code suivant utilise les nouvelles méthodes d’extension pour inscrire les services :

C#

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddConfig(builder.Configuration)
    .AddMyDependencyGroup();

builder.Services.AddRazorPages();

var app = builder.Build();

Remarque : chaque méthode d’extension services.Add{GROUP_NAME} ajoute des services et les configure éventuellement. Par exemple, AddControllersWithViews ajoute les services nécessaires à MVC avec vues et AddRazorPages ajoute les services nécessaires aux pages Razor.

Sécurité et secrets d’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. Vous pouvez utiliser l’outil Secret Manager pour stocker des secrets lors du 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.
• Les applications de production doivent utiliser le flux d’authentification le plus sécurisé disponible. Pour plus d’informations, consultez Flux d’authentification sécurisés.

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

• Utiliser plusieurs environnements dans ASP.NET Core
• Stockage sécurisé des secrets d’application en développement dans ASP.NET Core : comprend des conseils sur l’utilisation de variables d’environnement pour stocker les données sensibles. L’outil Secret Manager utilise le fournisseur de configuration de fichier pour stocker les secrets utilisateur dans un fichier JSON sur le système local.
• 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 sans préfixe

Les variables d’environnement sans préfixe sont des variables d’environnement autres que celles avec le préfixe ASPNETCORE_ ou DOTNET_. Par exemple, l’ensemble de modèles d’application web ASP.NET Core "ASPNETCORE_ENVIRONMENT": "Development" dans launchSettings.json. Pour plus d’informations sur les variables d’environnement ASPNETCORE_ et DOTNET_, consultez :

• Liste des sources de configuration par défaut classées de la priorité est la plus élevée à la plus basse, notamment les variables d’environnement sans préfixe, avec le préfixe ASPNETCORE_ et avec le préfixe DOTNETCORE_.
• DOTNET_ variables d’environnement utilisées en dehors de Microsoft.Extensions.Hosting.

À l’aide de la configuration par défaut, EnvironmentVariablesConfigurationProvider charge la configuration à partir de paires clé-valeur d’environnement après avoir lu appsettings.json, appsettings.{Environment}.json et les secrets de 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 des variables d’environnement sur toutes les plateformes. Par exemple, le séparateur : n’est pas pris en charge par Bash. Le double trait de soulignement __ est :

• Pris en charge par toutes les plateformes.
• Remplacé automatiquement par deux-points :.

Les commandes suivantes permettent de :

• Définir les clés d’environnement et les valeurs de l’exemple précédent sur Windows.
• Testez les paramètres lors de l’utilisation de l’exemple de téléchargement. La commande dotnet run doit être exécutée dans le répertoire du projet.

CLI .NET

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 :

• Définis uniquement dans les processus lancés à partir de la fenêtre de commande dans laquelle ils ont été définis.
• Ne seront pas lus 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, les paramètres setx sont persistants. /M définit la variable dans l’environnement système. Si le commutateur /M n’est pas utilisé, une variable d’environnement utilisateur est définie.

Console

setx MyKey "My key from setx Environment" /M
setx Position__Title 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 :

C#

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Configuration.AddEnvironmentVariables(prefix: "MyCustomPrefix_");

var app = builder.Build();

Dans le code précédent :

• builder.Configuration.AddEnvironmentVariables(prefix: "MyCustomPrefix_") 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.
• Les variables d’environnement définies avec le préfixe MyCustomPrefix_ remplacent les fournisseurs de configuration par défaut. Il s’agit notamment des variables d’environnement sans le préfixe.

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

Les commandes suivantes testent le préfixe personnalisé :

CLI .NET

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écédés du préfixe DOTNET_ et ASPNETCORE_. Les préfixes DOTNET_ et ASPNETCORE_ sont utilisés par ASP.NET Core pour la configuration de l’hôte et de 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. Les paramètres d’application Azure App Service sont :

• Chiffrés au rest 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 des chaînes de connexion pour plus d’informations sur les chaînes de connexion de base de données Azure.

Nommage des variables d’environnement

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

appsettings.json

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

Console

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 le fichier launchSettings.json généré

Les variables d’environnement définies dans launchSettings.json remplacent celles qui sont définies dans l’environnement système. Par exemple, les modèles web ASP.NET Core génèrent un fichier launchSettings.json qui définit la configuration du point de terminaison sur :

JSON

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

Configurer applicationUrl permet de définir la variable d’environnement ASPNETCORE_URLS et de remplacer les valeurs définies dans l’environnement.

Échappement des variables d’environnement sur Linux

Sur Linux, la valeur des variables d’environnement d’URL doit être placée dans une séquence d’échappement pour que systemd puisse l’analyser. Utiliser l’outil Linux systemd-escape qui interrompt http:--localhost:5001

Invite de commandes Windows

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 :

C#

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

foreach (var c in builder.Configuration.AsEnumerable())
{
    Console.WriteLine(c.Key + " = " + c.Value);
}

Ligne de commande

À l’aide de la configuration par défaut, CommandLineConfigurationProvider charge la configuration à partir de paires clé-valeur d’argument de ligne de commande après les sources de configuration suivantes :

• Fichiers appsettings.json et appsettings.{Environment}.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 = :

CLI .NET

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

CLI .NET

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

CLI .NET

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

Valeur de clé :

• Elle doit suivre = ou la clé doit avoir un préfixe -- ou / quand la valeur suit un espace.
• N’est pas obligatoire si l’option = est utilisée. Par exemple, MySetting=

Dans la même commande, ne mélangez pas des paires clé-valeur de l’argument de ligne de commande qui utilisent = avec des paires clé-valeur qui utilisent un espace.

Correspondances de commutateur

Les correspondances de commutateur permettent une logique de remplacement des noms de clé. Fournit un dictionnaire des remplacements de commutateur à la méthode AddCommandLine.

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 correspondances de commutateur, transmettez-le dans l’appel à AddCommandLine :

C#

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

builder.Configuration.AddCommandLine(args, switchMappings);

var app = builder.Build();

Exécutez la commande suivante pour tester le remplacement de la clé :

CLI .NET

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

Le code suivant montre les valeurs de clé pour les clés remplacées :

C#

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"]}'");
    }
}

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. Il n’existe aucun moyen de transmettre le dictionnaire de mappage de commutateur à CreateDefaultBuilder. La solution ne consiste pas à transmettre les arguments à CreateDefaultBuilder, mais à permettre à la méthode AddCommandLine de la méthode ConfigurationBuilder de traiter à la fois les arguments et le dictionnaire de correspondance de commutateur.

Définir les arguments d’environnement et de ligne de commande avec Visual Studio

Les arguments d’environnement et de ligne de commande peuvent être définis dans Visual Studio à partir de la boîte de dialogue Profils de lancement :

• Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet et sélectionnez Propriétés.
• Sélectionnez l’onglet Débogage > Général et sélectionnez Ouvrir l’IU Profils de lancement de débogage.

Données de configuration hiérarchiques

L’API de configuration lit les 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.

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

JSON

{
  "Position": {
    "Title": "Editor",
    "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 certains des paramètres de configuration :

C#

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 méthode pour lire les 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 à l’aide du modèle d’options 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

Avertissement

Cet article montre l’utilisation de chaîne de connexion s. Avec une base de données locale, l’utilisateur n’a pas besoin d’être authentifié, mais en production, les chaîne de connexion incluent parfois un mot de passe pour s’authentifier. Les informations d’identification de mot de passe du propriétaire de la ressource (ROPC) constituent un risque de sécurité qui doit être évité dans les bases de données de production. Les applications de production doivent utiliser le flux d’authentification le plus sécurisé disponible. Pour plus d’informations sur l’authentification des applications déployées pour tester ou produire des environnements, consultez Flux d’authentification sécurisés.

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 plus d’un fournisseur 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. Il est automatiquement transformé en signe 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 : quand 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 :

• Les valeurs 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 de variables d’environnement	Variables d'environnement
Fournisseur de configuration de fichier	Fichiers INI, JSON et XML
Fournisseur de configuration clé par fichier	Fichiers de répertoire
Fournisseur de configuration de 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 où leurs fournisseurs de configuration sont spécifiés. Organisez les fournisseurs de configuration dans le code en fonction des priorités pour les sources de configuration sous-jacentes nécessaires pour 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 avec le fournisseur de configuration des variables d’environnement.
5. Arguments de ligne de commande avec le fournisseur de configuration de ligne de commande.

Une pratique courante consiste à ajouter 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 dans la configuration par défaut.

Préfixes des chaînes de connexion

Avertissement

Cet article montre l’utilisation de chaîne de connexion s. Avec une base de données locale, l’utilisateur n’a pas besoin d’être authentifié, mais en production, les chaîne de connexion incluent parfois un mot de passe pour s’authentifier. Les informations d’identification de mot de passe du propriétaire de la ressource (ROPC) constituent un risque de sécurité qui doit être évité dans les bases de données de production. Les applications de production doivent utiliser le flux d’authentification le plus sécurisé disponible. Pour plus d’informations sur l’authentification des applications déployées pour tester ou produire des environnements, consultez Flux d’authentification sécurisés.

L’API de configuration présente 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 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

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
• Fournisseur de configuration JSON
• Fournisseur de configuration XML

Fournisseur de configuration INI

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

Le code suivant ajoute plusieurs fournisseurs de configuration :

C#

var builder = WebApplication.CreateBuilder(args);

builder.Configuration
    .AddIniFile("MyIniConfig.ini", optional: true, reloadOnChange: true)
    .AddIniFile($"MyIniConfig.{builder.Environment.EnvironmentName}.ini",
                optional: true, reloadOnChange: true);

builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);

builder.Services.AddRazorPages();

var app = builder.Build();

Dans le code précédent, les paramètres des fichiers MyIniConfig.ini et MyIniConfig.{Environment}.ini sont remplacés par les paramètres dans :

• Fournisseur de configuration de variables d’environnement
• Fournisseur de configuration de ligne de commande.

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

ini

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 certains des paramètres de configuration précédents :

C#

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

JsonConfigurationProvider charge la configuration à partir des paires clé-valeur du fichier JSON.

Les surcharges permettent de spécifier :

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

Prenez le code suivant :

C#

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddJsonFile("MyConfig.json",
        optional: true,
        reloadOnChange: true);

builder.Services.AddRazorPages();

var app = builder.Build();

Le code précédent :

• Configure le fournisseur de configuration JSON pour charger le fichier MyConfig.json avec les options suivantes :
  • optional: true : le fichier est facultatif.
  • reloadOnChange: true : le fichier est rechargé quand des modifications sont enregistrées.
• Lit les fournisseurs de configuration par défaut avant le fichier MyConfig.json. Les paramètres dans le fichier MyConfig.json remplacent les paramètres par défaut dans les fournisseurs de configuration, notamment le fournisseur de configuration des variables d’environnement et le fournisseur de configuration de ligne de commande.

En règle générale, vous ne souhaitez pas qu’un fichier JSON personnalisé écrase les valeurs définies dans le fournisseur de configuration des variables d’environnement et le fournisseur de configuration de ligne de commande.

Fournisseur de configuration XML

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

Le code suivant ajoute plusieurs fournisseurs de configuration :

C#

var builder = WebApplication.CreateBuilder(args);

builder.Configuration
    .AddXmlFile("MyXMLFile.xml", optional: true, reloadOnChange: true)
    .AddXmlFile($"MyXMLFile.{builder.Environment.EnvironmentName}.xml",
                optional: true, reloadOnChange: true);

builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);

builder.Services.AddRazorPages();

var app = builder.Build();

Dans le code précédent, les paramètres des fichiers MyXMLFile.xml et MyXMLFile.{Environment}.xml sont remplacés par les paramètres dans :

• Fournisseur de configuration de variables d’environnement
• Fournisseur de configuration de ligne de commande.

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

XML

<?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 certains des paramètres de configuration précédents :

C#

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

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

C#

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

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

C#

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

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

C#

var builder = WebApplication.CreateBuilder(args);

var Dict = new Dictionary<string, string>
        {
           {"MyKey", "Dictionary MyKey Value"},
           {"Position:Title", "Dictionary_Title"},
           {"Position:Name", "Dictionary_Name" },
           {"Logging:LogLevel:Default", "Warning"}
        };

builder.Configuration.AddInMemoryCollection(Dict);
builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);

builder.Services.AddRazorPages();

var app = builder.Build();

Le code suivant de l’exemple de téléchargement affiche les paramètres de configuration précédents :

C#

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.

Consultez Lier un tableau pour un autre exemple utilisant MemoryConfigurationProvider.

Configuration du point de terminaison Kestrel

Kestrel la configuration d’un point de terminaison spécifique remplace toutes les configurations de point de terminaison entre serveurs. Les configurations de point de terminaison entre serveurs comprennent notamment :

• UseUrls
• --urls sur la ligne de commande
• La variable d’environnement ASPNETCORE_URLS

Examinons le fichier appsettings.json utilisé dans une application web ASP.NET Core :

JSON

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

Quand 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 entre serveurs suivante :

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

Kestrel crée une liaison vers le point de terminaison configuré spécifiquement pour Kestrel dans le fichier appsettings.json (https://localhost:9999) et non https://localhost:7777.

Examinons le point de terminaison spécifique Kestrel 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 point de terminaison spécifique Kestrel. Le fichier appsettings.json précédent définit également un point de terminaison spécifique Kestrel 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 point de terminaison Https.

GetValue

ConfigurationBinder.GetValue extrait une valeur unique de la configuration avec une clé spécifiée et la convertit selon le type spécifié :

C#

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 NumberKey est introuvable dans la configuration, la valeur par défaut de 99 est utilisée.

GetSection, GetChildren et Exists

Pour les exemples suivants, utilisez le fichier MySubsection.json suivant :

JSON

{
  "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.json aux fournisseurs de configuration :

C#

var builder = WebApplication.CreateBuilder(args);

builder.Configuration
    .AddJsonFile("MySubsection.json",
                 optional: true,
                 reloadOnChange: true);

builder.Services.AddRazorPages();

var app = builder.Build();

GetSection

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

Le code suivant retourne les valeurs pour section1 :

C#

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 les valeurs pour section2:subsection0 :

C#

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 les valeurs pour section2:subsection0 :

C#

public class TestSection4Model : PageModel
{
    private readonly IConfiguration Config;

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

    public ContentResult OnGet()
    {
        string s = "";
        var selection = Config.GetSection("section2");
        if (!selection.Exists())
        {
            throw new 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 que la section existe :

Lier un tableau

ConfigurationBinder.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 est capable d’effectuer la liaison de tableau avec un tableau de classes POCO.

Examinons MyArray.json dans l’exemple de téléchargement :

JSON

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

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

C#

var builder = WebApplication.CreateBuilder(args);

builder.Configuration
    .AddJsonFile("MyArray.json",
                 optional: true,
                 reloadOnChange: true);

builder.Services.AddRazorPages();

var app = builder.Build();

Le code suivant lit la configuration et affiche les valeurs :

C#

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>();
        if (_array == null)
        {
            throw new ArgumentNullException(nameof(_array));
        }
        string s = String.Empty;

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

        return Content(s);
    }
}

C#

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

Le code précédent retourne la sortie suivante :

text

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.json. Les index de tableau lié sont contenus et ne sont pas liés à l’index de clé de configuration. Le binder de configuration n’est pas en mesure de lier des valeurs null, ni de créer des entrées null dans des objets liés.

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:

C#

public class EFConfigurationValue
{
    public string Id { get; set; } = String.Empty;
    public string Value { get; set; } = String.Empty;
}

Ajoutez un EFConfigurationContext pour stocker les valeurs configurées et y accéder.

EFConfigurationProvider/EFConfigurationContext.cs:

C#

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

    public DbSet<EFConfigurationValue> Values => Set<EFConfigurationValue>();
}

Créez une classe qui implémente IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs:

C#

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

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

    public IConfigurationProvider Build(IConfigurationBuilder builder) => 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 ne respectent 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:

C#

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))
        {
            if (dbContext == null || dbContext.Values == null)
            {
                throw new Exception("Null DB context");
            }
            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-2005
        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." }
            };

        if (dbContext == null || dbContext.Values == null)
        {
            throw new Exception("Null DB context");
        }

        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:

C#

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 :

C#

//using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddEFConfiguration(
    opt => opt.UseInMemoryDatabase("InMemoryDb"));

var app = builder.Build();

app.Run();

Configuration de l’accès avec injection de dépendances

La configuration peut être injectée dans des services à l’aide de l’injection de dépendances en résolvant le service IConfiguration :

C#

public class Service
{
    private readonly IConfiguration _config;

    public Service(IConfiguration config) =>
        _config = config;

    public void DoSomething()
    {
        var configSettingValue = _config["ConfigSetting"];

        // ...
    }
}

Pour plus d’informations sur l’accès aux valeurs à l’aide de IConfiguration, consultez GetValue et GetSection, GetChildren et Exists dans cet article.

Configuration de l’accès dans les pages Razor

Le code suivant affiche les données de configuration dans une page Razor :

CSHTML

@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 service avec Configure et lié à la configuration :

C#

using SampleApp.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<MyOptions>(
    builder.Configuration.GetSection("MyOptions"));

var app = builder.Build();

Le balisage suivant utilise la directive @injectRazor pour résoudre et afficher les valeurs des options :

CSHTML

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


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

Accéder à la configuration dans un fichier de vue MVC

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

CSHTML

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

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

Configuration de l’accès dans Program.cs

Le code suivant accède à la configuration dans le fichier Program.cs.

C#

var builder = WebApplication.CreateBuilder(args);

var key1 = builder.Configuration.GetValue<string>("KeyOne");

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

var key2 = app.Configuration.GetValue<int>("KeyTwo");
var key3 = app.Configuration.GetValue<bool>("KeyThree");

app.Logger.LogInformation("KeyOne: {KeyOne}", key1);
app.Logger.LogInformation("KeyTwo: {KeyTwo}", key2);
app.Logger.LogInformation("KeyThree: {KeyThree}", key3);

app.Run();

Dans appsettings.json pour l’exemple précédent :

JSON

{
  ...
  "KeyOne": "Key One Value",
  "KeyTwo": 1999,
  "KeyThree": true
}

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.

Dans le code suivant, un service IConfigureOptions<TOptions> est ajouté au conteneur de services. Il utilise un délégué pour configurer les valeurs pour MyOptions :

C#

using SampleApp.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<MyOptions>(myOptions =>
{
    myOptions.Option1 = "Value configured in delegate";
    myOptions.Option2 = 500;
});

var app = builder.Build();

Le code suivant affiche les valeurs d’options :

C#

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 sur l’impact des sources de configuration sur la configuration de l’hôte, consultez Vue d’ensemble des 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 :
  • Variables d’environnement avec le préfixe DOTNET_ (par exemple DOTNET_ENVIRONMENT) avec le fournisseur de configuration des variables d’environnement. Le préfixe (DOTNET_) est supprimé lorsque les paires clé-valeur de la configuration sont chargées.
  • Arguments de ligne de commande avec le fournisseur de configuration de ligne de commande.
• La configuration par défaut de l’hôte Web est établie (ConfigureWebHostDefaults) :
  • Kestrel est utilisé comme 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 des applications. D’autres aspects concernant l’exécution et l’hébergement des applications ASP.NET Core sont configurés à l’aide des fichiers de configuration qui ne sont pas abordés dans cette rubrique :

• launch.json/launchSettings.json sont des fichiers de configuration d’outils pour l’environnement de développement, décrits ci-après :
  • Dans Utiliser plusieurs environnements dans ASP.NET Core.
  • Dans l’ensemble de la documentation où les fichiers sont utilisés pour configurer des applications ASP.NET Core dans des scénarios de développement.
• web.config est un fichier de configuration de serveur décrit dans les rubriques suivantes :
  • Héberger ASP.NET Core sur Windows avec IIS
  • Module ASP.NET Core (ANCM) pour IIS

Les variables d’environnement définies dans launchSettings.json remplacent celles qui sont définies dans l’environnement système.

Pour plus d’informations sur la migration de la configuration d’application à partir de versions antérieures d’ASP.NET, consultez Effectuer une mise à jour 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 d’hébergement au démarrage dans ASP.NET Core.

Générateur de source de liaison de configuration

Le générateur de source de liaison de configuration fournit une configuration AOT et conviviale. Pour plus d’informations, consultez le générateur de source de liaison de configuration.

Ressources supplémentaires

• Code source de configuration
• Code source de WebApplicationBuilder
• Affichez ou téléchargez l’exemple de code (procédure de téléchargement)
• Modèle d’options dans ASP.NET Core
• C ASP.NET Core Blazor