Fournisseurs de configuration dans .NET

La configuration dans .NET est possible avec les fournisseurs de configuration. Plusieurs types de fournisseurs dépendent de diverses sources de configuration. Cet article détaille tous les différents fournisseurs de configuration et leurs sources correspondantes.

• Fournisseur de configuration de fichier
• Fournisseur de configuration de variable d’environnement
• Fournisseur de configuration de ligne de commande
• Fournisseur de configuration clé par fichier
• Fournisseur de configuration de mémoire

Fournisseur de configuration de fichier

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

• Fournisseur de configuration JSON
• Fournisseur de configuration XML
• Fournisseur de configuration INI

Les clés ne respectent pas la casse. Tous les fournisseurs de configuration de fichiers lèvent le FormatException lorsque les clés en double sont trouvées dans un seul fournisseur.

Fournisseur de configuration JSON

La classe JsonConfigurationProvider charge la configuration à partir d’un fichier JSON. Installez le package NuGet Microsoft.Extensions.Configuration.Json.

Les surcharges permettent de spécifier :

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

Prenez le code suivant :

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using ConsoleJson.Example;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.Sources.Clear();

IHostEnvironment env = builder.Environment;

builder.Configuration
    .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
    .AddJsonFile($"appsettings.{env.EnvironmentName}.json", true, true);

TransientFaultHandlingOptions options = new();
builder.Configuration.GetSection(nameof(TransientFaultHandlingOptions))
    .Bind(options);

Console.WriteLine($"TransientFaultHandlingOptions.Enabled={options.Enabled}");
Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={options.AutoRetryDelay}");

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Le code précédent :

• Efface tous les fournisseurs de configuration existants qui ont été ajoutés par défaut dans la méthode CreateApplicationBuilder(String[]).
• Configure le fournisseur de configuration JSON pour charger les appsettings.json et appsettings.Environment.json avec les options suivantes :
  • optional: true : le fichier est facultatif.
  • reloadOnChange: true : le fichier est rechargé quand des modifications sont enregistrées.

Voici un exemple de fichier appsettings.json avec différents paramètres de configuration :

{
    "SecretKey": "Secret key value",
    "TransientFaultHandlingOptions": {
        "Enabled": true,
        "AutoRetryDelay": "00:00:07"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    }
}

À partir de l’instance IConfigurationBuilder, une fois que des fournisseurs de configuration ont été ajoutés, vous pouvez appeler IConfigurationBuilder.Build() pour obtenir l’objet IConfigurationRoot. La racine de configuration représente la racine d’une hiérarchie de configuration. Les sections de la configuration peuvent être liées à des instances d’objets .NET, et fournies ultérieurement comme IOptions<TOptions> par le biais de l’injection de dépendances.

Considérez la classe TransientFaultHandlingOptions définie comme suit :

namespace ConsoleJson.Example;

public sealed class TransientFaultHandlingOptions
{
    public bool Enabled { get; set; }
    public TimeSpan AutoRetryDelay { get; set; }
}

Le code suivant génère la racine de configuration, lie une section au type de classe TransientFaultHandlingOptions et imprime les valeurs liées dans la fenêtre de console :

TransientFaultHandlingOptions options = new();
builder.Configuration.GetSection(nameof(TransientFaultHandlingOptions))
    .Bind(options);

Console.WriteLine($"TransientFaultHandlingOptions.Enabled={options.Enabled}");
Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={options.AutoRetryDelay}");

L’application écrit l’exemple de sortie suivant :

// Sample output:
//    TransientFaultHandlingOptions.Enabled=True
//    TransientFaultHandlingOptions.AutoRetryDelay=00:00:07

Fournisseur de configuration XML

La classe XmlConfigurationProvider charge la configuration à partir d’un fichier XML au moment de l’exécution. Installez le package NuGet Microsoft.Extensions.Configuration.Xml.

Le code suivant illustre la configuration de fichiers XML à l’aide du fournisseur de configuration XML.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.Sources.Clear();

builder.Configuration
    .AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true)
    .AddXmlFile("repeating-example.xml", optional: true, reloadOnChange: true);

builder.Configuration.AddEnvironmentVariables();

if (args is { Length: > 0 })
{
    builder.Configuration.AddCommandLine(args);
}

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Le code précédent :

• Efface tous les fournisseurs de configuration existants qui ont été ajoutés par défaut dans la méthode CreateApplicationBuilder(String[]).
• Configure le fournisseur de configuration XML pour charger les fichiers appsettings.xml et repeating-example.xml avec les options suivantes :
  • optional: true : le fichier est facultatif.
  • reloadOnChange: true : le fichier est rechargé quand des modifications sont enregistrées.
• Configure le fournisseur de configuration des variables d’environnement.
• Configure le fournisseur de configuration de ligne de commande si args contiennent des arguments.

Les paramètres XML sont écrasés par les paramètres dans le fournisseur de configuration de variables d’environnement et le fournisseur de configuration de ligne de commande.

Voici un exemple de fichier appsettings.xml avec différents paramètres de configuration :

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <SecretKey>Secret key value</SecretKey>
  <TransientFaultHandlingOptions>
    <Enabled>true</Enabled>
    <AutoRetryDelay>00:00:07</AutoRetryDelay>
  </TransientFaultHandlingOptions>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

Dans .NET 5 et les versions antérieures, ajoutez l’attribut name pour distinguer les éléments répétitifs qui utilisent le même nom d’élément. Dans .NET 6 et versions ultérieures, le fournisseur de configuration XML indexe automatiquement les éléments répétitifs. Cela signifie que vous n’avez pas besoin de spécifier l’attribut name, sauf si vous souhaitez l’index « 0 » dans la clé et qu’il n’y a qu’un seul élément. (Si vous effectuez une mise à niveau vers .NET 6 ou version ultérieure, vous pouvez rencontrer une interruption résultant de ce changement de comportement. Pour plus d’informations, consultez Les éléments XML répétés incluent un index.)

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

IConfigurationRoot configurationRoot = builder.Configuration;

string key00 = "section:section0:key:key0";
string key01 = "section:section0:key:key1";
string key10 = "section:section1:key:key0";
string key11 = "section:section1:key:key1";

string? val00 = configurationRoot[key00];
string? val01 = configurationRoot[key01];
string? val10 = configurationRoot[key10];
string? val11 = configurationRoot[key11];

Console.WriteLine($"{key00} = {val00}");
Console.WriteLine($"{key01} = {val01}");
Console.WriteLine($"{key10} = {val10}");
Console.WriteLine($"{key10} = {val11}");

L’application écrit l’exemple de sortie suivant :

// Sample output:
//    section:section0:key:key0 = value 00
//    section:section0:key:key1 = value 01
//    section:section1:key:key0 = value 10
//    section:section1:key:key0 = value 11

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 INI

La classe IniConfigurationProvider charge la configuration à partir d’un fichier INI au moment de l’exécution. Installez le package NuGet Microsoft.Extensions.Configuration.Ini.

Le code suivant efface tous les fournisseurs de configuration et ajoute le IniConfigurationProvider avec deux fichiers INI comme source :

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
builder.Configuration.Sources.Clear();

IHostEnvironment env = builder.Environment;

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

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Voici un exemple de fichier appsettings.ini avec différents paramètres de configuration :

SecretKey="Secret key value"

[TransientFaultHandlingOptions]
Enabled=True
AutoRetryDelay="00:00:07"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Le code suivant affiche les paramètres de configuration précédents en les écrivant dans la fenêtre de console :

foreach ((string key, string? value) in
    builder.Configuration.AsEnumerable().Where(t => t.Value is not null))
{
    Console.WriteLine($"{key}={value}");
}

L’application écrit l’exemple de sortie suivant :

// Sample output:
//    TransientFaultHandlingOptions:Enabled=True
//    TransientFaultHandlingOptions:AutoRetryDelay=00:00:07
//    SecretKey=Secret key value
//    Logging:LogLevel:Microsoft=Warning
//    Logging:LogLevel:Default=Information

Fournisseur de configuration de variable d’environnement

À l’aide de la configuration par défaut, le EnvironmentVariablesConfigurationProvider charge la configuration à partir des paires clé-valeur après avoir lu appsettings.json, appsettings.Environment.json, et gestionnaire de secrets. Par conséquent, les valeurs clés lues à partir de l’environnement remplacent les valeurs lues à partir de appsettings.json, appsettings.Environment.json et du gestionnaire de secrets.

Le délimiteur : ne fonctionne pas avec les clés hiérarchiques des variables d’environnement sur toutes les plateformes. Par exemple, le délimiteur : n’est pas pris en charge par Bash. Le double trait de soulignement (__), pris en charge sur toutes les plateformes, remplace automatiquement tous les délimiteurs : dans les variables d’environnement.

Considérons la classe TransientFaultHandlingOptions :

public class TransientFaultHandlingOptions
{
    public bool Enabled { get; set; }
    public TimeSpan AutoRetryDelay { get; set; }
}

Les commandes suivantes set définissent les clés d’environnement et les valeurs de SecretKey et TransientFaultHandlingOptions.

set SecretKey="Secret key from environment"
set TransientFaultHandlingOptions__Enabled="true"
set TransientFaultHandlingOptions__AutoRetryDelay="00:00:13"

Ces paramètres d’environnement sont définis uniquement dans les processus lancés à partir de la fenêtre de commande dans laquelle ils ont été définis. Ils ne sont pas lus par les applications web lancées avec Visual Studio.

Avec Visual Studio 2019 et versions ultérieures, vous pouvez spécifier des variables d’environnement à l’aide de la boîte de dialogue Profils de lancement.

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

setx SecretKey "Secret key from setx environment" /M
setx TransientFaultHandlingOptions__Enabled "true" /M
setx TransientFaultHandlingOptions__AutoRetryDelay "00:00:05" /M

Pour tester que les commandes précédentes remplacent les paramètres 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.

Préfixes

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

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

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

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Dans le code précédent :

• config.AddEnvironmentVariables(prefix: "CustomPrefix_") est ajouté après les fournisseurs de configuration par défaut. Pour obtenir un exemple de classement des fournisseurs de configuration, consultez Fournisseur de configuration XML.
• Les variables d’environnement définies avec le préfixe CustomPrefix_ remplacent les fournisseurs de configuration par défaut. Il s’agit notamment des variables d’environnement sans le préfixe.

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

La configuration par défaut charge les variables d’environnement et les arguments de ligne de commande précédés du préfixe DOTNET_. Le préfixe DOTNET_ est utilisé par .NET pour la configuration de l’hôte et de l’application, mais pas pour la configuration de l’utilisateur.

Pour plus d’informations sur la configuration de l’hôte et de l’application, consultez Hôte générique .NET.

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 sont chargées dans l’application avec la configuration par défaut ou si aucun préfixe n’est fourni à AddEnvironmentVariables.

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

Variables d’environnement définies dans le fichier launchSettings.json

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

Paramètres d’Azure App Service

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

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

Fournisseur de configuration de ligne de commande

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

• Fichiers appsettings.json et appsettings.Environment.json.
• Secrets d’application (Gestionnaire de secrets) 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 avec tous les autres fournisseurs de configuration.

Avec Visual Studio 2019 et versions ultérieures, vous pouvez spécifier des arguments de ligne de commande à l’aide de la boîte de dialogue Profils de lancement.

Arguments de ligne de commande

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

dotnet run SecretKey="Secret key from command line"

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

dotnet run /SecretKey "Secret key set from forward slash"

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

dotnet run --SecretKey "Secret key set from double hyphen"

Valeur de clé :

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

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

Fournisseur de configuration clé par fichier

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

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

Les surcharges permettent de spécifier :

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

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

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

.ConfigureAppConfiguration((_, configuration) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");

    configuration.AddKeyPerFile(directoryPath: path, optional: true);
})

Fournisseur de configuration de mémoire

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

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

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.AddInMemoryCollection(
    new Dictionary<string, string?>
    {
        ["SecretKey"] = "Dictionary MyKey Value",
        ["TransientFaultHandlingOptions:Enabled"] = bool.TrueString,
        ["TransientFaultHandlingOptions:AutoRetryDelay"] = "00:00:07",
        ["Logging:LogLevel:Default"] = "Warning"
    });

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Dans le code précédent, MemoryConfigurationBuilderExtensions.AddInMemoryCollection(IConfigurationBuilder, IEnumerable<KeyValuePair<String,String>>) ajoute le fournisseur de mémoire après les fournisseurs de configuration par défaut. Pour obtenir un exemple de classement des fournisseurs de configuration, consultez Fournisseur de configuration XML.

Voir aussi

• Configuration dans .NET
• Hôte générique .NET
• Implémenter un fournisseur de configuration personnalisé