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, exposant des fonctionnalités pour les 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.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. Développement. 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

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>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="9.0.7" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="9.0.7" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="9.0.7" />
  </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>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="9.0.7" />
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.7" />
  </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 Fournit la configuration à partir de
Fournisseur de configuration d’Application Azure Configuration d'Applications Azure
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 des variables d’environnement Variables d'environnement
Fournisseur de configuration de fichiers Fichiers JSON, XML et INI
Fournisseur de configuration de clé par fichier Fichiers de répertoire
Fournisseur de configuration de la 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