Configuration dans .NET

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

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 :

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.

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 :

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.

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.2" />
    <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 :

• Microsoft.Extensions.Configuration.Binder : fonctionnalité permettant de lier un objet à des données dans les fournisseurs de configuration pour Microsoft.Extensions.Configuration.
• Microsoft.Extensions.Configuration.Json : implémentation du fournisseur de configuration JSON pour Microsoft.Extensions.Configuration.
• Variables Microsoft.Extensions.Configuration.EnvironmentVariables : implémentation du fournisseur de configuration des variables d’environnement pour Microsoft.Extensions.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.Configuration.Binder" Version="8.0.2" />
    <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.

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.

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

Voir aussi

• Fournisseurs de configuration dans .NET
• Implémenter un fournisseur de configuration personnalisé
• Les bogues de configuration doivent être créés dans le référentiel github.com/dotnet/runtime
• Configuration dans ASP.NET Core