Configuration dans .NET

  • Article

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

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

Notes

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 type IConfiguration fournit un affichage unifié 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 le biais de la programmation. L’interface IConfiguration est une représentation unique de toutes les sources de configuration, comme illustré dans le diagramme suivant :

The `IConfiguration` interface is a single representation of all the configuration sources.

Configurer des applications console

Les applications console .NET créées à l’aide du modèle de commande dotnet new ou de Visual Studio par défaut n’exposent pas les fonctionnalités de configuration. Pour ajouter la 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. Il fournit le ConfigurationBuilder et les types associés.

using Microsoft.Extensions.Configuration;

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

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

// Outputs:
//   SomeValue

Le code précédent :

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

Bien que cet exemple utilise une configuration en mémoire, il existe de nombreux fournisseurs de configuration disponibles, exposant des fonctionnalités pour les variables 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

En règle générale, vos applications effectuent plus que la configuration de lecture. Elles utiliseront probablement l’injection de dépendances, la journalisation et d’autres services. L’approche par 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 méthode Host.CreateApplicationBuilder(String[]) fournit la configuration de l’application par défaut dans l’ordre suivant, de la priorité la plus élevée à la plus basse :

  1. Arguments de ligne de commande avec le fournisseur de configuration de ligne de commande.
  2. Variables d’environnement avec le fournisseur de configuration des variables d’environnement.
  3. Secrets de l’application quand l’application s’exécute dans l’environnement Development.
  4. appsettings.json à l’aide du fournisseur de configuration JSON.
  5. appsettings.Environment.json à l’aide du fournisseur de configuration JSON. Par exemple, appsettings.Production.json et appsettings.Development.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 dans appsettings.json et dans l’environnement, la valeur de l’environnement est utilisée, car 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 les valeurs de configuration à des instances d’objets .NET. Par exemple, le fournisseur de configuration JSON permet de mapper les fichiers appsettings.json avec des objets .NET et il est utilisé avec l’injection de dépendances. Cela permet au modèle d’options qui utilise des classes de fournir un accès fortement typé aux groupes de paramètres associés. La configuration .NET fournit différentes abstractions. Observons les interfaces suivantes :

  • IConfiguration : représente un ensemble de propriétés de configuration d’application de clé/valeur.
  • IConfigurationRoot : représente la racine d’une hiérarchie IConfiguration.
  • 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 instance IConfiguration pour accéder à n’importe quelle valeur de configuration 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 possédant des propriétés.

Notes

Le binder 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, considérons les 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

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 le type ConfigurationBuilder directement.

Conseil

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

Considérez le projet C# suivant :

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.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="8.0.1" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="8.0.0" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="8.0.0" />
  </ItemGroup>

</Project>

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

Prenons un exemple de fichier appsettings.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 utilisant directement le constructeur de configuration :

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 fichier "appsettings.json" à reconnaître par le fournisseur de configuration JSON.
  • Ajoute des variables d’environnement reconnues par le fournisseur de configuration des variables d’environnement.
  • Obtient la section "Settings" requise et l’instance Settings correspondante à 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 valeur IConfiguration, vous pouvez vous appuyer à nouveau sur le package NuGet Microsoft.Extensions.Hosting. Créez une application console et collez le contenu du fichier projet suivant :

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

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

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

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
  </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 package NuGet Microsoft.Extensions.Hosting 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 pour l’instance IConfiguration, puis lui demander des valeurs.

Conseil

L’utilisation de l’instance IConfiguration brute de cette façon, bien que pratique, n’est pas très bien mise à l’échelle. Lorsque les applications deviennent plus complexes et que leurs configurations correspondantes le deviennent également, 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 de l’indexeur

Considérez le même contenu du fichier appsettings.json que celui 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 Fournit la configuration à partir de
Fournisseur de configuration Azure App Azure App Configuration
Fournisseur de configuration Azure Key Vault Azure Key Vault
Fournisseur de configuration de ligne de commande Paramètres de ligne de commande
Fournisseur de configuration personnalisé Source personnalisée
Fournisseur de configuration de variables d’environnement Variables d'environnement
Fournisseur de configuration de fichier Fichiers JSON, XML et INI
Fournisseur de configuration clé par fichier Fichiers de répertoire
Fournisseur de configuration de mémoire Collections en mémoire
Secrets d’application (Gestionnaire de secrets) Fichier dans le répertoire de profil utilisateur

Conseil

L’ordre dans lequel les fournisseurs de configuration sont ajoutés est important. Lorsque plusieurs fournisseurs de configuration sont utilisés et que plusieurs fournisseurs de configuration fournis 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