Configuration dans ASP.NET Core

Note

Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 10 de cet article.

Warning

Cette version d’ASP.NET Core n’est plus prise en charge. Pour plus d’informations, consultez la stratégie de support .NET et .NET Core. Pour la version actuelle, consultez la version .NET 10 de cet article.

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

Fichiers de paramètres, comme appsettings.json
Variables d’environnement, y compris la configuration d’Azure App
Azure Key Vault
Arguments de ligne de commande
Fournisseurs personnalisés, installés ou créés
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 non-ASP.NET Core, consultez .NET Configuration.

Pour obtenir des conseils de configuration supplémentairesBlazor, qui complète ou remplace les instructions ici, consultez la configuration d'ASP.NET CoreBlazor.

Cet article concerne principalement la configuration de l’application. D’autres types de configuration, tels que les fichiers de paramètres de lancement et le web.config fichier, sont mentionnés ici, mais leur documentation principale est ailleurs :

Lancez les fichiers de paramètres (launch.json/launchSettings.json), qui sont des fichiers de configuration d’outils pour l’environnement.Development Pour plus d’informations, consultez ASP.NET environnements d’exécution Core. Certains détails sur les paramètres de lancement sont couverts par cet article dans la section Remplacement des paramètres de lancement par des variables d’environnement.
web.config, qui est un fichier de configuration de serveur pour Internet Information Services (IIS). Pour plus d’informations, consultez Host ASP.NET Core sur Windows avec IIS et ASP.NET Core Module (ANCM) pour IIS.

Pour plus d’informations sur la migration de la configuration des applications à partir de versions antérieures de ASP.NET, consultez Migrer la configuration vers ASP.NET Core.

Warning

Cet article montre l’utilisation de chaînes de connexion. Lorsque vous utilisez une base de données locale pour le développement et le test, l’authentification de l’utilisateur de base de données via la chaîne de connexion n’est pas nécessaire. Dans les environnements de production, les chaînes de connexion incluent parfois un mot de passe pour authentifier l’accès à la base de données ou les opérations de base de données. Les informations d’identification de mot de passe du propriétaire de la ressource (ROPC) dans une chaîne de connexion constituent un risque de sécurité à éviter dans les applications de production. Les applications de production doivent utiliser le flux d’authentification le plus sécurisé disponible. Pour plus d’informations sur l’authentification des applications déployées sur des environnements de test ou de production, consultez ASP.NET rubriques de sécurité principales.

Les exemples de cet article utilisent des constructeurs principaux, disponibles en C# 12 (.NET 8) ou version ultérieure. Pour plus d’informations, consultez Déclarer des constructeurs principaux pour les classes et les structs (didacticiel de documentation C#) et les constructeurs principaux (Guide C#).

Lire les valeurs de configuration

La configuration est généralement lue en résolvant le IConfiguration service (Microsoft.Extensions.Configuration espace de noms) et en utilisant la clé de paires clé-valeur de configuration pour obtenir une valeur de configuration.

Le code de composant suivant Razor montre comment une valeur de configuration, une adresse e-mail de contact technique, est obtenue à partir de la configuration par la clé TechnicalContactEmail.

@inject IConfiguration Config

Technical Contact: @Config["TechnicalContactEmail"]

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

Les applications ASP.NET Core configurent et lancent un hôte. L’hôte est responsable de la gestion du démarrage et de la durée de vie des applications. Les paires clé-valeur de configuration de l’hôte sont incluses dans la configuration de l’application. Bien que vous puissiez effectuer une configuration d’application avec des fournisseurs de configuration d’hôte, nous vous recommandons uniquement d’effectuer la configuration nécessaire pour l’hôte dans la configuration de l’hôte.

La configuration de l’application est la priorité la plus élevée. Pour plus d’informations sur l’utilisation des fournisseurs de configuration lors de la génération de l’hôte et sur l’impact des sources de configuration sur la configuration de l’hôte, consultez Vue d’ensemble des notions de base d’ASP.NET Core.

Sources de configuration d’application par défaut

Les applications web ASP.NET Core appellent WebApplication.CreateBuilder pour initialiser une nouvelle instance de la classe WebApplicationBuilder avec des valeurs par défaut préconfigurés :

var builder = WebApplication.CreateBuilder(args);

Pour plus d’informations, consultez l’hôte générique .NET dans ASP.NET Core.

Applications créées à partir d’un appel Host.CreateDefaultBuilder de modèle de projet d’application web core ASP.NET Pour initialiser une nouvelle instance de la HostBuilder classe avec des valeurs par défaut préconfigurées :

Host.CreateDefaultBuilder(args)

La configuration d’application par défaut est chargée dans l’ordre suivant, de la plus haute à la priorité la plus basse :

Arguments de ligne de commande utilisant le fournisseur de configuration de ligne de commande.
Variables d’environnement non précédées ASPNETCORE_ ou DOTNET_ utilisant le fournisseur de configuration des variables d’environnement.
Secrets utilisateur lorsque l’application s’exécute dans l’environnement à l’aide Development du fournisseur de configuration de fichiers.
Configuration de fichier de paramètres d'application environnementale via appsettings.{ENVIRONMENT}.json, où l'espace réservé {ENVIRONMENT} est l'environnement de l'application, à l'aide du fournisseur de configuration JSON. Par exemple, appsettings.Production.json est utilisé en production et appsettings.Development.json est utilisé pendant le développement.
Configuration générale du fichier de paramètres d’applicationappsettings.json en utilisant le fournisseur de configuration JSON.
Configuration de l’hôte de secours.

Note

Nous vous déconseillons d’appeler CreateBuilder plusieurs fois uniquement pour obtenir des valeurs de configuration au moment de l’exécution. Nous vous recommandons d’utiliser un ConfigurationManager (par exemple : builder.Configuration, WebApplicationBuilder.Configuration) ou d’utiliser un ConfigurationBuilder à partir de la source de configuration appropriée.

Pour autoriser les arguments de ligne de commande à contrôler des paramètres tels que le nom de l’environnement, ce qui est important pour déterminer le fichier de paramètres d’application basé sur l’environnement à charger, le fournisseur de configuration de ligne de commande est utilisé deux fois comme source de configuration, au début et à la fin de la configuration. Étant donné que le fournisseur est utilisé à la fin, il a la priorité la plus élevée.

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.

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

Sources de configuration d’hôte par défaut de la priorité la plus élevée à la plus basse lorsqu’elle est appliquée à la configuration de l’application web (WebApplicationBuilder) :

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

Les sources de configuration d’hôte par défaut de la priorité la plus élevée à la plus basse appliquée à l’hôte générique ou à l’hôte web :

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

Pour plus d’informations sur la configuration de l’hôte, consultez les ressources suivantes :

Hôte générique : recommandé pour les applications ASP.NET Core ciblant .NET 6 ou version ultérieure qui adoptent le modèle d’hébergement minimal.
Hôte web : requis pour les applications ASP.NET Core qui ciblent les versions antérieures à .NET 6 et conservées uniquement par l’infrastructure pour la compatibilité descendante dans .NET 6 ou version ultérieure.

Sources de configuration d’hôte par défaut de la priorité la plus élevée à la plus basse pour l’hôte web :

Configuration de l’hôte
- Variables d’environnement précédées DOTNET_ (par exemple) DOTNET_ENVIRONMENTà 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.
Configuration par défaut de l’hôte web (ConfigureWebHostDefaults)
- Kestrel est utilisé comme serveur web et configuré à l’aide des fournisseurs de configuration de l’application.
- Ajouter un intergiciel de filtrage d’hôte.
- Ajoutez l’intergiciel des 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.

Variables d’hôte

Les variables suivantes sont définies au début de l’initialisation du générateur d’hôtes et ne peuvent pas être influencées par la configuration d’application :

Nom de l’application.
Nom de l’environnement.
Racine du contenu.
Racine web.
Indique s’il faut effectuer une analyse à la recherche d’assemblys d’hébergement au démarrage et spécifie les assemblys à analyser.
Variables lues par le code de l’application et de la bibliothèque dans les rappels de HostBuilderContext.Configuration en IHostBuilder.ConfigureAppConfiguration.

D’autres paramètres d’hôte sont lus à 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 ne sont pas initialisés par la configuration de l’hôte. URLS est lu ultérieurement dans la configuration de l'application. La configuration de l’hôte est un secours pour la configuration d’application. Par conséquent, la configuration de l’hôte peut être utilisée pour définir URLS, mais la valeur est remplacée par n’importe quelle source de configuration définie URLS dans la configuration de l’application, telle que les fichiers de paramètres d’application (appsettings.{ENVIRONMENT}.jsonoù l’espace {ENVIRONMENT} réservé est le nom de l’environnement ou appsettings.json).

Pour plus d’informations, consultez Modifier la racine de 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.

Sécurité et secrets d’utilisateur

Instructions relatives aux données de configuration :

Ne stockez jamais des mots de passe ou d’autres données sensibles dans le code du fournisseur de configuration ou dans les fichiers de configuration en texte clair. Vous pouvez utiliser l’outil Secret Manager pour stocker des secrets lors du développement.
N’utilisez aucun secret de production dans les environnements de développement ou de test.
Spécifiez les secrets en dehors du projet afin qu’ils ne puissent pas être validés par inadvertance dans un référentiel de code source.
Les applications de production doivent utiliser le flux d’authentification le plus sécurisé disponible. Pour plus d’informations, consultez Flux d’authentification sécurisés.

La source de configuration du fichier secrets utilisateur des sources de configuration par défaut est inscrite après les sources de configuration JSON pour les fichiers de paramètres d’application. Par conséquent, les clés des secrets utilisateur sont prioritaires sur les clés dans appsettings.json et appsettings.{ENVIRONMENT}.json.

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

environnements d’exécution ASP.NET Core
Stockage sécurisé des secrets d’application en développement dans ASP.NET Core : comprend des conseils sur l’utilisation de variables d’environnement pour stocker les données sensibles. L’outil Gestionnaire de secrets utilise le fournisseur de configuration de fichiers pour stocker les secrets utilisateur dans un fichier JSON sur le système local.
Azure Key Vault stocke en toute sécurité des secrets d’application pour les applications ASP.NET Core. Pour plus d’informations, consultez Fournisseur de configuration Azure Key Vault dans ASP.NET Core.

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

La configuration peut être injectée dans des services à l’aide de l’injection de dépendances (DI) en résolvant le IConfiguration service. Dans l’exemple suivant, la valeur de configuration stockée pour la clé de configuration représentée par l’espace {KEY} réservé est affectée à value. Si la clé est introuvable, null est assigné à value:

public class CustomService(IConfiguration config)
{
    public void CustomMethod()
    {
        var value = config["{KEY}"];
    }
}

Configuration d’accès dans le `Program` fichier

Le code suivant accède à la configuration dans le fichier à l’aide de ProgramWebApplicationBuilder.Configuration (builder.Configuration) :

var defaultConnectionString = 
   builder.Configuration.GetValue<string>("ConnectionStrings:DefaultConnection");

Une fois l’application générée (après la ligne var app = builder.Build();), utilisez WebApplication.Configuration (app.Configuration) :

var defaultLogLevel = app.Configuration.GetValue<string>("Logging:LogLevel:Default");

Configuration d’accès dans la `Startup` classe

Cette section s’applique généralement aux applications ASP.NET Core avant la publication de .NET 6.

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

public class Startup
{
    public Startup(IConfiguration config)
    {
        Config = config;
    }

    public IConfiguration Config { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        var connectionString = Config["ConnectionStrings.DefaultConnection"];

        ...
    }

    public void Configure(...)
    {
        var defaultLogLevel = Config["Logging:LogLevel:Default"];

        ...
    }
}

Afficher les paramètres de configuration au démarrage pour le débogage

Le code suivant affiche les paires clé-valeur de configuration de l’application au démarrage de l’application.

Une fois l’application générée dans le Program fichier (après la ligne var app = builder.Build();), placez le code suivant, qui inclut une directive du compilateur pour la configuration DEBUG :

#if DEBUG
foreach (var c in app.Configuration.AsEnumerable())
{
    Console.WriteLine($"CONFIG: Key: {c.Key} Value: {c.Value}");
}
#endif

Dans le constructeur de classe de l'application Startup, injectez IConfiguration, config dans l’exemple suivant pour écrire les paires clé-valeur de configuration dans la console. L’exemple suivant inclut une directive du compilateur pour la configuration DEBUG :

#if DEBUG
foreach (var c in config.AsEnumerable())
{
    Console.WriteLine($"CONFIG: Key: {c.Key} Value: {c.Value}");
}
#endif

Clés et valeurs de configuration

Clés de configuration :

Insensible à 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 par 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.
- Sur certaines plateformes, un séparateur par deux-points dans les variables d’environnement ne fonctionne pas. Un trait de soulignement double (__) est pris en charge par toutes les plateformes et est automatiquement converti en deux-points (:) lorsque la configuration est lue par l’application.
- Dans Azure Key Vault, les clés hiérarchiques utilisent des tirets doubles (--) comme séparateur. Le fournisseur de configuration Azure Key Vault remplace automatiquement les tirets doubles (--) par un deux-points (:) lorsque les secrets sont chargés dans la configuration de l'application.
ConfigurationBinder prend en charge la liaison de tableaux à des objets à l’aide d’index de tableau dans les clés de configuration. La liaison de tableau est décrite dans la section Lier un tableau .

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

Organisation des données de configuration hiérarchique

L’API Configuration lit les données de configuration hiérarchiques en les aplatissant à l’aide d’un délimiteur dans les clés de configuration, souvent des deux-points (:). Les traits de soulignement doubles (__) sont généralement utilisés dans la configuration des variables d’environnement pour la prise en charge multiplateforme.

Note

Dans les scénarios de configuration d’applications complexes, il est préférable de regrouper et de lire les données de configuration hiérarchique associées à l’aide du modèle d’options.

Tenez compte des données de configuration hiérarchique suivantes :

ConnectionStrings
- DefaultConnection (Value = 'Data Source=LocalSqlServer\MSSQLDev;')
Logging
- LogLevel
  - Default (Value = 'Information')
  - Microsoft (Value = 'Warning')
  - Microsoft.Hosting.Lifetime (Value = 'Information')
AllowedHosts (Value = '*')

Le tableau suivant affiche les clés utilisées pour récupérer les valeurs dans les données de configuration précédentes. Le délimiteur n’est pas requis pour AllowedHosts.

Clé (délimiteur de deux-points)	Clé (délimiteur de trait de soulignement double)
`ConnectionStrings:DefaultConnection`	`ConnectionStrings__DefaultConnection`
`Logging:LogLevel:Default`	`Logging__LogLevel__Default`
`Logging:LogLevel:Microsoft`	`Logging__LogLevel__Microsoft`
`Logging:LogLevel:Microsoft.Hosting.Lifetime`	`Logging__LogLevel__Microsoft.Hosting.Lifetime`
`AllowedHosts`	`AllowedHosts`

Note

Dans les scénarios de configuration d’applications complexes, nous vous recommandons de regrouper et de lire les données de configuration hiérarchique associées à l’aide du modèle Options.

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 où GetSection, GetChildrenet Exists sont couvertes.

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 le chemin d’accès. Considérez les données de configuration hiérarchique suivantes sous forme de tableau.

MainObject (un tableau) :

Premier élément du tableau
- Object0
- Object1
  - SubObject0
  - SubObject1
Deuxième élément dans le tableau
- Object0
- Object1
  - SubObject0
  - SubObject1

Clés avec des séparateurs de deux-points :

MainObject:0:Object0
MainObject:0:Object1:SubObject0
MainObject:0:Object1:SubObject1
MainObject:1:Object0
MainObject:1:Object1:SubObject0
MainObject:1:Object1:SubObject1

Les clés avec des séparateurs underscore, recommandées pour la compatibilité multiplateforme lorsque la configuration est fournie par des variables d'environnement :

MainObject__0__Object0
MainObject__0__Object1:SubObject0
MainObject__0__Object1:SubObject1
MainObject__1__Object0
MainObject__1__Object1:SubObject0
MainObject__1__Object1:SubObject1

Étant donné que les configurations provenant de tableaux sont aplaties et numérotées séquentiellement pour chaque source de configuration utilisée par une application, les valeurs peuvent être écrasées de manière inattendue si l'on ne prend pas soin de structurer et de lire les données à partir de plusieurs sources. Tenez compte des paires clé-valeur de configuration suivantes :

Modules valeurs (tableau) :

Module1
Module2
Module3

Le tableau est aplatit et indexé de façon séquentielle, ce qui génère les paires clé-valeur de configuration dans le tableau suivant.

Key	Valeur
`Modules:0`	`Module1`
`Modules:1`	`Module2`
`Modules:2`	`Module3`

Une fois la configuration précédente établie, une autre source de configuration charge la configuration suivante :

Modules valeurs (tableau) :

Module4
Module5

Ce tableau est également aplatit et indexé séquentiellement.

Key	Valeur
`Modules:0`	`Module4`
`Modules:1`	`Module5`

Rappelant que la dernière source de configuration d’une clé donnée définit la valeur de cette clé, le dernier ensemble de paires clé-valeur de configuration est indiqué dans le tableau suivant.

Key	Valeur
`Modules:0`	`Module4`
`Modules:1`	`Module5`
`Modules:2`	`Module3`

Ce n’est pas un résultat surprenant étant donné la façon dont le cadre aplatit et indexe les données de tableau à partir de sources de configuration, mais il convient de garder à l’esprit qu’il faut éviter les remplacements inattendus.

Pour éviter de tels écrasements, l'indexation des tableaux doit être structurée de manière à s'aligner avec les différentes sources de configuration qui fournissent les mêmes données de tableau. Une autre approche consiste à délimiter les valeurs de tableau dans une chaîne de caractères d'une paire clé-valeur unique, par exemple à l'aide d'une virgule, d'un point-virgule ou d'une barre verticale comme délimiteur. Écrivez du code personnalisé pour fractionner la chaîne et affecter les valeurs délimitées à votre tableau.

Fournisseurs de configuration

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

Provider	Fournit la configuration à partir de...
Fournisseur de configuration Azure Key Vault	Azure Key Vault
Fournisseur de Configuration des Applications Azure	Configuration d'application Azure
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 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 où leurs fournisseurs de configuration sont spécifiés. Organisez les fournisseurs de configuration dans le code en fonction des priorités pour les sources de configuration sous-jacentes nécessaires pour l’application.

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

Paramètres généraux de l’application via appsettings.json.
Paramètres de l’application environnementale via appsettings.{ENVIRONMENT}.json, où l’espace {ENVIRONMENT} réservé est l’environnement de l’application (exemples : Development, Production).
Secrets utilisateur.
Variables d’environnement à l’aide du fournisseur de configuration des variables d’environnement.
Arguments de ligne de commande utilisant le fournisseur de configuration de ligne de commande.

Une pratique courante consiste à ajouter le fournisseur de configuration de ligne de commande en dernier dans une série de fournisseurs pour autoriser les arguments de ligne de commande à remplacer la configuration définie par les autres fournisseurs.

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

Pour inspecter les fournisseurs de configuration de l’application, l’injecter, le IConfiguration caster IConfigurationRootet lire la Providers propriété.

Dans le composant suivant ConfigurationProvidersRazor , les fournisseurs de configuration activés s’affichent dans l’ordre dans lequel ils sont ajoutés à l’application.

Pages/ConfigurationProviders.razor :

@page "/configuration-providers"
@inject IConfiguration Config

<h1>Configuration Providers</h1>

@if (ConfigRoot is not null)
{
    <ul>
        @foreach (var provider in ConfigRoot.Providers)
        {
            <li>@provider</li>
        }
    </ul>
}

@code {
    private IConfigurationRoot? ConfigRoot;

    protected override void OnInitialized()
    {
        ConfigRoot = (IConfigurationRoot)Config;
    }
}

Le composant précédent Razor génère la sortie suivante, où le remplacement {APP NAMESPACE} correspond à l'espace de noms de l'application :

MemoryConfigurationProvider
EnvironmentVariablesConfigurationProvider Prefix: 'ASPNETCORE_'
MemoryConfigurationProvider
EnvironmentVariablesConfigurationProvider Prefix: 'DOTNET_'
JsonConfigurationProvider for 'appsettings.json' (Optional)
JsonConfigurationProvider for 'appsettings.Development.json' (Optional)
JsonConfigurationProvider for '{APP NAMESPACE}.settings.json' (Optional)
JsonConfigurationProvider for '{APP NAMESPACE}.settings.Development.json' (Optional)
EnvironmentVariablesConfigurationProvider
Microsoft.Extensions.Configuration.ChainedConfigurationProvider

Dans la section Sources de configuration d’application par défaut plus haut dans cet article, les sources de configuration sont répertoriées de la priorité la plus élevée à la plus basse. Le composant précédent ConfigurationProviders affiche les sources dans l’ordre dans lequel l’application les lit. Par exemple, le fournisseur de configuration JSON pour le fichier de paramètres d’application non environnemental (appsettings.json) est antérieur à la liste précédente, car il est ajouté avant le fournisseur pour le fichier de paramètres de l’application d’environnement de développement (appsettings.Development.json). Les fournisseurs de configuration sont exécutés du haut de la liste au bas de la liste. Pour une clé de configuration correspondante entre les deux fournisseurs de configuration JSON des paramètres d’application, le dernier paramètre est prioritaire, qui est la valeur de appsettings.Development.json.

Configuration du fichier de paramètres d’application (`appsettings.json`, `appsettings.{ENVIRONMENT}.json`)

Lire la configuration chargée à partir des fichiers de paramètres d’application à l’aide du fournisseur de configuration JSON.

Examinons le fichier appsettings.json suivant :

{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=LocalSqlServer\\MSSQLDev;"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Injectez une instance de pour lire les valeurs de configuration.

Le composant suivant AppSettingsConfigurationRazor lit la chaîne de connexion de base de données par défaut et la configuration au niveau de journalisation par défaut. IConfiguration est injecté en haut du composant et utilisé pour lire les valeurs de configuration. Un séparateur deux-points (:) est utilisé dans les clés de configuration de type chaîne pour localiser les propriétés JSON appropriées. Par exemple, la structure JSON de l’objet de chaîne de connexion par défaut (DefaultConnection) est imbriquée sous l’objet chaînes de connexion (ConnectionStrings), de sorte que la notation de chaîne pour accéder à la chaîne de connexion par défaut utilise un signe deux-points pour séparer DefaultConnection et ConnectionStrings dans l’ordre dans lequel les objets apparaissent dans le fichier des paramètres de l’application : ConnectionStrings:DefaultConnection

Pages/AppSettingsConfiguration.razor :

@page "/app-settings-configuration"
@inject IConfiguration Config

<h1>App Settings Configuration</h1>

<ul>
    <li>Default Connection String: @Config["ConnectionStrings:DefaultConnection"]
    <li>Default Log Level: @Config["Logging:LogLevel:Default"]
</ul>

Dans un modèle de page Razor Pages, la même approche est adoptée :

using Microsoft.Extensions.Configuration;

...

public class AppSettingsPageModel(IConfiguration config) : PageModel
{
    public ContentResult OnGet()
    {
        var defaultConnectionString = config["ConnectionStrings:DefaultConnection"];
        var defaultLogLevel = config["Logging:LogLevel:Default"];

        return Content(
            $"Default Connection String: {defaultConnectionString}\n" +
            $"Default Log Level: {defaultLogLevel}");
    }
}

Les instances par défaut JsonConfigurationProvider chargent la configuration dans l’ordre suivant :

appsettings.json
appsettings.{ENVIRONMENT}.json, où l’espace {ENVIRONMENT} réservé est l’environnement de l’application (exemples : appsettings.Production.json, appsettings.Development.json). La version environnementale du fichier est chargée en fonction de IHostingEnvironment.EnvironmentName.

Les valeurs appsettings.{ENVIRONMENT}.json remplacent les clés dans appsettings.json.

Par défaut :

Dans l’environnement de développement, appsettings.Development.json la configuration remplace les valeurs trouvées dans appsettings.json.
Dans l’environnement de production, appsettings.Production.json la configuration remplace les valeurs trouvées dans appsettings.json.

L’exemple précédent lit uniquement les chaînes et ne prend pas en charge une valeur par défaut. Si une valeur de configuration doit être garantie avec une valeur par défaut, consultez la section Extraire une valeur unique de la configuration avec la conversion de type (GetValue).

À l’aide des sources de configuration d’application par défaut, les fichiers appsettings.json et appsettings.{ENVIRONMENT}.json sont activés avec reloadOnChange défini sur true, ce qui signifie que les modifications apportées soit aux fichiers appsettings.json soit appsettings.{ENVIRONMENT}.json après le démarrage de l’application prennent effet immédiatement après l’enregistrement du fichier.

Pour qu'ils soient pris en charge dans les fichiers appsettings.json et appsettings.{ENVIRONMENT}.json, les commentaires doivent utiliser la syntaxe des commentaires C# ou JavaScript. Certains environnements de développement intégrés affichent des erreurs lors de la modification d’un fichier JSON contenant des commentaires, car la spécification JSON officielle (RFC 7159) n’est pas prise en compte pour les commentaires dans les fichiers JSON. Vous pouvez généralement ignorer les erreurs de commentaire et les avertissements, mais vous pouvez également désactiver les avertissements ou les erreurs avec un paramètre dans l’IDE. Dans Visual Studio Code, par exemple, ajoutez ce qui suit au settings.json fichier pour désactiver les erreurs :

"files.associations": {
  "appsettings*.json": "jsonc"
}

Le paramètre précédent indique à VS Code que les fichiers de paramètres d’application, y compris les fichiers basés sur l’environnement, sont associés au format de fichier JSONC (« JSON with Comments ») qui prend en charge les commentaires.

Pour d’autres IDE, consultez la documentation de l’IDE et les canaux de prise en charge des produits pour déterminer comment silence les erreurs ou les avertissements relatifs aux commentaires dans les fichiers JSON.

Fournisseur de configuration des variables d’environnement

Le fournisseur de configuration des variables d’environnement par défaut (EnvironmentVariablesConfigurationProvider) charge la configuration à partir de variables d'environnement qui ne sont pas préfixées par ASPNETCORE_ ou DOTNET_. Pour plus d’informations sur les variables d’environnement ASPNETCORE_ et DOTNET_, consultez la section Sources de configuration de l’hôte par défaut et les variables d’environnement DOTNET_ (documentation .NET Core).

À l’aide du fournisseur de configuration des variables d’environnement par défaut, l’application charge la configuration à partir de paires clé-valeur de variable d’environnement après la lecture appsettings.json, appsettings.{ENVIRONMENT}.jsonet les secrets utilisateur. Par conséquent, les valeurs de clés lues à partir de l’environnement remplacent les valeurs lues à partir de appsettings.json, appsettings.{ENVIRONMENT}.json et les secrets de l’utilisateur.

Le séparateur : ne fonctionne pas avec les clés hiérarchiques des variables d’environnement sur toutes les plateformes. Par exemple, le : séparateur n’est pas pris en charge par Bash. Le double trait de soulignement __, est pris en charge par toutes les plateformes et remplacé automatiquement par un signe deux-points :.

Pour obtenir des conseils sur la définition de variables d’environnement dans un interpréteur de commandes sur Windows ou dans un interpréteur de commandes PowerShell multiplateforme, consultez les ressources suivantes :

Préfixe personnalisé pour les variables d’environnement

Vous pouvez ajouter un fournisseur de configuration pour les variables d’environnement préfixées personnalisées. Dans le fichier Program, appelez AddEnvironmentVariables avec une chaîne pour spécifier un préfixe après l'appel de WebApplication.CreateBuilder. Le fournisseur est ajouté après les fournisseurs de configuration par défaut. Par conséquent, le fournisseur ajouté a une priorité plus élevée, y compris sur les variables d’environnement du même nom sans le préfixe.

Dans l’exemple suivant, les variables d’environnement sont ajoutées avec le CustomPrefix_ préfixe :

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

Vous pouvez ajouter un fournisseur de configuration pour les variables d’environnement préfixées personnalisées. Dans le fichier Program, appelez AddEnvironmentVariables avec une chaîne pour spécifier un préfixe sur le IConfigurationBuilder de ConfigureAppConfiguration. Le fournisseur est ajouté après les fournisseurs de configuration par défaut. Par conséquent, le fournisseur ajouté a une priorité plus élevée, y compris sur les variables d’environnement du même nom sans le préfixe.

Dans l’exemple suivant, les variables d’environnement sont ajoutées avec le CustomPrefix_ préfixe :

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

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

Les paramètres de lancement remplacent les paramètres de variable d’environnement

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

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

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

Échappement des variables d’environnement sur Linux

Sur Linux, la valeur des variables d’environnement d’URL doit être placée dans une séquence d’échappement pour que systemd puisse l’analyser. Dans l’exemple suivant, l’outil systemd-escape Linux est utilisé pour générer http:--localhost:5001 à partir de http://localhost:5001:

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

Paramètres d’application Azure App Service (variables d’environnement)

Pour obtenir des conseils sur les paramètres d’application Azure App Service (variable d’environnement), consultez les ressources suivantes :

Préfixes des chaînes de connexion

L’API de configuration présente des règles de traitement spéciales pour quatre variables d’environnement de chaîne de connexion. Ces chaînes de connexion sont impliquées dans la configuration des chaînes de connexion Azure pour l’environnement de l’application. Les variables d’environnement avec les préfixes indiqués dans le tableau suivant 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	Provider
`CUSTOMCONNSTR_`	Fournisseur personnalisé
`MYSQLCONNSTR_`	MySQL
`SQLAZURECONNSTR_`	Base de données SQL Azure
`SQLCONNSTR_`	SQL Server

Lorsqu’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 précédent :

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 connexions de base de données, sauf pour CUSTOMCONNSTR_, qui n’a pas de 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`

Command-line

À l’aide des sources de 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 :

Fichiers appsettings.json et appsettings.{ENVIRONMENT}.json.
Secrets d’application dans l’environnement Development .
Variables d'environnement.

Par défaut, les valeurs de configuration définies sur la ligne de commande remplacent les valeurs de configuration définies par tous les autres fournisseurs de configuration.

Arguments de ligne de commande

La commande suivante dotnet run définit des clés et des valeurs à l’aide de signes égaux (=) :

dotnet run ConnectionStrings:DefaultConnection="Data Source=LocalSqlServer\\MSSQLDev;" Logging:LogLevel:Default=Information

La commande suivante définit des clés et des valeurs à l’aide de barres obliques (/) :

dotnet run /ConnectionStrings:DefaultConnection "Data Source=LocalSqlServer\\MSSQLDev;" /Logging:LogLevel:Default Information

La commande suivante définit des clés et des valeurs à l’aide de tirets doubles (--) :

dotnet run --ConnectionStrings:DefaultConnection "Data Source=LocalSqlServer\\MSSQLDev;" --Logging:LogLevel:Default Information

Conventions d’argument :

La valeur de clé doit suivre le signe égal (=), ou la clé doit avoir un préfixe d’un tiret double (--) ou d’une barre oblique (/) lorsque la valeur suit un espace.
Ne pas assigner une valeur après un signe égal (=) entraîne l'affectation d'une chaîne vide pour le paramètre de configuration. Par exemple, la ConnectionStrings:DefaultConnection= spécification est valide et entraîne l’affectation d’une chaîne vide à la chaîne de connexion par défaut.
Dans la même commande, ne mélangez pas les paires clé-valeur d’argument séparées par un signe égal (=) avec des paires clé-valeur séparées par un espace.

Mappages de commutateurs

Les mappages de commutateurs autorisent la logique de remplacement de nom de clé via un dictionnaire de remplacements de commutateur transmis à la AddCommandLine méthode.

Quand le dictionnaire de correspondances de commutateur est utilisé, il est vérifié afin de déterminer s’il contient une clé correspondant à celle fournie par un argument de ligne de commande. Si la clé de ligne de commande est trouvée dans le dictionnaire, la valeur du dictionnaire est retournée pour définir la paire clé-valeur dans la configuration de l’application. Une correspondance de commutateur est nécessaire pour chaque clé de ligne de commande préfixée avec un tiret unique (-).

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

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

Dans l’exemple suivant, un dictionnaire de correspondance des commutateurs (switchMappings) est passé à AddCommandLine dans le fichier de l’application Program :

var switchMappings = 
    new Dictionary<string, string>(){ { "-k1", "key1" }, { "-k2", "key2" } };

builder.Configuration.AddCommandLine(args, switchMappings);

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
.ConfigureAppConfiguration(config =>
{ 
    var switchMappings =
        new Dictionary<string, string>() { { "-k1", "key1" }, { "-k2", "key2" } };

    config.AddCommandLine(args, switchMappings);
});

Les commandes suivantes dotnet run illustrent le remplacement de clé (remplaçant value1 par key1 et value2 par key2) :

dotnet run -k1 value1 -k2 value2
dotnet run --k1=value1 --k2=value2
dotnet run --k1 value1 --k2 value2
dotnet run /k1=value1 /k2=value2
dotnet run /k1 value1 /k2 value2

Pour les applications qui utilisent des mappages de commutateurs, l’appel à CreateDefaultBuilder ne doit pas passer d’arguments. L’appel CreateDefaultBuilder de la méthode AddCommandLine n’inclut pas de commutateurs mappés. Il n’existe aucun moyen de transmettre le dictionnaire de mappage de commutateur à CreateDefaultBuilder. La solution ne consiste pas à transmettre les arguments à CreateDefaultBuilder, mais à permettre à la méthode ConfigurationBuilder de la méthode AddCommandLine de traiter à la fois les arguments et le dictionnaire de correspondance de commutateur.

Pour les applications qui utilisent des mappages de commutateurs, l’appel à CreateDefaultBuilder ne doit pas passer d’arguments. L’appel CreateDefaultBuilder de la méthode AddCommandLine n’inclut pas de commutateurs mappés. Il n’existe aucun moyen de transmettre le dictionnaire de mappage de commutateur à CreateDefaultBuilder. La solution ne consiste pas à transmettre les arguments à CreateDefaultBuilder, mais à permettre à la méthode IConfigurationBuilder de la méthode AddCommandLine de traiter à la fois les arguments et le dictionnaire de correspondance de commutateur.

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

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

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

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

Fournisseur de configuration INI

Le IniConfigurationProvider charge la configuration à partir des paires clé-valeur du fichier INI. L’exemple suivant montre comment utiliser le fournisseur. Les surcharges peuvent spécifier si le fichier est facultatif et si la configuration est rechargée sur les modifications apportées au fichier.

IniConfig.ini :

[ConnectionStrings]
DefaultConnection="Data Source=LocalSqlServer\\MSSQLDev;"

[Logging:LogLevel]
Default=Debug
Microsoft=Debug

IniConfig.Production.ini :

[ConnectionStrings]
DefaultConnection="Data Source=LocalSqlServer\\MSSQLProd;"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Chargez la configuration en appelant AddIniFile. L’exemple suivant crée une source de configuration pour chacun des fichiers précédents. Le fichier non environnemental recharge la configuration si le fichier est modifié (reloadOnChange paramètre, valeur par défaut : false). La version environnementale du fichier spécifie que le fichier est facultatif (optional paramètre, valeur par défaut : false). Si vous souhaitez spécifier le rechargement du fichier lors de la modification (reloadOnChange: true), vous devez également spécifier si le fichier est facultatif ou non (optional).

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

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
.ConfigureAppConfiguration(config =>
{ 
    config
        .AddIniFile("IniConfig.ini", optional:false, reloadOnChange: true)
        .AddIniFile("IniConfig.Production.ini", optional: true);
});

Fournisseur de configuration JSON

JsonConfigurationProvider charge la configuration à partir des paires clé-valeur du fichier JSON. L’exemple suivant montre comment utiliser le fournisseur. Les surcharges peuvent spécifier si le fichier est facultatif et si la configuration est rechargée sur les modifications apportées au fichier.

Appelez AddJsonFile avec le chemin d’accès du fichier (ou le nom de fichier si le fichier se trouve à la racine de l’application). Les éléments suivants rendent le fichier facultatif (optional paramètre, valeur par défaut : false) et spécifie que la configuration est rechargée si le fichier est modifié (reloadOnChange paramètre, valeur par défaut : false). Si vous souhaitez spécifier le rechargement du fichier lors de la modification (reloadOnChange: true), vous devez également spécifier si le fichier est facultatif ou non (optional).

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

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
.ConfigureAppConfiguration(config =>
{ 
    config.AddJsonFile("config.json", optional: true, reloadOnChange: true);
});

Fournisseur de configuration XML

La XmlConfigurationProvider charge la configuration à partir des paires clé-valeur d'un fichier XML. L’exemple suivant montre comment utiliser le fournisseur. Les surcharges peuvent spécifier si le fichier est facultatif et si la configuration est rechargée sur les modifications apportées au fichier.

XmlFile.xml :

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <ConnectionStrings>
    <DefaultConnection>Data Source=LocalSqlServer\\MSSQLDev;</DefaultConnectionString>
  </ConnectionStrings>
  <Logging>
    <LogLevel>
      <Default>Debug</Default>
      <Microsoft>Debug</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

XmlFile.Production.xml :

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <ConnectionStrings>
    <DefaultConnectionString>Data Source=LocalSqlServer\\MSSQLProd;</DefaultConnectionString>
  </ConnectionStrings>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

Chargez la configuration en appelant AddXmlFile. L’exemple suivant crée une source de configuration pour chacun des fichiers précédents. Le fichier non environnemental recharge la configuration si le fichier est modifié (reloadOnChange paramètre, valeur par défaut : false). La version environnementale du fichier spécifie que le fichier est facultatif (optional paramètre, valeur par défaut : false). Si vous souhaitez spécifier le rechargement du fichier lors de la modification (reloadOnChange: true), vous devez également spécifier si le fichier est facultatif ou non (optional).

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

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
.ConfigureAppConfiguration(config =>
{ 
    config
        .AddXmlFile("XmlFile.xml", optional:false, reloadOnChange: true)
        .AddXmlFile("XmlFile.Production.xml", optional: true);
});

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>

var value_00 = Config["section:section0:key:key0"];
var value_01 = Config["section:section0:key:key1"];
var value_10 = Config["section:section1:key:key0"];
var value_11 = Config["section:section1:key:key1"];

Les attributs qui fournissent des valeurs sont pris en charge :

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <key attribute="value" />
  <section>
    <key attribute="value" />
  </section>
</configuration>

La configuration précédente charge les clés suivantes avec value:

key:attribute
section:key:attribute

Fournisseur de configuration par 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 key-Per-File 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.

var path = Path.Combine(Directory.GetCurrentDirectory(), "path/to/files");
builder.Configuration.AddKeyPerFile(directoryPath: path, optional: true);

.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 en mémoire au système de configuration :

var configSettings = new Dictionary<string, string>
{
    { "ConnectionStrings:DefaultConnection", "Data Source=LocalSqlServer\\MSSQLDev;" },
    { "Logging:LogLevel:Default", "Information" }
};

builder.Configuration.AddInMemoryCollection(configSettings);

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
    .ConfigureAppConfiguration(config =>
    { 
        var configSettings = new Dictionary<string, string>
        {
            { "ConnectionStrings:DefaultConnection", "Data Source=LocalSqlServer\\MSSQLDev;" },
            { "Logging:LogLevel:Default", "Information" }
        };

        config.AddInMemoryCollection(configSettings);
    });

Configuration du point de terminaison Kestrel

KestrelLa 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 comprennent notamment :

UseUrls.
--urls sur la ligne de commande.
La ASPNETCORE_URLSvariable d’environnement.

Considérez la section de configuration suivante Kestrel dans un appsettings.json fichier :

"Kestrel": {
  "Endpoints": {
    "Https": {
      "Url": "https://localhost:9999"
    }
  }
},

L’application est lancée sur la ligne de commande avec dotnet run et la configuration de point de terminaison inter-serveur suivante :

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

Kestrel se lie au point de terminaison configuré spécifiquement pour Kestrel dans le fichier appsettings.json (https://localhost:9999) et non à la configuration du point de terminaison inter-serveurs transmise à la commande dotnet run (https://localhost:7777).

Toutefois, considérez le Kestrelpoint de terminaison spécifique configuré comme variable d’environnement :

Clé :Kestrel__Endpoints__Https__Url
Valeur: https://localhost:8888

Dans la variable d’environnement précédente, «Https » est le nom du point de terminaison Kestrel spécifique. La configuration des paramètres d’application précédente définit également un Kestrelpoint de terminaison spécifique nommé Https. Selon les fournisseurs de configuration d’hôte par défaut, les variables d’environnement lues par 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 (Kestrel__Endpoints__Https__Url) est utilisée pour le Https point de terminaison.

Extraire une valeur unique de la configuration avec conversion de type (`GetValue`)

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

var number = Config.GetValue<int>("NumberKey", 99);

Dans le code précédent :

Config est un IConfiguration injecté.
Si NumberKey n'est pas trouvé dans la configuration, la valeur par défaut 99 est utilisée.

Utiliser des sections, obtenir les enfants d’une section et déterminer si une section existe

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

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

Un fournisseur de configuration est ajouté pour subsection.json par appel de AddJsonFile.

`GetSection`

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

Le code suivant retourne des valeurs pour section1, où Config est injecté IConfiguration:

var subsection = Config.GetSection("section1");
var value1 = subsection["key0"];
var value2 = subsection["key1"];

Le code suivant retourne des valeurs pour section2:subsection0, où Config est injecté IConfiguration:

var subsection = Config.GetSection("section2:subsection0");
var value1 = subsection["key0"];
var value2 = subsection["key1"];

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

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

`GetChildren` et `Exists`

Les appels de code suivants :

ConfigurationExtensions.Exists pour vérifier qu’il section2 existe.
IConfiguration.GetChildren et retourne des valeurs pour les sous-sections de section2.

var section = Config.GetSection("section2");

if (!section.Exists())
{
    throw new Exception("section2 doesn't exist!");
}

var children = section.GetChildren();

foreach (var subSection in children)
{
    int i = 0;
    var key1 = subSection.Key + ":key" + i++.ToString();
    var key2 = subSection.Key + ":key" + i.ToString();
    Console.WriteLine($"{key1} value: {section[key1]}");
    Console.WriteLine($"{key2} value: {section[key2]}");
}

Sortie:

subsection0:key0 value: value200
subsection0:key1 value: value201
subsection1:key0 value: value210
subsection1:key1 value: value211

Lier un tableau

ConfigurationBinder.Bind prend en charge la liaison de tableaux à des objets à l’aide d’index de tableau dans les clés de configuration. Tout format de tableau qui expose un segment de clé numérique est capable d’effectuer la liaison de tableau avec un tableau de classes POCO.

array.json :

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

Un fournisseur de configuration est ajouté pour array.json par appel de AddJsonFile.

Le code suivant lit les valeurs de configuration.

ArrayExample.cs :

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

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

if (array is null)
{
    throw new ArgumentNullException(nameof(array));
}

for (int j = 0; j < array.Entries?.Length; j++)
{
    Console.WriteLine($"Index: {j} Value: {array.Entries[j]}");
}

Sortie:

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

Dans la sortie précédente, l’index 3 a la valeur value40, ce qui correspond à "4": "value40", dans array.json. Les index de tableau lié sont contenus et ne sont pas liés à l’index de clé de configuration. Le classeur de configuration n’est pas capable de lier null des valeurs ou de créer null des entrées dans des objets liés.

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 Index 3. Dans l’exemple suivant, supposons que les valeurs fournies array.json dans l’exemple précédent sont fournies par une collection en mémoire. L’exemple montre comment charger la valeur Index 3 à partir du fournisseur de configuration JSON avant la liaison de la collection.

value3.json :

{
  "array:entries:3": "value30"
}

var configSettings = new Dictionary<string, string>
{
    { "array:entries:0", "value00" },
    { "array:entries:1", "value10" },
    { "array:entries:2", "value20" },
    { "array:entries:4", "value40" },
    { "array:entries:5", "value50" }
};

builder.Configuration.AddInMemoryCollection(configSettings);
builder.Configuration.AddJsonFile("value3.json", optional: false, 
    reloadOnChange: false);

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
    .ConfigureAppConfiguration(config =>
    { 
        var configSettings = new Dictionary<string, string>
        {
            { "array:entries:0", "value00" },
            { "array:entries:1", "value10" },
            { "array:entries:2", "value20" },
            { "array:entries:4", "value40" },
            { "array:entries:5", "value50" }
        };

        config.AddInMemoryCollection(configSettings);
        config.AddJsonFile("value3.json", optional: false, reloadOnChange: false);
    });

Le code précédent génère le tableau lié suivant :

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

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

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

Note

L’exemple nécessite les instructions suivantes using :

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) => 
        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 sont insensibles à la casse, le dictionnaire utilisé pour initialiser la base de données est créé avec un comparateur indifférent à la casse. StringComparer.OrdinalIgnoreCase

EFConfigurationProvider/EFConfigurationProvider.cs :

using Microsoft.EntityFrameworkCore;

public class EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction) : ConfigurationProvider
{
    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 Dictionary<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;
    }
}

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

Note

L’exemple nécessite les instructions suivantes using :

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

public static class EntityFrameworkExtensions
{
    public static IConfigurationBuilder AddEFConfiguration(
        this IConfigurationBuilder builder,
        Action<DbContextOptionsBuilder> optionsAction)
    {
        return builder.Add(new EFConfigurationSource(optionsAction));
    }
}

Le code suivant montre comment utiliser le composant personnalisé EFConfigurationProvider dans le fichier Program de l'application :

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

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

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.

Ajouter la configuration à partir d’un assembly externe

Une implémentation de IHostingStartup permet d’ajouter des améliorations à une application au démarrage à partir d’un assembly externe, en dehors de la classe Startup de l’application. Pour plus d’informations, consultez Utiliser des assemblys d’hébergement au démarrage dans ASP.NET Core.

Générateur de source de liaison de configuration

Le Générateur de source de liaison de configuration fournit une configuration AOT optimisée pour le trimming. Pour plus d’informations, consultez Générateur de source de liaison de configuration.

Ressources supplémentaires

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

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-02-11

Partager via

Configuration dans ASP.NET Core

Lire les valeurs de configuration

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

Sources de configuration d’application par défaut

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

Variables d’hôte

Sécurité et secrets d’utilisateur

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

Configuration d’accès dans le Program fichier

Configuration d’accès dans la Startup classe

Afficher les paramètres de configuration au démarrage pour le débogage

Clés et valeurs de configuration

Organisation des données de configuration hiérarchique

Fournisseurs de configuration

Configuration du fichier de paramètres d’application (appsettings.json, appsettings.{ENVIRONMENT}.json)

Fournisseur de configuration des variables d’environnement

Préfixe personnalisé pour les variables d’environnement

Les paramètres de lancement remplacent les paramètres de variable d’environnement

Échappement des variables d’environnement sur Linux

Paramètres d’application Azure App Service (variables d’environnement)

Préfixes des chaînes de connexion

Command-line

Arguments de ligne de commande

Mappages de commutateurs

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

Fournisseur de configuration de fichiers

Fournisseur de configuration INI

Fournisseur de configuration JSON

Fournisseur de configuration XML

Fournisseur de configuration par clé par fichier

Fournisseur de configuration de la mémoire

Configuration du point de terminaison Kestrel

Extraire une valeur unique de la configuration avec conversion de type (GetValue)

Utiliser des sections, obtenir les enfants d’une section et déterminer si une section existe

GetSection

GetChildren et Exists

Lier un tableau

Fournisseur de configuration personnalisé

Ajouter la configuration à partir d’un assembly externe

Générateur de source de liaison de configuration

Ressources supplémentaires

Commentaires

Ressources supplémentaires

Configuration d’accès dans le `Program` fichier

Configuration d’accès dans la `Startup` classe

Configuration du fichier de paramètres d’application (`appsettings.json`, `appsettings.{ENVIRONMENT}.json`)

Extraire une valeur unique de la configuration avec conversion de type (`GetValue`)

`GetSection`

`GetChildren` et `Exists`