Partager via

Configuration dans .NET

La configuration dans .NET 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 différentes sources de configuration :

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

Remarque

Pour plus d’informations sur la configuration du runtime .NET lui-même, consultez les paramètres de configuration du runtime .NET.

Concepts et abstractions

Étant donné une ou plusieurs sources de configuration, le IConfiguration type fournit une vue unifiée des données de configuration. La configuration est en lecture seule et le modèle de configuration n’est pas conçu pour être accessible en écriture par programmation. L’interface IConfiguration est une représentation unique de toutes les sources de configuration, comme illustré dans le diagramme suivant :

L’interface « IConfiguration » est une représentation unique de toutes les sources de configuration.

Configurer des applications console

Les applications console .NET créées à l’aide du nouveau modèle de commande dotnet ou de Visual Studio par défaut n’exposent pas les fonctionnalités de configuration. Pour ajouter une configuration dans une nouvelle application console .NET, ajoutez une référence de package à 📦 Microsoft.Extensions.Configuration. Ce package est la base de la configuration dans les applications .NET. Elle fournit les types ConfigurationBuilder et connexes.

using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string?>()
    {
        ["SomeKey"] = "SomeValue"
    })
    .Build();

Console.WriteLine(configuration["SomeKey"]);

// Outputs:
//   SomeValue

Code précédent :

  • Crée une nouvelle instance ConfigurationBuilder.
  • Ajoute une collection en mémoire de paires clé-valeur au générateur de configuration.
  • Appelle la Build() méthode pour créer une IConfiguration instance.
  • Écrit la valeur de la SomeKey clé dans la console.

Bien que cet exemple utilise une configuration en mémoire, il existe de nombreux fournisseurs de configuration disponibles, offrant des fonctionnalités pour les configurations basées sur des fichiers, les variables d’environnement, les arguments de ligne de commande et d’autres sources de configuration. Pour plus d’informations, consultez Fournisseurs de configuration dans .NET.

Autre approche d’hébergement

Habituellement, vos applications font plus que de simplement lire la configuration. Ils utiliseront probablement l’injection de dépendances, la journalisation, et d’autres services. L’approche hôte générique .NET est recommandée pour les applications qui utilisent ces services. Au lieu de cela, envisagez d’ajouter une référence de package à 📦 Microsoft.Extensions.Hosting. Modifiez le fichier Program.cs pour qu’il corresponde au code suivant :

using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Application code should start here.

await host.RunAsync();

La Host.CreateApplicationBuilder(String[]) méthode fournit une configuration par défaut pour 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 à l’aide du fournisseur de configuration des variables d’environnement.
  3. Secrets d’application lorsque l’application s’exécute dans l’environnement Development .
  4. appsettings.Environment.json à l’aide du fournisseur de configuration JSON. Par exemple, appsettings. Production. json et appsettings. Développement. json.
  5. appsettings.json à l’aide du fournisseur de configuration JSON.
  6. ChainedConfigurationProvider : ajoute un IConfiguration existant en tant que source.

L’ajout d’un fournisseur de configuration remplace les valeurs de configuration précédentes. Par exemple, le fournisseur de configuration de ligne de commande remplace toutes les valeurs d’autres fournisseurs, car il est ajouté en dernier. Si SomeKey est défini à la fois dans appsettings.json et dans l’environnement, la valeur de l’environnement est utilisée parce qu’elle a été ajoutée après appsettings.json.

Liaison

L’un des principaux avantages de l’utilisation des abstractions de configuration .NET est la possibilité de lier des valeurs de configuration à des instances d’objets .NET. Par exemple, le fournisseur de configuration JSON peut être utilisé pour mapper des fichiersappsettings.json aux objets .NET et est utilisé avec l’injection de dépendances. Cela permet au modèle d’options, qui utilise des classes pour fournir un accès fortement typé aux groupes de paramètres associés. Le binder par défaut est basé sur la réflexion, mais il existe un autre générateur de source facile à activer.

La configuration .NET fournit différentes abstractions. Tenez compte des interfaces suivantes :

  • IConfiguration: représente un ensemble de propriétés de configuration d’application clé/valeur.
  • IConfigurationRoot: représente la racine d’une IConfiguration hiérarchie.
  • IConfigurationSection: représente une section des valeurs de configuration d’application.

Ces abstractions sont indépendantes de leur fournisseur de configuration sous-jacent (IConfigurationProvider). En d’autres termes, vous pouvez utiliser une IConfiguration instance pour accéder à n’importe quelle valeur de configuration à partir de plusieurs fournisseurs.

Le binder peut utiliser différentes approches pour traiter les valeurs de configuration :

  • Désérialisation directe (à l’aide de convertisseurs intégrés) pour les types primitifs.
  • Le TypeConverter pour le type complexe lorsque le type en a un.
  • Réflexion d’un type complexe qui a des propriétés.

Remarque

Le classeur présente quelques limitations :

  • Les propriétés sont ignorées si elles ont des setters privés ou si leur type ne peut pas être converti.
  • Les propriétés sans clés de configuration correspondantes sont ignorées.

Liaison de hiérarchies

Les valeurs de configuration peuvent contenir des données hiérarchiques. Les objets hiérarchiques sont représentés avec l’utilisation du : délimiteur dans les clés de configuration. Pour accéder à une valeur de configuration, utilisez le : caractère pour délimiter une hiérarchie. Par exemple, tenez compte des valeurs de configuration suivantes :

{
  "Parent": {
    "FavoriteNumber": 7,
    "Child": {
      "Name": "Example",
      "GrandChild": {
        "Age": 3
      }
    }
  }
}

Le tableau suivant représente des exemples de clés et leurs valeurs correspondantes pour l’exemple JSON précédent :

Clé Valeur
"Parent:FavoriteNumber" 7
"Parent:Child:Name" "Example"
"Parent:Child:GrandChild:Age" 3

Scénarios de liaison avancés

Le classeur de configuration présente des comportements et des limitations spécifiques lors de l’utilisation de certains types. Cette section inclut les sous-sections suivantes :

Liaison à des dictionnaires

Lorsque vous liez la configuration à un Dictionary<TKey,TValue> emplacement où la valeur est un type de collection mutable (comme des tableaux ou des listes), les liaisons répétées à la même clé étendent les valeurs de collection au lieu de les remplacer.

L’exemple suivant illustre ce comportement :

IConfiguration config = new ConfigurationBuilder()
    .AddInMemoryCollection()
    .Build();

config["Queue:0"] = "Value1";
var dict = new Dictionary<string, string[]>() { { "Queue", new[] { "InitialValue" } } };

Console.WriteLine("=== Dictionary Binding with Collection Values ===");
Console.WriteLine($"Initially: {string.Join(", ", dict["Queue"])}");

// In .NET 7+, binding extends the collection instead of replacing it.
config.Bind(dict);
Console.WriteLine($"After Bind: {string.Join(", ", dict["Queue"])}");

config["Queue:1"] = "Value2";
config.Bind(dict);
Console.WriteLine($"After 2nd Bind: {string.Join(", ", dict["Queue"])}");

Pour plus d’informations, consultez La configuration de liaison au dictionnaire étend les valeurs.

Clés de dictionnaire avec deux-points

Le caractère deux-points (:) est réservé en tant que délimiteur de hiérarchie dans les clés de configuration. Cela signifie que vous ne pouvez pas utiliser les deux-points dans les clés de dictionnaire pour lier la configuration. Si vos clés contiennent des points-virgules (tels que des URL ou d’autres identificateurs mis en forme), le système de configuration les interprète comme des chemins de hiérarchie plutôt que des caractères littéraux. Tenez compte des solutions de contournement suivantes :

  • Utilisez d’autres caractères délimiteurs (tels que des traits __de soulignement doubles) dans vos clés de configuration et transformez-les par programmation si nécessaire.
  • Désérialisez manuellement la configuration en tant que JSON brut à l’aide de System.Text.Json ou d'une bibliothèque similaire, qui prend en charge les deux-points dans les clés.
  • Créez une couche de mappage personnalisée qui traduit des clés sécurisées en clés souhaitées avec des points-virgules.

Lier aux types IReadOnly*

Le classeur de configuration ne prend pas en charge la liaison directement vers IReadOnlyList<T>, IReadOnlyDictionary<TKey, TValue>ou d’autres interfaces de collection en lecture seule. Ces interfaces n’ont pas les mécanismes dont le classeur a besoin pour remplir les collections.

Pour utiliser des collections en lecture seule, utilisez des types mutables pour les propriétés que le classeur remplit, puis exposez-les en tant qu'interfaces en lecture seule pour les consommateurs :

Console.WriteLine("=== IReadOnly* Types (NOT Directly Supported) ===");

var readonlyConfig = new ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string?>
    {
        ["Settings:Values:0"] = "Item1",
        ["Settings:Values:1"] = "Item2",
        ["Settings:Values:2"] = "Item3",
    })
    .Build();

// This class uses List<string> for binding, exposes as IReadOnlyList<string>.
var settings = new SettingsWithReadOnly();
readonlyConfig.GetSection("Settings").Bind(settings);

Console.WriteLine("Values bound to mutable List, exposed as IReadOnlyList:");
foreach (var value in settings.ValuesReadOnly)
{
    Console.WriteLine($"  {value}");
}

Implémentation de la classe de configuration :

class SettingsWithReadOnly
{
    // Use mutable type for binding
    public List<string> Values { get; set; } = [];

    // Expose as read-only for consumers
    public IReadOnlyList<string> ValuesReadOnly => Values;
}

Cette approche permet au classeur de remplir le mutable List<string> tout en présentant une interface immuable aux consommateurs via IReadOnlyList<string>.

Liaison avec des constructeurs paramétrables

À compter de .NET 7, le classeur de configuration prend en charge la liaison aux types avec un seul constructeur paramétrable public. Cela permet aux types et enregistrements immuables d’être renseignés directement à partir de la configuration :

Console.WriteLine("=== Parameterized Constructor Binding ===");

var ctorConfig = new ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string?>
    {
        ["AppSettings:Name"] = "MyApp",
        ["AppSettings:MaxConnections"] = "100",
        ["AppSettings:Timeout"] = "30"
    })
    .Build();

// Binding to a type with a single parameterized constructor
var appSettings = ctorConfig.GetSection("AppSettings").Get<AppSettings>();
if (appSettings != null)
{
    Console.WriteLine($"Name: {appSettings.Name}");
    Console.WriteLine($"MaxConnections: {appSettings.MaxConnections}");
    Console.WriteLine($"Timeout: {appSettings.Timeout}");
}

Classe de paramètres immuables :

// Immutable type with single parameterized constructor.
class AppSettings
{
    public string Name { get; }
    public int MaxConnections { get; }
    public int Timeout { get; }

    public AppSettings(string name, int maxConnections, int timeout)
    {
        Name = name;
        MaxConnections = maxConnections;
        Timeout = timeout;
    }
}

Important

Le binder prend uniquement en charge les types avec un seul constructeur à paramètres publics. Si un type a plusieurs constructeurs paramétrables publics, le classeur ne peut pas déterminer celui à utiliser et la liaison échoue. Utilisez un constructeur paramétrable unique ou un constructeur sans paramètre avec des setters de propriétés.

Exemple de base

Pour accéder aux valeurs de configuration sous leur forme de base, sans l’aide de l’approche hôte générique , utilisez directement le ConfigurationBuilder type.

Conseil / Astuce

Le System.Configuration.ConfigurationBuilder type est différent du Microsoft.Extensions.Configuration.ConfigurationBuilder type. Tout ce contenu est spécifique aux Microsoft.Extensions.* paquets et espaces de noms NuGet.

Considérez le projet C# suivant :

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="appsettings.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.3" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.3" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.3" />
  </ItemGroup>

</Project>

Le fichier projet précédent fait référence à plusieurs packages NuGet de configuration :

Prenons un exemple de fichierappsettings.json :

{
    "Settings": {
        "KeyOne": 1,
        "KeyTwo": true,
        "KeyThree": {
            "Message": "Oh, that's nice...",
            "SupportedVersions": {
                "v1": "1.0.0",
                "v3": "3.0.7"
            }
        },
        "IPAddressRange": [
            "46.36.198.121",
            "46.36.198.122",
            "46.36.198.123",
            "46.36.198.124",
            "46.36.198.125"
        ]
    }
}

Maintenant, étant donné ce fichier JSON, voici un exemple de modèle de consommation à l’aide du générateur de configuration directement :

using Microsoft.Extensions.Configuration;

// Build a config object, using env vars and JSON providers.
IConfigurationRoot config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddEnvironmentVariables()
    .Build();

// Get values from the config given their key and their target type.
Settings? settings = config.GetRequiredSection("Settings").Get<Settings>();

// Write the values to the console.
Console.WriteLine($"KeyOne = {settings?.KeyOne}");
Console.WriteLine($"KeyTwo = {settings?.KeyTwo}");
Console.WriteLine($"KeyThree:Message = {settings?.KeyThree?.Message}");

// Application code which might rely on the config could start here.

// This will output the following:
//   KeyOne = 1
//   KeyTwo = True
//   KeyThree:Message = Oh, that's nice...

Le code C# précédent :

  • Instancie un ConfigurationBuilder.
  • Ajoute le "appsettings.json" fichier à reconnaître par le fournisseur de configuration JSON.
  • Ajoute des variables d’environnement comme étant reconnues par le fournisseur de configuration des variables d’environnement.
  • Obtient la section requise "Settings" et l’instance correspondante Settings à l’aide de l’instance config .

L’objet Settings est mis en forme comme suit :

public sealed class Settings
{
    public required int KeyOne { get; set; }
    public required bool KeyTwo { get; set; }
    public required NestedSettings KeyThree { get; set; } = null!;
}

public sealed class NestedSettings
{
    public required string Message { get; set; } = null!;
}

Exemple de base avec l’hébergement

Pour accéder à la IConfiguration valeur, vous pouvez vous appuyer à nouveau sur le Microsoft.Extensions.Hosting package NuGet. Créez une application console et collez le contenu du fichier projet suivant :

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="appsettings.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.3" />
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="10.0.3" />
  </ItemGroup>

</Project>

Le fichier projet précédent définit ce qui suit :

  • L’application est un exécutable.
  • Un fichier appsettings.json doit être copié dans le répertoire de sortie lorsque le projet est compilé.
  • La référence du Microsoft.Extensions.Hosting package NuGet est ajoutée.

Ajoutez le fichier appsettings.json à la racine du projet avec le contenu suivant :

{
    "KeyOne": 1,
    "KeyTwo": true,
    "KeyThree": {
        "Message": "Thanks for checking this out!"
    }
}

Remplacez le contenu du fichier Program.cs par le code C# suivant :

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

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Ask the service provider for the configuration abstraction.
IConfiguration config = host.Services.GetRequiredService<IConfiguration>();

// Get values from the config given their key and their target type.
int keyOneValue = config.GetValue<int>("KeyOne");
bool keyTwoValue = config.GetValue<bool>("KeyTwo");
string? keyThreeNestedValue = config.GetValue<string>("KeyThree:Message");

// Write the values to the console.
Console.WriteLine($"KeyOne = {keyOneValue}");
Console.WriteLine($"KeyTwo = {keyTwoValue}");
Console.WriteLine($"KeyThree:Message = {keyThreeNestedValue}");

// Application code which might rely on the config could start here.

await host.RunAsync();

// This will output the following:
//   KeyOne = 1
//   KeyTwo = True
//   KeyThree:Message = Thanks for checking this out!

Lorsque vous exécutez cette application, le Host.CreateApplicationBuilder définit le comportement pour découvrir la configuration JSON et l'exposer via l'instance IConfiguration. À partir de l’instance host, vous pouvez demander au fournisseur de services l’instance IConfiguration, puis obtenir des valeurs à partir de celle-ci.

Conseil / Astuce

L’utilisation de l’instance brute IConfiguration de cette façon, bien que pratique, ne s’adapte pas très bien. Lorsque les applications augmentent en complexité et que leurs configurations correspondantes deviennent plus complexes, nous vous recommandons d’utiliser le modèle d’options comme alternative.

Exemple de base avec l’hébergement et l’utilisation de l’API d’indexeur

Considérez le même contenu de fichierappsettings.json de l’exemple précédent :

{
    "SupportedVersions": {
        "v1": "1.0.0",
        "v3": "3.0.7"
    },
    "IPAddressRange": [
        "46.36.198.123",
        "46.36.198.124",
        "46.36.198.125"
    ]
}

Remplacez le contenu du fichier Program.cs par le code C# suivant :

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

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Ask the service provider for the configuration abstraction.
IConfiguration config = host.Services.GetRequiredService<IConfiguration>();

// Get values from the config given their key and their target type.
string? ipOne = config["IPAddressRange:0"];
string? ipTwo = config["IPAddressRange:1"];
string? ipThree = config["IPAddressRange:2"];
string? versionOne = config["SupportedVersions:v1"];
string? versionThree = config["SupportedVersions:v3"];

// Write the values to the console.
Console.WriteLine($"IPAddressRange:0 = {ipOne}");
Console.WriteLine($"IPAddressRange:1 = {ipTwo}");
Console.WriteLine($"IPAddressRange:2 = {ipThree}");
Console.WriteLine($"SupportedVersions:v1 = {versionOne}");
Console.WriteLine($"SupportedVersions:v3 = {versionThree}");

// Application code which might rely on the config could start here.

await host.RunAsync();

// This will output the following:
//     IPAddressRange:0 = 46.36.198.123
//     IPAddressRange:1 = 46.36.198.124
//     IPAddressRange:2 = 46.36.198.125
//     SupportedVersions:v1 = 1.0.0
//     SupportedVersions:v3 = 3.0.7

Les valeurs sont accessibles à l’aide de l’API d’indexeur où chaque clé est une chaîne et la valeur est une chaîne. La configuration prend en charge les propriétés, les objets, les tableaux et les dictionnaires.

Fournisseurs de configuration

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

Fournisseur de configuration Fournit la configuration à partir de
Configuration d'application Azure Configuration d'Applications Azure
Azure Key Vault Azure Key Vault
Ligne de commande Paramètres de ligne de commande
Personnalisée Source personnalisée
variables d’environnement Variables d'environnement
File Fichiers JSON, XML et INI
Clé par fichier Fichiers de répertoire
Mémoire Collections en mémoire
Secrets d’application (gestionnaire de secrets) Fichier dans le répertoire du profil utilisateur

Conseil / Astuce

L’ordre dans lequel les fournisseurs de configuration sont ajoutés importe. Lorsque plusieurs fournisseurs de configuration sont utilisés et que plusieurs fournisseurs spécifient la même clé, le dernier ajouté est utilisé.

Pour plus d’informations sur différents fournisseurs de configuration, consultez Fournisseurs de configuration dans .NET.

Voir aussi

  • Last updated on