Événements
31 mars, 23 h - 2 avr., 23 h
L’événement de la communauté Microsoft Fabric, Power BI, SQL et AI ultime. 31 mars au 2 avril 2025.
Inscrivez-vous aujourd’huiCe 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.
Par Stephen Molloy et Rick Anderson
Les générateurs de configuration fournissent un mécanisme moderne et agile pour ASP.NET applications afin d’obtenir des valeurs de configuration à partir de sources externes.
Générateurs de configuration :
Un scénario courant qui peut être géré par les générateurs de configuration consiste à fournir un mécanisme de remplacement de clé/valeur de base pour les sections de configuration qui suivent un modèle clé/valeur. Le concept .NET Framework de ConfigurationBuilders n’est pas limité aux sections ou modèles de configuration spécifiques. Toutefois, un grand nombre des générateurs de configuration dans Microsoft.Configuration.ConfigurationBuilders
(github, NuGet) fonctionnent dans le modèle clé/valeur.
Les paramètres suivants s’appliquent à tous les générateurs de configuration clé/valeur dans Microsoft.Configuration.ConfigurationBuilders
.
Les générateurs de configuration utilisent une source externe d’informations de clé/valeur pour remplir les éléments clé/valeur sélectionnés du système de configuration. Plus précisément, les <appSettings/>
sections <connectionStrings/>
reçoivent un traitement spécial des constructeurs de configuration. Les constructeurs fonctionnent en trois modes :
Strict
- Mode par défaut. Dans ce mode, le générateur de configuration fonctionne uniquement sur les sections de configuration centrées sur les clés/valeurs connues. Strict
le mode énumère chaque clé de la section. Si une clé correspondante est trouvée dans la source externe :
Greedy
- Ce mode est étroitement lié au Strict
mode. Au lieu d’être limité aux clés qui existent déjà dans la configuration d’origine :
Expand
- Fonctionne sur le xml brut avant d’être analysé dans un objet de section de configuration. Il peut être considéré comme une expansion des jetons dans une chaîne. Toute partie de la chaîne XML brute qui correspond au modèle ${token}
est un candidat à l’expansion des jetons. Si aucune valeur correspondante n’est trouvée dans la source externe, le jeton n’est pas modifié. Les générateurs dans ce mode ne sont pas limités aux sections et <connectionStrings/>
aux <appSettings/>
sections.
Le balisage suivant à partir de web.config active EnvironmentConfigBuilder en Strict
mode :
<configuration>
<configSections>
<section name="configBuilders"
type="System.Configuration.ConfigurationBuildersSection,
System.Configuration, Version=4.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a"
restartOnExternalChanges="false" requirePermission="false" />
</configSections>
<configBuilders>
<builders>
<add name="MyEnvironment"
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment,
Version=1.0.0.0, Culture=neutral" />
</builders>
</configBuilders>
<appSettings configBuilders="MyEnvironment">
<add key="ServiceID" value="ServiceID value from web.config" />
<add key="ServiceKey" value="ServiceKey value from web.config" />
</appSettings>
<connectionStrings configBuilders="MyEnvironment">
<add name="default" connectionString="Data Source=web.config/mydb.db" />
</connectionStrings>
Le code suivant lit le <appSettings/>
fichier web.config précédent et <connectionStrings/>
le montre :
using System;
using System.Configuration;
using System.Web.UI;
namespace MyConfigBuilders
{
public partial class About : Page
{
public string ServiceID { get; set; }
public string ServiceKey { get; set; }
public string ConString { get; set; }
protected void Page_Load(object sender, EventArgs e)
{
ServiceID = ConfigurationManager.AppSettings["ServiceID"];
ServiceKey = ConfigurationManager.AppSettings["ServiceKey"];
ConString = ConfigurationManager.ConnectionStrings["default"]
?.ConnectionString;
}
}
}
Le code précédent définit les valeurs de propriété sur :
Par exemple, ServiceID
contient les éléments suivants :
ServiceID
d’environnement n’est pas définie.ServiceID
, si elle est définie.L’image suivante montre les <appSettings/>
clés/valeurs du jeu de fichiers web.config précédent dans l’éditeur d’environnement :
Remarque : Vous devrez peut-être quitter et redémarrer Visual Studio pour voir les modifications apportées aux variables d’environnement.
Les préfixes de clé peuvent simplifier la définition des clés, car :
Utilisez l’une des approches suivantes pour injecter à la fois <appSettings/>
et <connectionStrings/>
dans la configuration via des variables d’environnement :
EnvironmentConfigBuilder
mode par défaut Strict
et les noms de clés appropriés dans le fichier de configuration. Le code et le balisage précédents prennent cette approche. À l’aide de cette approche, vous ne pouvez pas avoir de clés nommées identiquement dans les deux <appSettings/>
et <connectionStrings/>
.EnvironmentConfigBuilder
s en Greedy
mode avec des préfixes distincts et stripPrefix
. Avec cette approche, l’application peut lire <appSettings/>
et <connectionStrings/>
sans avoir à mettre à jour le fichier de configuration. La section suivante, stripPrefix, montre comment procéder.EnvironmentConfigBuilder
s en Greedy
mode avec des préfixes distincts. Avec cette approche, vous ne pouvez pas avoir de noms de clés en double, car les noms de clés doivent différer par préfixe. Par exemple :<configuration>
<configSections>
<section name="configBuilders"
type="System.Configuration.ConfigurationBuildersSection,
System.Configuration, Version=4.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a"
restartOnExternalChanges="false" requirePermission="false" />
</configSections>
<configBuilders>
<builders>
<add name="AS_Environment" mode="Greedy" prefix="AppSetting_"
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment" />
<add name="CS_Environment" mode="Greedy" prefix="ConnStr_"
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment" />
</builders>
</configBuilders>
<appSettings configBuilders="AS_Environment">
<add key="AppSetting_ServiceID" value="ServiceID value from web.config" />
<add key="AppSetting_default" value="AppSetting_default value from web.config" />
</appSettings>
<connectionStrings configBuilders="CS_Environment">
<add name="ConnStr_default" connectionString="Data Source=web.config/mydb.db" />
</connectionStrings>
Avec le balisage précédent, la même source de clé/valeur plate peut être utilisée pour remplir la configuration de deux sections différentes.
L’image suivante montre les <connectionStrings/>
<appSettings/>
clés/valeurs du jeu de fichiers web.config précédent dans l’éditeur d’environnement :
Le code suivant lit les <appSettings/>
<connectionStrings/>
clés/valeurs contenues dans le fichier web.config précédent :
public partial class Contact : Page
{
public string ServiceID { get; set; }
public string AppSetting_default { get; set; }
public string ConString { get; set; }
protected void Page_Load(object sender, EventArgs e)
{
ServiceID = ConfigurationManager.AppSettings["AppSetting_ServiceID"];
AppSetting_default = ConfigurationManager.AppSettings["AppSetting_default"];
ConString = ConfigurationManager.ConnectionStrings["ConnStr_default"]
?.ConnectionString;
}
}
Le code précédent définit les valeurs de propriété sur :
Par exemple, à l’aide du fichier web.config précédent, des clés/valeurs dans l’image de l’éditeur d’environnement précédent et du code précédent, les valeurs suivantes sont définies :
Clé | Valeur |
---|---|
AppSetting_ServiceID | AppSetting_ServiceID à partir de variables env |
AppSetting_default | AppSetting_default valeur d’env |
ConnStr_default | ConnStr_default val d’env |
stripPrefix
: booléen, valeur false
par défaut .
Le balisage XML précédent sépare les paramètres d’application des chaîne de connexion, mais nécessite que toutes les clés du fichier web.config utilisent le préfixe spécifié. Par exemple, le préfixe AppSetting
doit être ajouté à la ServiceID
clé (« AppSetting_ServiceID »). Avec stripPrefix
, le préfixe n’est pas utilisé dans le fichier web.config . Le préfixe est requis dans la source du générateur de configuration (par exemple, dans l’environnement.) Nous prévoyons que la plupart des développeurs utiliseront stripPrefix
.
Les applications suppriment généralement le préfixe. Le fichier web.config suivant supprime le préfixe :
<configuration>
<configSections>
<section name="configBuilders"
type="System.Configuration.ConfigurationBuildersSection,
System.Configuration, Version=4.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a"
restartOnExternalChanges="false" requirePermission="false" />
</configSections>
<configBuilders>
<builders>
<add name="AS_Environment" mode="Greedy" prefix="AppSetting_"
stripPrefix="true"
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment,
Version=1.0.0.0, Culture=neutral" />
<add name="CS_Environment" mode="Greedy" prefix="ConnStr_"
stripPrefix="true"
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment,
Version=1.0.0.0, Culture=neutral" />
</builders>
</configBuilders>
<appSettings configBuilders="AS_Environment">
<add key="ServiceID" value="ServiceID value from web.config" />
<add key="default" value="AppSetting_default value from web.config" />
</appSettings>
<connectionStrings configBuilders="CS_Environment">
<add name="default" connectionString="Data Source=web.config/mydb.db" />
</connectionStrings>
Dans le fichier web.config précédent, la default
clé se trouve à la fois dans le <appSettings/>
fichier web.config et <connectionStrings/>
.
L’image suivante montre les <connectionStrings/>
<appSettings/>
clés/valeurs du jeu de fichiers web.config précédent dans l’éditeur d’environnement :
Le code suivant lit les <appSettings/>
<connectionStrings/>
clés/valeurs contenues dans le fichier web.config précédent :
public partial class About2 : Page
{
public string ServiceID { get; set; }
public string AppSetting_default { get; set; }
public string ConString { get; set; }
protected void Page_Load(object sender, EventArgs e)
{
ServiceID = ConfigurationManager.AppSettings["ServiceID"];
AppSetting_default = ConfigurationManager.AppSettings["default"];
ConString = ConfigurationManager.ConnectionStrings["default"]
?.ConnectionString;
}
}
Le code précédent définit les valeurs de propriété sur :
Par exemple, à l’aide du fichier web.config précédent, des clés/valeurs dans l’image de l’éditeur d’environnement précédent et du code précédent, les valeurs suivantes sont définies :
Clé | Valeur |
---|---|
ServiceID | AppSetting_ServiceID à partir de variables env |
default | AppSetting_default valeur d’env |
default | ConnStr_default val d’env |
tokenPattern
: Chaîne, valeur par défaut @"\$\{(\w+)\}"
Le Expand
comportement des générateurs recherche le code XML brut pour les jetons qui ressemblent ${token}
. La recherche est effectuée avec l’expression @"\$\{(\w+)\}"
régulière par défaut. L’ensemble de caractères qui correspond \w
est plus strict que XML et de nombreuses sources de configuration autorisent. Utilisez tokenPattern
quand plusieurs caractères sont @"\$\{(\w+)\}"
requis dans le nom du jeton.
tokenPattern
:Corde:
<add name="Environment"
[mode|prefix|stripPrefix|tokenPattern]
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment" />
name
est arbitraire.Remarque : Dans un environnement de conteneur Windows, les variables définies au moment de l’exécution sont injectées uniquement dans l’environnement de processus EntryPoint. Les applications qui s’exécutent en tant que service ou un processus non-EntryPoint ne récupèrent pas ces variables, sauf s’ils sont injectés par le biais d’un mécanisme dans le conteneur. Pour les conteneurs basés sur IIS/ASP.NET, la version actuelle de ServiceMonitor.exe gère cela uniquement dans DefaultAppPool. D’autres variantes de conteneur Windows peuvent avoir besoin de développer leur propre mécanisme d’injection pour les processus non-EntryPoint.
Avertissement
Ne stockez jamais les mots de passe, les chaîne de connexion sensibles ou d’autres données sensibles dans le code source. Les secrets de production ne doivent pas être utilisés pour le développement ou le test.
<add name="UserSecrets"
[mode|prefix|stripPrefix|tokenPattern]
(userSecretsId="{secret string, typically a GUID}" | userSecretsFile="~\secrets.file")
[optional="true"]
type="Microsoft.Configuration.ConfigurationBuilders.UserSecretsConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.UserSecrets" />
Dans le code XML précédent, le userSecretsFile
chemin d’accès peut utiliser ~/
ou ~\
. Par exemple, le chemin d’accès peut être écrit en tant que userSecretsFile="~/secrets.file
. Pour plus d’informations, consultez la classe ConfigurationBuilders Utils .
Ce générateur de configuration fournit une fonctionnalité similaire à ASP.NET Core Secret Manager.
UserSecretsConfigBuilder peut être utilisé dans les projets .NET Framework, mais un fichier de secrets doit être spécifié. Vous pouvez également définir la UserSecretsId
propriété dans le fichier projet et créer le fichier de secrets bruts à l’emplacement approprié pour la lecture. Pour empêcher les dépendances externes de votre projet, le fichier secret est au format XML. La mise en forme XML est un détail d’implémentation et le format ne doit pas être utilisé. Si vous devez partager un fichier secrets.json avec des projets .NET Core, envisagez d’utiliser SimpleJsonConfigBuilder. Le SimpleJsonConfigBuilder
format de .NET Core doit également être considéré comme un détail d’implémentation susceptible de changer.
Attributs de configuration pour UserSecretsConfigBuilder
:
userSecretsId
- Il s’agit de la méthode recommandée pour identifier un fichier de secrets XML. Elle fonctionne comme .NET Core, qui utilise une UserSecretsId
propriété de projet pour stocker cet identificateur. La chaîne doit être unique, elle n’a pas besoin d’être un GUID. Avec cet attribut, l’apparence UserSecretsConfigBuilder
dans un emplacement local connu (%APPDATA%\Microsoft\UserSecrets\<UserSecrets Id>\secrets.xml
) pour un fichier de secrets appartenant à cet identificateur.userSecretsFile
- Attribut facultatif spécifiant le fichier contenant les secrets. Le ~
caractère peut être utilisé au début pour référencer la racine de l’application. Cet attribut ou l’attribut userSecretsId
est requis. Si les deux sont spécifiés, userSecretsFile
il est prioritaire.optional
: valeur booléenne, valeur true
par défaut : empêche une exception si le fichier de secrets est introuvable.name
est arbitraire.Le fichier secrets a le format suivant :
<?xml version="1.0" encoding="utf-8" ?>
<root>
<secrets ver="1.0">
<secret name="secret key name" value="secret value" />
</secrets>
</root>
<add name="AzureKeyVault"
[mode|prefix|stripPrefix|tokenPattern]
(vaultName="MyVaultName" |
uri="https:/MyVaultName.vault.azure.net")
[version="secrets version"]
[preloadSecretNames="true"]
type="Microsoft.Configuration.ConfigurationBuilders.AzureKeyVaultConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Azure" />
AzureKeyVaultConfigBuilder lit les valeurs stockées dans Azure Key Vault.
vaultName
est requis (soit le nom du coffre, soit un URI vers le coffre). Les autres attributs autorisent le contrôle sur le coffre auquel se connecter, mais ne sont nécessaires que si l’application n’est pas en cours d’exécution dans un environnement qui fonctionne avec Microsoft.Azure.Services.AppAuthentication
. La bibliothèque d’authentification des services Azure est utilisée pour récupérer automatiquement les informations de connexion à partir de l’environnement d’exécution si possible. Vous pouvez remplacer automatiquement les informations de connexion en fournissant une chaîne de connexion.
vaultName
- Obligatoire s’il uri
n’est pas fourni. Spécifie le nom du coffre dans votre abonnement Azure à partir duquel lire des paires clé/valeur.uri
- Se connecte à d’autres fournisseurs Key Vault avec la valeur spécifiée uri
. S’il n’est pas spécifié, Azure (vaultName
) est le fournisseur de coffres.version
- Azure Key Vault fournit une fonctionnalité de contrôle de version pour les secrets. S’il version
est spécifié, le générateur récupère uniquement les secrets correspondant à cette version.preloadSecretNames
- Par défaut, ce générateur interroge tous les noms de clés dans le coffre de clés lorsqu’il est initialisé. Pour empêcher la lecture de toutes les valeurs de clé, définissez cet attribut sur false
. La définition de ce paramètre permet de false
lire les secrets un par un. La lecture des secrets un par un peut être utile si le coffre autorise l’accès « Obtenir » mais pas l’accès « Lister ». Remarque : Lors de l’utilisation Greedy
du mode, preloadSecretNames
doit être true
(la valeur par défaut.)<add name="KeyPerFile"
[mode|prefix|stripPrefix|tokenPattern]
(directoryPath="PathToSourceDirectory")
[ignorePrefix="ignore."]
[keyDelimiter=":"]
[optional="false"]
type="Microsoft.Configuration.ConfigurationBuilders.KeyPerFileConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.KeyPerFile" />
KeyPerFileConfigBuilder est un générateur de configuration de base qui utilise les fichiers d’un répertoire comme source de valeurs. Le nom d’un fichier est la clé et le contenu est la valeur. Ce générateur de configuration peut être utile lors de l’exécution dans un environnement de conteneur orchestré. Les systèmes tels que Docker Swarm et Kubernetes fournissent secrets
à leurs conteneurs Windows orchestrés de cette manière de clé par fichier.
Détails de l’attribut :
directoryPath
- Obligatoire. Spécifie un chemin d’accès à rechercher des valeurs. Les secrets Docker pour Windows sont stockés dans le répertoire C :\ProgramData\Docker\secrets par défaut.ignorePrefix
- Les fichiers qui commencent par ce préfixe sont exclus. La valeur par défaut est « ignore ».keyDelimiter
- La valeur par défaut est null
. S’il est spécifié, le générateur de configuration traverse plusieurs niveaux du répertoire, ce qui crée des noms de clés avec ce délimiteur. Si cette valeur est null
, le générateur de configuration examine uniquement le niveau supérieur du répertoire.optional
- La valeur par défaut est false
. Spécifie si le générateur de configuration doit provoquer des erreurs si le répertoire source n’existe pas.Avertissement
Ne stockez jamais les mots de passe, les chaîne de connexion sensibles ou d’autres données sensibles dans le code source. Les secrets de production ne doivent pas être utilisés pour le développement ou le test.
<add name="SimpleJson"
[mode|prefix|stripPrefix|tokenPattern]
jsonFile="~\config.json"
[optional="true"]
[jsonMode="(Flat|Sectional)"]
type="Microsoft.Configuration.ConfigurationBuilders.SimpleJsonConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Json" />
Les projets .NET Core utilisent fréquemment des fichiers JSON pour la configuration. Le générateur SimpleJsonConfigBuilder permet aux fichiers JSON .NET Core d’être utilisés dans le .NET Framework. Ce générateur de configuration fournit un mappage de base à partir d’une source clé/valeur plate en zones clé/valeur spécifiques de la configuration .NET Framework. Ce générateur de configuration ne fournit pas de configurations hiérarchiques. Le fichier de stockage JSON est similaire à un dictionnaire, et non à un objet hiérarchique complexe. Un fichier hiérarchique à plusieurs niveaux peut être utilisé. Ce fournisseur flatten
est la profondeur en ajoutant le nom de propriété à chaque niveau à l’aide :
d’un délimiteur.
Détails de l’attribut :
jsonFile
- Obligatoire. Spécifie le fichier JSON à lire. Le ~
caractère peut être utilisé au début pour référencer la racine de l’application.
optional
- Boolean, la valeur par défaut est true
. Empêche la levée d’exceptions si le fichier JSON est introuvable.
jsonMode
- [Flat|Sectional]
. Flat
est la valeur par défaut. Quand jsonMode
c’est Flat
le cas, le fichier JSON est une source de clé/valeur plate unique. AzureKeyVaultConfigBuilder
Il EnvironmentConfigBuilder
s’agit également de sources de clé/valeur plate unique. Quand le SimpleJsonConfigBuilder
mode est configuré Sectional
:
{
"appSettings" : {
"setting1" : "value1",
"setting2" : "value2",
"complex" : {
"setting1" : "complex:value1",
"setting2" : "complex:value2",
}
}
}
Consultez l’ordre d’exécution de ConfigurationBuilders dans le dépôt GitHub aspnet/MicrosoftConfigurationBuilders .
Si les générateurs de configuration ne répondent pas à vos besoins, vous pouvez en écrire un personnalisé. La KeyValueConfigBuilder
classe de base gère les modes de substitution et la plupart des problèmes de préfixe. Un projet d’implémentation n’a besoin que des éléments suivants :
GetValue
éléments suivants GetAllValues
:using Microsoft.Configuration.ConfigurationBuilders;
using System.Collections.Generic;
public class MyCustomConfigBuilder : KeyValueConfigBuilder
{
public override string GetValue(string key)
{
// Key lookup should be case-insensitive, because most key/value collections in
// .NET Framework config sections are case-insensitive.
return "Value for given key, or null.";
}
public override ICollection<KeyValuePair<string, string>> GetAllValues(string prefix)
{
// Populate the return collection.
return new Dictionary<string, string>() { { "one", "1" }, { "two", "2" } };
}
}
La KeyValueConfigBuilder
classe de base fournit une grande partie du travail et du comportement cohérent entre les générateurs de configuration clé/valeur.
Événements
31 mars, 23 h - 2 avr., 23 h
L’événement de la communauté Microsoft Fabric, Power BI, SQL et AI ultime. 31 mars au 2 avril 2025.
Inscrivez-vous aujourd’hui