Entrainement
Module
Gérer les données de configuration d’application - Training
Gérer les données de configuration d’application
Ce navigateur n’est plus pris en charge.
Effectuez une mise à niveau vers Microsoft Edge pour tirer parti des dernières fonctionnalités, des mises à jour de sécurité et du support technique.
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 :
Notes
Pour plus d’informations sur la configuration du runtime .NET lui-même, consultez les Paramètres de configuration du runtime .NET.
É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 :
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 :
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.
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 :
Development
.Environment
.json à l’aide du fournisseur de configuration JSON. Par exemple, appsettings.Production.json et appsettings.Development.json.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.
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
.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 :
Notes
Le binder présente quelques limitations :
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 |
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.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
.Microsoft.Extensions.Configuration
.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 :
"appsettings.json"
à reconnaître par le fournisseur de configuration JSON."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!;
}
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 :
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.
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.
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.
Commentaires sur .NET
.NET est un projet open source. Sélectionnez un lien pour fournir des commentaires :
Entrainement
Module
Gérer les données de configuration d’application - Training
Gérer les données de configuration d’application
Documentation
Fournisseurs de configuration - .NET
Découvrez comment configurer des applications .NET avec l’API du fournisseur de configuration et les fournisseurs de configuration disponibles.
Implémenter un fournisseur de configuration personnalisé - .NET
Découvrez comment implémenter un fournisseur de configuration personnalisé dans les applications .NET. Explorez un fournisseur de configuration de base de données qui utilise Entity Framework Core.
Découvrez le modèle d’options pour représenter des groupes de paramètres associés dans les applications .NET. Le modèle d’options utilise des classes pour fournir un accès fortement typé aux paramètres.