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 plusieurs fournisseurs de configuration. Les fournisseurs de configuration lisent les données de configuration à partir de paires clé-valeur à l’aide de diverses sources de configuration :

  • fichiers Paramètres, tels queappsettings.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 les applications console, consultez .NET Configuration.

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

ASP.NET Core applications 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. Bien que certaines configurations puissent être effectuées à la fois dans l’hôte et les fournisseurs de configuration d’application, en général, seule la configuration nécessaire pour l’hôte doit être effectuée dans la configuration de l’hôte.

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

Sources de configuration d’application par défaut

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

var builder = WebApplication.CreateBuilder(args);

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

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

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

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

  1. ASPNETCORE_- variables d’environnement préfixées à l’aide du fournisseur de configuration des variables d’environnement.
  2. Arguments de ligne de commande à l’aide du fournisseur de configuration de ligne de commande
  3. DOTNET_- variables d’environnement préfixées à l’aide du fournisseur de configuration des variables d’environnement.

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

Consultez explication dans ce GitHub commentaire pour une explication de la raison pour laquelle, dans la configuration de l’hôte, ASPNETCORE_ les variables d’environnement préfixées ont une priorité plus élevée que les arguments de ligne de commande.

Variables d’hôte

Les variables suivantes sont verrouillées tôt lors de l’initialisation des générateurs d’hôtes et ne peuvent pas être influencées par la configuration de l’application :

Chaque autre paramètre hôte est lu à partir de la configuration de l’application au lieu de la configuration de l’hôte.

URLS est l’un des nombreux paramètres d’hôte courants qui n’est pas un paramètre de démarrage. Comme tous les autres paramètres d’hôte qui ne se trouve pas dans la liste précédente, URLS sont lus ultérieurement à partir de la configuration de l’application. La configuration de l’hôte est un 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 n’importe quelle 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 de contenu, le nom de l’application et l’environnement par variables d’environnement ou ligne de commande

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

Fournisseurs de configuration d’application

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

La liste précédente des sources de configuration par défaut les plus élevées à priorité la plus basse affiche les fournisseurs dans l’ordre inverse qu’ils sont ajoutés à l’application générée par le modèle. Par exemple, le fournisseur deJS configuration ON 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 et remplacent les paramètres de clé précédents. Par exemple, si MyKey elle est définie dans les deux appsettings.json et dans l’environnement, la valeur de l’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 CreateBuilder, consultez paramètres du générateur par défaut.

appsettings.json

Considérez le fichier suivant appsettings.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 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 la configuration dans l’ordre suivant :

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

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

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

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

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

La méthode préféré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 classe suivante PositionOptions :

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 :

  • Doit être non abstrait 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é. Le Position champ est utilisé afin que la chaîne "Position" n’ait pas besoin d’ê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 données de Position 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 JSfichier de configuration ON 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 d’utiliser 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 JSfichier de configuration ON 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 Position section 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 :

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 :

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 JSfichier de configuration ON après le démarrage de l’application ne sont pas lues. Pour lire les modifications après le démarrage de l’application, utilisez IOptionsSnapshot.

À l’aide de la configuration par défaut, les fichiers et appsettings.{Environment}.json les appsettings.json fichiers sont activés avec rechargementOnChange : true. Les modifications apportées au fichier etappsettings.{Environment}.json au appsettings.json démarrage de l’application sont lues par le JSfournisseur de configuration ON.

Consultez JSle fournisseur de configuration ON dans ce document pour plus d’informations sur l’ajout de fichiers de configuration ON supplémentaires JS.

Combinaison de la collection de services

Prenez en compte les options suivantes qui inscrivent les services et configurent les options suivantes :

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 des 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. Le code suivant utilise les nouvelles méthodes d’extension pour inscrire les services :

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

Note: Chaque services.Add{GROUP_NAME} méthode d’extension ajoute et configure potentiellement les services. Par exemple, AddControllersWithViews ajoute les contrôleurs MVC de services nécessitant des vues et AddRazorPages ajoute les pages de services Razor requises. Nous avons recommandé que les applications suivent la convention d’affectation de noms de création de méthodes d’extension dans l’espace Microsoft.Extensions.DependencyInjection de noms. Création de méthodes d’extension dans l’espace de Microsoft.Extensions.DependencyInjection noms :

  • Encapsule des groupes d’inscriptions de service.
  • Fournit un accès pratique IntelliSense au service.

Secrets de sécurité et 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. L’outil Secret Manager peut être utilisé pour stocker les secrets dans le 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 utilisateur est inscrite après les JSsources de configuration ON. Par conséquent, les clés de 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 :

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

Variables d’environnement non préfixes

Les variables d’environnement non préfixées sont des variables d’environnement autres que celles préfixées par ASPNETCORE_ ou DOTNET_. Par exemple, les modèles d’application web ASP.NET Core définis "ASPNETCORE_ENVIRONMENT": "Development" dans launchSettings.json. Pour plus d’informations sur les variables d’environnement et DOTNET_ sur les variables d’environnementASPNETCORE_, consultez :

À l’aide de la configuration par défaut , la EnvironmentVariablesConfigurationProvider configuration est chargée à partir de paires clé-valeur de l’environnement après la lecture appsettings.json, appsettings.{Environment}.jsonet les secrets utilisateur. Par conséquent, les valeurs de clé lues à partir de l’environnement remplacent les valeurs lues par appsettings.json, appsettings.{Environment}.jsonet les secrets utilisateur.

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

  • Pris en charge par toutes les plateformes. Par exemple, le : séparateur n’est pas pris en charge par Bash, mais __ il l’est.
  • Remplacé automatiquement par un :

Commandes suivantes set :

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 définis uniquement dans les processus lancés à partir de la fenêtre de commande dans laquelle ils ont été définis.
  • Ne sera pas lu 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 setaux paramètres persistants setx . /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 Environment_Editor /M
setx Position__Name Environment_Rick /M

Pour tester que les commandes précédentes remplacent appsettings.json et appsettings.{Environment}.json:

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

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

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

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écédés DOTNET_ et ASPNETCORE_. Les préfixes et ASPNETCORE_ les DOTNET_ préfixes sont utilisés par ASP.NET Core pour la configuration de l’hôte et de l’application, mais pas pour la configuration utilisateur. Pour plus d’informations sur la configuration de l’hôte et de l’application, consultez l’hôte générique .NET.

Dans Azure App Service, sélectionnez Nouveau paramètre d’application dans la page Configuration Paramètres>. Azure App Service paramètres d’application sont les suivants :

  • Chiffré au repos et transmis sur un canal chiffré.
  • Exposé 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 les préfixes de chaîne 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 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 un signe deux-points. Lorsque la structure d’élément inclut un tableau, l’index de tableau doit être traité comme un nom d’élément supplémentaire dans ce chemin d’accès. Considérez le fichier suivant appsettings.json et ses valeurs équivalentes représentées en tant que 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 launchSettings.json généré

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

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

Configuration des ensembles de la applicationUrlASPNETCORE_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 d’URL doit être échappée afin de systemd pouvoir l’analyser. Utiliser l’outil systemd-escape Linux 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 et valeurs d’environnement au démarrage de l’application, qui peuvent être utiles lors du débogage des paramètres d’environnement :

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 , la CommandLineConfigurationProvider configuration est chargée à partir de paires clé-valeur d’argument de ligne de commande après les sources de configuration suivantes :

  • appsettings.json et appsettings.{Environment}.json les fichiers.
  • Secrets d’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 les clés et les valeurs à l’aide =de :

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

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

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

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

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

Valeur de clé :

  • Doit suivre =, ou la clé doit avoir un préfixe de -- ou / lorsque la valeur suit un espace.
  • N’est pas obligatoire si = elle est utilisée. 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 qui utilisent = un espace.

Correspondances de commutateur

Les mappages de commutateur autorisent la logique de remplacement de nom de clé . Fournissez un dictionnaire de remplacements de commutateurs à 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 renvoyé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 démarrer avec - ou --.
  • Le dictionnaire de correspondances de commutateur ne doit pas contenir de clés en double.

Pour utiliser un dictionnaire de mappages de commutateurs, passez-le dans l’appel à AddCommandLine:


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

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 :

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 de AddCommandLine la CreateDefaultBuilder méthode n’inclut pas de commutateurs mappés et il n’existe aucun moyen de passer le dictionnaire de mappage de commutateur à CreateDefaultBuilder. La solution n’est pas de passer les arguments, CreateDefaultBuilder mais plutôt d’autoriser la méthode de AddCommandLine la ConfigurationBuilder méthode à traiter à la fois les arguments et le dictionnaire de mappage de commutateur.

Définir des 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 des profils de lancement :

  • Dans Explorateur de solutions, cliquez avec le bouton droit sur le projet, puis sélectionnez Propriétés.
  • Sélectionnez l’onglet Général de débogage > et sélectionnez Ouvrir l’interface utilisateur des 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 aplatissant 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 suivant appsettings.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 plusieurs 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 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 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 sont utilisées -- comme séparateur. Le fournisseur de configuration Azure Key Vault remplace automatiquement par un : moment où 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 fichiers 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 les fournisseurs de configuration dans le code pour qu’ils répondent 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 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 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 précédente de fournisseurs 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 d’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 fichiers

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 :

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

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

L’exemple de téléchargement contient le fichier suivant MyIniConfig.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 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}");
    }
}

JSFournisseur de configuration ON

Charge la JsonConfigurationProvider configuration à partir de paires clé-valeur de JSfichier ON.

Les surcharges peuvent spécifier :

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

Prenez le code suivant :

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

Le code précédent :

En règle générale, vous ne souhaitez pas qu’un fichier ON personnalisé JSsubstitue des 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 efface tous les fournisseurs de configuration et ajoute plusieurs fournisseurs de configuration :

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

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

L’exemple de téléchargement contient le fichier suivant MyXMLFile.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 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 de clé par fichier est utilisé dans les scénarios d’hébergement 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 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 :

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.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();

    config.AddInMemoryCollection(Dict);

    config.AddEnvironmentVariables();

    if (args != null)
    {
        config.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 :

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 JSle fournisseur de configuration ON.

Consultez Lier un tableau pour obtenir un autre exemple à l’aide de MemoryConfigurationProvider.

Kestrel configuration du point de terminaison

Kestrel une configuration de point de terminaison spécifique remplace toutes les configurations de point de terminaison entre serveurs . Les configurations de point de terminaison entre serveurs sont les suivantes :

Considérez le fichier suivant appsettings.json 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-serveur suivante :

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

Kestrellie au point de terminaison configuré spécifiquement pour Kestrel le fichier (https://localhost:9999) et non https://localhost:7777appsettings.json .

Considérez le Kestrel point de terminaison spécifique configuré en tant que variable d’environnement :

set Kestrel__Endpoints__Https__Url=https://localhost:8888

Dans la variable d’environnement précédente, Https correspond au nom du Kestrel point de terminaison spécifique. Le fichier précédent appsettings.json définit également un Kestrel point de terminaison spécifique nommé Https. Par défaut, les variables d’environnement utilisant le fournisseur de configuration 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 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, s’il NumberKey n’est pas trouvé dans la configuration, la valeur par défaut est 99 utilisée.

GetSection, GetChildren et Exists

Pour les exemples qui suivent, tenez compte du fichier suivant MySubsection.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 est ajouté MySubsection.json aux fournisseurs de configuration :

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

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

Les appels ConfigurationExtensions.Exists de code précédents 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 de lier un tableau de tableaux à un tableau de classes POCO .

À MyArray.json partir de l’exemple de téléchargement :

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

Le code suivant est ajouté MyArray.json aux fournisseurs de configuration :

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

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>();
        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);
    }
}
public class ArrayExample
{
    public string[]? Entries { get; set; } 
}

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, Index 3 a la valeur value40, correspondant à "4": "value40", .MyArray.json Les index de tableau liés sont continus et ne sont pas liés à l’index de clé de configuration. Le classeur de configuration n’est pas capable de lier des valeurs Null ou 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:

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:

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:

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 respectant la casse (StringComparer.OrdinalIgnoreCase).

EFConfigurationProvider/EFConfigurationProvider.cs:

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:

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 la commande personnalisée EFConfigurationProvider dans Program.cs:

//using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

app.Run();

Configuration d’accès avec injection de dépendances (DI)

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

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 IConfigurationde GetValue et GetSection, GetChildren et Exists dans cet article.

Configuration d’accès dans 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 service avec Configure et lié à la configuration :

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 @injectRazor directive pour résoudre et afficher les valeurs d’options :

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

Configuration d’accès dans un fichier d’affichage 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é

Options configurées dans un jeu de valeurs de remplacement délégué dans les fournisseurs de configuration.

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

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 :

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 et Option1Option2 sont spécifiées, 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 la façon dont les fournisseurs de configuration sont utilisés lorsque l’hôte est généré et comment les sources de configuration affectent la configuration de l’hôte, consultez ASP.NET Core vue d’ensemble des principes de base.

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é 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 de l’application. D’autres aspects de l’exécution et de l’hébergement d’applications ASP.NET Core sont configurés à l’aide de fichiers de configuration non abordés dans cette rubrique :

Les variables d’environnement définies en launchSettings.json remplacement de ces ensembles dans l’environnement système.

Pour plus d’informations sur la migration de la configuration des applications à partir des versions antérieures de ASP.NET, consultez Migrer de 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 l’hébergement d’assemblys de démarrage dans ASP.NET Core.

Ressources supplémentaires

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

  • fichiers Paramètres, tels queappsettings.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 les applications console, consultez .NET Configuration.

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

ASP.NET Core applications 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. Bien que certaines configurations puissent être effectuées dans l’hôte et les fournisseurs de configuration d’application, généralement, seule la configuration nécessaire pour l’hôte doit être effectuée dans la configuration de l’hôte.

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

Sources de configuration d’application par défaut

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

var builder = WebApplication.CreateBuilder(args);

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

  1. Arguments de ligne de commande utilisant le fournisseur de configuration de ligne de commande.
  2. Variables d’environnement non précédées à l’aide du fournisseur de configuration des variables d’environnement non préfixées.
  3. Les secrets utilisateur quand l’application s’exécute dans l’environnement Development
  4. appsettings.{Environment}.json à l’aide du fournisseur de JSconfiguration ON. Par exemple : appsettings.Production.json et appsettings.Development.json.
  5. appsettings.json à l’aide du JSfournisseur de configuration ON.
  6. Secours à la configuration de l’hôte décrite dans la section suivante.

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

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

  1. ASPNETCORE_Variables d’environnement préfixées à l’aide du fournisseur de configuration des variables d’environnement.
  2. Arguments de ligne de commande à l’aide du fournisseur de configuration de ligne de commande
  3. DOTNET_Variables d’environnement préfixées à l’aide du fournisseur de configuration des variables d’environnement.

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

Consultez explication dans ce GitHub commentaire pour une explication de la raison pour laquelle, dans la configuration de l’hôte, ASPNETCORE_ les variables d’environnement préfixées ont une priorité supérieure aux arguments de ligne de commande.

Variables d’hôte

Les variables suivantes sont verrouillées tôt lors de l’initialisation des générateurs d’hôtes et ne peuvent pas être influencées par la configuration de l’application :

Chaque autre paramètre hôte est lu à partir de la configuration d’application au lieu de la configuration de l’hôte.

URLS est l’un des nombreux paramètres hôtes courants qui n’est pas un paramètre de démarrage. Comme tous les autres paramètres d’hôte non dans la liste précédente, URLS est lu plus loin dans la configuration de l’application. La configuration de l’hôte est un secours pour la configuration d’application. La configuration de l’hôte peut donc être utilisée pour définir URLS, mais elle sera remplacée par n’importe quelle source de configuration dans la configuration de l’application comme appsettings.json.

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

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

Fournisseurs de configuration d’application

Le code suivant affiche les fournisseurs de configuration activés dans l’ordre qu’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);
    }
}

La liste précédente des sources de configuration par défaut les plus élevées à priorité la plus faible affiche les fournisseurs dans l’ordre opposé qu’ils sont ajoutés à l’application générée par le modèle. Par exemple, le JSfournisseur de configuration ON 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 et remplacent les paramètres de clé précédents. Par exemple, si MyKey elle est définie dans les deux appsettings.json et dans l’environnement, la valeur de l’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 CreateBuilder, consultez paramètres du générateur par défaut.

appsettings.json

Tenez compte du fichier suivant appsettings.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 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 la configuration dans l’ordre suivant :

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

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

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

À l’aide de la configuration par défaut, les fichiers et appsettings.{Environment}.json les appsettings.json fichiers sont activés avec rechargementOnChange : true. Les modifications apportées au fichier etappsettings.{Environment}.json au appsettings.json démarrage de l’application sont lues par le JSfournisseur de configuration ON.

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

La méthode préféré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 classe suivante PositionOptions :

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

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

Une classe d’options :

  • Doit être non abstrait avec un constructeur sans paramètre public.
  • Toutes les propriétés en lecture-écriture publique du type sont liées.
  • Les champs ne sont pas liés. Dans le code précédent, Position n’est pas lié. Le Position champ est utilisé afin que la chaîne "Position" n’ait pas besoin d’ê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 données de Position 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 ON une fois l’application JSdémarrée sont lues.

ConfigurationBinder.Get<T> lie et retourne le type spécifié. ConfigurationBinder.Get<T> peut être plus pratique que l’utilisation 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 ON une fois l’application JSdémarrée sont lues.

Une autre approche lors de l’utilisation du modèle d’options consiste à lier la section et à l’ajouter Position 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 :

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 :

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 JSfichier de configuration ON une fois l’application démarrée ne sont pas lues. Pour lire les modifications après le démarrage de l’application, utilisez IOptionsSnapshot.

À l’aide de la configuration par défaut, les fichiers et appsettings.{Environment}.json les appsettings.json fichiers sont activés avec rechargementOnChange : true. Les modifications apportées au fichier etappsettings.{Environment}.json au appsettings.json démarrage de l’application sont lues par le JSfournisseur de configuration ON.

Consultez JSle fournisseur de configuration ON dans ce document pour plus d’informations sur l’ajout de fichiers de configuration ON supplémentaires JS.

Combinaison de la collection de services

Prenez en compte les options suivantes qui inscrivent les services et configurent les options suivantes :

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 des 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. Le code suivant utilise les nouvelles méthodes d’extension pour inscrire les services :

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

Note: Chaque services.Add{GROUP_NAME} méthode d’extension ajoute et configure potentiellement les services. Par exemple, AddControllersWithViews ajoute les contrôleurs MVC de services nécessitant des vues et AddRazorPages ajoute les pages de services Razor requises. Nous avons recommandé que les applications suivent la convention d’affectation de noms de création de méthodes d’extension dans l’espace Microsoft.Extensions.DependencyInjection de noms. Création de méthodes d’extension dans l’espace de Microsoft.Extensions.DependencyInjection noms :

  • Encapsule des groupes d’inscriptions de service.
  • Fournit un accès pratique IntelliSense au service.

Secrets de sécurité et 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. L’outil Secret Manager peut être utilisé pour stocker les secrets dans le 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 utilisateur est inscrite après les JSsources de configuration ON. Par conséquent, les clés de 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 :

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

Variables d’environnement non préfixes

Les variables d’environnement non préfixées sont des variables d’environnement autres que celles préfixées par ASPNETCORE_ ou DOTNET_. Par exemple, les modèles d’application web ASP.NET Core définis "ASPNETCORE_ENVIRONMENT": "Development" dans launchSettings.json. Pour plus d’informations sur les variables d’environnement et DOTNET_ sur les variables d’environnementASPNETCORE_, consultez :

À l’aide de la configuration par défaut , la EnvironmentVariablesConfigurationProvider configuration est chargée à partir de paires clé-valeur de variable d’environnement après lecture appsettings.json, appsettings.{Environment}.jsonet secrets utilisateur. Par conséquent, les valeurs de clé lues à partir de l’environnement remplacent les valeurs lues à partir de , appsettings.{Environment}.jsonet les appsettings.jsonsecrets utilisateur.

Le : séparateur ne fonctionne pas avec les clés hiérarchiques des variables 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 __ il l’est.
  • Remplacé automatiquement par un :

Les commandes suivantes set :

set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run

Les paramètres d’environnement précédents :

  • Sont uniquement définis dans les processus lancés à partir de la fenêtre de commande dans laquelle ils ont été définis.
  • Ne sera pas lu 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 Environment_Editor /M
setx Position__Name Environment_Rick /M

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

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

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

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écédés DOTNET_ et ASPNETCORE_. Les DOTNET_ préfixes et ASPNETCORE_ les préfixes sont utilisés par ASP.NET Core pour la configuration de l’hôte et de l’application, mais pas pour la configuration utilisateur. Pour plus d’informations sur la configuration de l’hôte et de l’application, consultez l’hôte générique .NET.

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

  • Chiffré au repos et transmis sur un canal chiffré.
  • Exposé 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 les préfixes de chaîne 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 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 un signe deux-points. Lorsque la structure d’élément inclut un tableau, l’index de tableau doit être traité comme un nom d’élément supplémentaire dans ce chemin d’accès. Considérez le fichier suivant appsettings.json et ses valeurs équivalentes représentées en tant que 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 launchSettings.json généré

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

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

La configuration des ensembles de applicationUrl la variable d’environnement ASPNETCORE_URLS et remplace les valeurs définies dans l’environnement.

Variables d’environnement d’échappement sur Linux

Sur Linux, la valeur des variables d’environnement d’URL doit être placée dans une séquence d’échappement afin de systemd pouvoir l’analyser. Utiliser l’outil systemd-escape Linux 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 :

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 , la CommandLineConfigurationProvider configuration charge à partir de paires clé-valeur d’argument de ligne de commande après les sources de configuration suivantes :

  • appsettings.json et appsettings.{Environment}.json fichiers.
  • Secrets d’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 les clés et les valeurs à l’aide de =:

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

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

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

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

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

Valeur de clé :

  • Doit suivre =, ou la clé doit avoir un préfixe de -- ou / lorsque la valeur suit un espace.
  • N’est pas obligatoire si = elle est utilisée. 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 qui utilisent = un espace.

Correspondances de commutateur

Les mappages de commutateur autorisent la logique de remplacement de nom de clé . Fournissez un dictionnaire de remplacements de commutateurs à 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 renvoyé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 démarrer avec - ou --.
  • Le dictionnaire de correspondances de commutateur ne doit pas contenir de clés en double.

Pour utiliser un dictionnaire de mappages de commutateurs, passez-le dans l’appel à AddCommandLine:


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

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 :

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 de AddCommandLine la CreateDefaultBuilder méthode n’inclut pas de commutateurs mappés et il n’existe aucun moyen de passer le dictionnaire de mappage de commutateur à CreateDefaultBuilder. La solution n’est pas de passer les arguments, CreateDefaultBuilder mais plutôt d’autoriser la méthode de AddCommandLine la ConfigurationBuilder méthode à traiter à la fois les arguments et le dictionnaire de mappage de commutateur.

Définir des 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 des profils de lancement :

  • Dans Explorateur de solutions, cliquez avec le bouton droit sur le projet, puis sélectionnez Propriétés.
  • Sélectionnez l’onglet Général de débogage > et sélectionnez Ouvrir l’interface utilisateur des 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 aplatissant 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 suivant appsettings.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 plusieurs 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 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 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 sont utilisées -- comme séparateur. Le fournisseur de configuration Azure Key Vault remplace automatiquement par un : moment où 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 fichiers 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 les fournisseurs de configuration dans le code pour qu’ils répondent 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 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 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 précédente de fournisseurs 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 d’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 fichiers

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 :

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

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

L’exemple de téléchargement contient le fichier suivant MyIniConfig.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 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}");
    }
}

JSFournisseur de configuration ON

Charge la JsonConfigurationProvider configuration à partir de paires clé-valeur de JSfichier ON.

Les surcharges peuvent spécifier :

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

Prenez le code suivant :

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

Le code précédent :

En règle générale, vous ne souhaitez pas qu’un fichier ON personnalisé JSsubstitue des 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 efface tous les fournisseurs de configuration et ajoute plusieurs fournisseurs de configuration :

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

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

L’exemple de téléchargement contient le fichier suivant MyXMLFile.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 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 de clé par fichier est utilisé dans les scénarios d’hébergement 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 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 :

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.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();

    config.AddInMemoryCollection(Dict);

    config.AddEnvironmentVariables();

    if (args != null)
    {
        config.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 :

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 commande des fournisseurs de configuration, consultez JSle fournisseur de configuration ON.

Consultez Lier un tableau pour un autre exemple à l’aide MemoryConfigurationProviderde .

Kestrel Configuration du point de terminaison

Kestrel une configuration de point de terminaison spécifique remplace toutes les configurations de point de terminaison entre serveurs . Les configurations de point de terminaison entre serveurs sont les suivantes :

Considérez le fichier suivant appsettings.json 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 mis 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-serveur suivante :

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

Kestrellie au point de terminaison configuré spécifiquement pour Kestrel le fichier (https://localhost:9999) et non https://localhost:7777appsettings.json .

Considérez le point de terminaison spécifique configuré en tant que variable d’environnement Kestrel :

set Kestrel__Endpoints__Https__Url=https://localhost:8888

Dans la variable d’environnement précédente, Https correspond au nom du Kestrel point de terminaison spécifique. Le fichier précédent appsettings.json 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 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, s’il NumberKey n’est pas trouvé dans la configuration, la valeur par défaut est 99 utilisée.

GetSection, GetChildren et Exists

Pour les exemples suivants, tenez compte du fichier suivant MySubsection.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 s’ajoute MySubsection.json aux fournisseurs de configuration :

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

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

Les appels ConfigurationExtensions.Exists de code précédents 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 de lier le tableau à un tableau de classes POCO .

Envisagez MyArray.json à partir de l’exemple de téléchargement :

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

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

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

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>();
        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);
    }
}
public class ArrayExample
{
    public string[]? Entries { get; set; } 
}

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, correspondant à "4": "value40",MyArray.json. Les index de tableau liés sont continus et ne sont pas liés à l’index de clé de configuration. Le classeur de configuration n’est pas capable de lier des valeurs Null ou 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:

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:

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:

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 respectant la casse (StringComparer.OrdinalIgnoreCase).

EFConfigurationProvider/EFConfigurationProvider.cs:

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:

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 la commande personnalisée EFConfigurationProvider dans Program.cs:

//using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

app.Run();

Configuration d’accès avec injection de dépendances (DI)

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

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 IConfigurationde GetValue et GetSection, GetChildren et Exists dans cet article.

Configuration d’accès dans 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 service avec Configure et lié à la configuration :

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 @injectRazor directive pour résoudre et afficher les valeurs d’options :

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

Configuration d’accès dans un fichier d’affichage 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é

Options configurées dans un jeu de valeurs de remplacement délégué dans les fournisseurs de configuration.

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

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 :

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 et Option1Option2 sont spécifiées, 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 la façon dont les fournisseurs de configuration sont utilisés lorsque l’hôte est généré et comment les sources de configuration affectent la configuration de l’hôte, consultez ASP.NET Core vue d’ensemble des principes de base.

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é 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 de l’application. D’autres aspects de l’exécution et de l’hébergement d’applications ASP.NET Core sont configurés à l’aide de fichiers de configuration non abordés dans cette rubrique :

Les variables d’environnement définies en launchSettings.json remplacement de ces ensembles dans l’environnement système.

Pour plus d’informations sur la migration de la configuration des applications à partir des versions antérieures de ASP.NET, consultez Migrer de 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 l’hébergement d’assemblys de démarrage dans ASP.NET Core.

Ressources supplémentaires

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

  • fichiers Paramètres, tels queappsettings.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 .NET Configuration.

Afficher ou télécharger un exemple de code (comment télécharger)

Configuration par défaut

ASP.NET Core applications web créées avec dotnet new ou Visual Studio générer 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 une source existante IConfiguration . Dans le cas de configuration par défaut, ajoute la configuration de l’hôte et la définit comme première source pour la configuration de l’application.
  2. appsettings.json à l’aide du JSfournisseur de configuration ON.
  3. appsettings.{Environment}.json à l’aide du fournisseur de JSconfiguration ON. Par exemple : appsettings.Production.json et appsettings.Development.json.
  4. Secrets d’application lorsque l’application s’exécute dans l’environnement Development .
  5. Variables d’environnement à l’aide du fournisseur de configuration des variables d’environnement.
  6. Arguments de ligne de commande utilisant le fournisseur de configuration de ligne de commande.

Les fournisseurs de configuration ajoutés remplacent ultérieurement les paramètres de clé précédents. Par exemple, si MyKey elle est définie dans les deux appsettings.json et dans l’environnement, la valeur de l’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 du générateur par défaut.

Le code suivant affiche les fournisseurs de configuration activés dans l’ordre qu’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

Tenez compte du fichier suivant appsettings.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 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 la configuration dans l’ordre suivant :

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

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

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

À l’aide de la configuration par défaut, les fichiers et appsettings.{Environment}.json les appsettings.json fichiers sont activés avec rechargementOnChange : true. Les modifications apportées au fichier etappsettings.{Environment}.json au appsettings.json démarrage de l’application sont lues par le JSfournisseur de configuration ON.

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

La méthode préféré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 classe suivante PositionOptions :

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 abstrait avec un constructeur sans paramètre public.
  • Toutes les propriétés en lecture-écriture publique 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" n’ait pas besoin d’ê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 données de Position 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 ON une fois l’application JSdémarrée sont lues.

ConfigurationBinder.Get<T> lie et retourne le type spécifié. ConfigurationBinder.Get<T> peut être plus pratique que l’utilisation 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 ON une fois l’application JSdémarrée sont lues.

Une autre approche lors de l’utilisation du modèle d’options consiste à lier la section et à l’ajouter Position 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 :

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 JSfichier de configuration ON une fois l’application démarrée ne sont pas lues. Pour lire les modifications après le démarrage de l’application, utilisez IOptionsSnapshot.

À l’aide de la configuration par défaut, les fichiers et appsettings.{Environment}.json les appsettings.json fichiers sont activés avec rechargementOnChange : true. Les modifications apportées au fichier etappsettings.{Environment}.json au appsettings.json démarrage de l’application sont lues par le JSfournisseur de configuration ON.

Consultez JSle fournisseur de configuration ON dans ce document pour plus d’informations sur l’ajout de fichiers de configuration ON supplémentaires JS.

Combinaison de la collection de services

Tenez compte de la méthode suivante ConfigureServices , 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 des 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 méthode suivante ConfigureServices utilise les nouvelles méthodes d’extension pour inscrire les services :

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

    services.AddRazorPages();
}

Note: Chaque services.Add{GROUP_NAME} méthode d’extension ajoute et configure potentiellement les services. Par exemple, AddControllersWithViews ajoute les contrôleurs MVC de services nécessitant des vues et AddRazorPages ajoute les pages de services Razor requises. Nous avons recommandé que les applications suivent la convention d’affectation de noms de création de méthodes d’extension dans l’espace Microsoft.Extensions.DependencyInjection de noms. Création de méthodes d’extension dans l’espace de Microsoft.Extensions.DependencyInjection noms :

  • Encapsule des groupes d’inscriptions de service.
  • Fournit un accès pratique IntelliSense au service.

Secrets de sécurité et 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. L’outil Secret Manager peut être utilisé pour stocker les secrets dans le 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 utilisateur est inscrite après les JSsources de configuration ON. Par conséquent, les clés de 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 :

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

Variables d'environnement

À l’aide de la configuration par défaut , la EnvironmentVariablesConfigurationProvider configuration est chargée à partir de paires clé-valeur de l’environnement après la lecture appsettings.json, appsettings.{Environment}.jsonet les secrets utilisateur. Par conséquent, les valeurs de clé lues à partir de l’environnement remplacent les valeurs lues par appsettings.json, appsettings.{Environment}.jsonet les secrets utilisateur.

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

  • Pris en charge par toutes les plateformes. Par exemple, le : séparateur n’est pas pris en charge par Bash, mais __ il l’est.
  • Remplacé automatiquement par un :

Commandes suivantes set :

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 définis uniquement dans les processus lancés à partir de la fenêtre de commande dans laquelle ils ont été définis.
  • Ne sera pas lu 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 setaux paramètres persistants setx . /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 Environment_Editor /M
setx Position__Name Environment_Rick /M

Pour tester que les commandes précédentes remplacent appsettings.json et appsettings.{Environment}.json:

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

Appel 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écédés DOTNET_ et ASPNETCORE_. Les préfixes et ASPNETCORE_ les DOTNET_ préfixes sont utilisés par ASP.NET Core pour la configuration de l’hôte et de l’application, mais pas pour la configuration utilisateur. Pour plus d’informations sur la configuration de l’hôte et de l’application, consultez l’hôte générique .NET.

Dans Azure App Service, sélectionnez Nouveau paramètre d’application dans la page Configuration Paramètres>. Azure App Service paramètres d’application sont les suivants :

  • Chiffré au repos et transmis sur un canal chiffré.
  • Exposé 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 les préfixes de chaîne 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 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 un signe deux-points. Lorsque la structure d’élément inclut un tableau, l’index de tableau doit être traité comme un nom d’élément supplémentaire dans ce chemin d’accès. Considérez le fichier suivant appsettings.json et ses valeurs équivalentes représentées en tant que 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 launchSettings.json généré

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

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

Configuration des ensembles de la applicationUrlASPNETCORE_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 d’URL doit être échappée afin de systemd pouvoir l’analyser. Utiliser l’outil systemd-escape Linux 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 et valeurs d’environnement au démarrage de l’application, qui peuvent être utiles 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 , la CommandLineConfigurationProvider configuration est chargée à partir de paires clé-valeur d’argument de ligne de commande après les sources de configuration suivantes :

  • appsettings.json et appsettings.{Environment}.json les fichiers.
  • Secrets d’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 les clés et les valeurs à l’aide =de :

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

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

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

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

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

Valeur de clé :

  • Doit suivre =, ou la clé doit avoir un préfixe de -- ou / lorsque la valeur suit un espace.
  • N’est pas obligatoire si = elle est utilisée. 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 qui utilisent = un espace.

Correspondances de commutateur

Les mappages de commutateur autorisent la logique de remplacement de nom de clé . Fournissez un dictionnaire de remplacements de commutateurs à 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 renvoyé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 démarrer avec - ou --.
  • Le dictionnaire de correspondances de commutateur ne doit pas contenir de clés en double.

Pour utiliser un dictionnaire de mappages de commutateurs, passez-le dans 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 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’appel de AddCommandLine la CreateDefaultBuilder méthode n’inclut pas de commutateurs mappés et il n’existe aucun moyen de passer le dictionnaire de mappage de commutateur à CreateDefaultBuilder. La solution n’est pas de passer les arguments, CreateDefaultBuilder mais plutôt d’autoriser la méthode de AddCommandLine la ConfigurationBuilder méthode à traiter à la fois les arguments et le dictionnaire de mappage de commutateur.

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

L’image suivante montre la définition de l’environnement et des arguments de ligne de commande avec Visual Studio :

Debug tab of VS

Dans Visual Studio version 16.10 preview 4 et ultérieure de la version 2019, la définition des arguments d’environnement et de ligne de commande est effectuée à partir de l’interface utilisateur des profils de lancement :

launch profiles UI

Données de configuration hiérarchiques

L’API De configuration lit les données de configuration hiérarchiques en aplatissant 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 suivant appsettings.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 plusieurs 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 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 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 sont utilisées -- comme séparateur. Le fournisseur de configuration Azure Key Vault remplace automatiquement par un : moment où 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 fichiers 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 les fournisseurs de configuration dans le code pour qu’ils répondent 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 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 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 précédente de fournisseurs 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 d’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 fichiers

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 dans les fichiers et MyIniConfig.{Environment}.ini les MyIniConfig.ini paramètres sont remplacés par les paramètres dans les paramètres suivants :

L’exemple de téléchargement contient le fichier suivant MyIniConfig.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 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}");
    }
}

JSFournisseur de configuration ON

Charge la JsonConfigurationProvider configuration à partir de paires clé-valeur de JSfichier ON.

Les surcharges peuvent spécifier :

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

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

En règle générale, vous ne souhaitez pas qu’un fichier ON personnalisé JSsubstitue des valeurs définies dans le fournisseur de configuration des variables d’environnement et 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, paramètres dans myConfig MyConfig.json et myConfig.Environment. fichiers json :

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

{
  "Position": {
    "Title": "My Config title",
    "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 dans les fichiers et MyXMLFile.{Environment}.xml les MyXMLFile.xml paramètres sont remplacés par les paramètres dans les paramètres suivants :

L’exemple de téléchargement contient le fichier suivant MyXMLFile.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 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 de clé par fichier est utilisé dans les scénarios d’hébergement 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 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 JSle fournisseur de configuration ON.

Consultez Lier un tableau pour obtenir un autre exemple à l’aide de MemoryConfigurationProvider.

Kestrel configuration du point de terminaison

Kestrel une configuration de point de terminaison spécifique remplace toutes les configurations de point de terminaison entre serveurs . Les configurations de point de terminaison entre serveurs sont les suivantes :

Considérez le fichier suivant appsettings.json 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-serveur suivante :

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

Kestrellie au point de terminaison configuré spécifiquement pour Kestrel le fichier (https://localhost:9999) et non https://localhost:7777appsettings.json .

Considérez le Kestrel point de terminaison spécifique configuré en tant que variable d’environnement :

set Kestrel__Endpoints__Https__Url=https://localhost:8888

Dans la variable d’environnement précédente, Https correspond au nom du Kestrel point de terminaison spécifique. Le fichier précédent appsettings.json définit également un Kestrel point de terminaison spécifique nommé Https. Par défaut, les variables d’environnement utilisant le fournisseur de configuration 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 extrait une valeur unique de la configuration avec une clé spécifiée et la convertit en type spécifié. Cette méthode est une méthode d’extension pour IConfiguration:

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, s’il NumberKey n’est pas trouvé dans la configuration, la valeur par défaut est 99 utilisée.

GetSection, GetChildren et Exists

Pour les exemples qui suivent, tenez compte du fichier suivant MySubsection.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 est ajouté MySubsection.json 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 and 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);
    }
}

Les appels ConfigurationExtensions.Exists de code précédents 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 de lier un tableau de tableaux à un tableau de classes POCO .

À MyArray.json partir de l’exemple de téléchargement :

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

Le code suivant est ajouté MyArray.json 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, correspondant à "4": "value40",MyArray.json. Les index de tableau liés sont continus et ne sont pas liés à l’index de clé de configuration. Le classeur de configuration n’est pas capable de lier des valeurs Null ou de créer des entrées null dans des objets liés

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

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 le arrayDictDictionary code 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

Index #3 dans l’objet lié contient les données de configuration de la array:4 clé de configuration et sa valeur .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 index #3 peut être fourni avant la liaison à l’instance ArrayExample par n’importe quel fournisseur de configuration qui lit la paire clé/valeur d’index #3. Prenez en compte le fichier suivant Value3.json à partir de l’exemple de téléchargement :

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

Le code suivant inclut la configuration et Value3.json les arrayDictDictionaryéléments suivants :

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 ne respectent pas la casse, le dictionnaire utilisé pour initialiser la base de données est créé avec le comparateur respectant 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-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." }
            };

        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 la commande personnalisée EFConfigurationProvider 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 d’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 d’accès dans 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 service avec Configure et lié à la configuration :

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

    services.AddRazorPages();
}

Le balisage suivant utilise la @injectRazor directive pour résoudre et afficher les valeurs d’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 d’accès dans un fichier d’affichage 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é

Options configurées dans un jeu de valeurs de remplacement délégué dans les fournisseurs de configuration.

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

Dans le code suivant, un IConfigureOptions<TOptions> service est ajouté au conteneur de service. 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 d’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 et Option1Option2 sont spécifiées, 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 la façon dont les fournisseurs de configuration sont utilisés lorsque l’hôte est généré et comment les sources de configuration affectent la configuration de l’hôte, consultez ASP.NET Core vue d’ensemble des principes de base.

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 précédées (par exemple) DOTNET_ENVIRONMENTà DOTNET_ l’aide du 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 utilisant 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 de l’application. D’autres aspects de l’exécution et de l’hébergement d’applications ASP.NET Core sont configurés à l’aide de fichiers de configuration non abordés dans cette rubrique :

Les variables d’environnement définies en launchSettings.json remplacement de ces ensembles dans l’environnement système.

Pour plus d’informations sur la migration de la configuration des applications à partir des versions antérieures de ASP.NET, consultez Migrer de 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 l’hébergement d’assemblys de démarrage dans ASP.NET Core.

Ressources supplémentaires