Konfigurations-Generatoren für ASP.NET
Von Stephen Molloy und Rick Anderson
Konfigurations-Generatoren bieten einen modernen und agilen Mechanismus für ASP.NET Apps zum Abrufen von Konfigurationswerten aus externen Quellen.
Konfigurations-Generatoren:
- Sind in .NET Framework 4.7.1 und höher verfügbar.
- Stellen Sie einen flexiblen Mechanismus zum Lesen von Konfigurationswerten bereit.
- Berücksichtigen Sie einige der grundlegenden Anforderungen von Apps, während sie in eine container- und cloudorientierte Umgebung wechseln.
- Kann verwendet werden, um den Schutz von Konfigurationsdaten zu verbessern, indem sie aus Quellen zeichnen, die zuvor nicht verfügbar sind (z. B. Azure Key Vault- und Umgebungsvariablen) im .NET-Konfigurationssystem.
Ein häufiges Szenario, das von Konfigurations-Generatoren behandelt werden kann, besteht darin, einen grundlegenden Schlüssel-Wert-Ersetzungsmechanismus für Konfigurationsabschnitte bereitzustellen, die einem Schlüssel-/Wertmuster folgen. Das .NET Framework-Konzept von ConfigurationBuilders ist nicht auf bestimmte Konfigurationsabschnitte oder -muster beschränkt. Viele der Konfigurations-Generatoren in Microsoft.Configuration.ConfigurationBuilders
(github, NuGet) funktionieren jedoch innerhalb des Schlüssel-/Wertmusters.
Die folgenden Einstellungen gelten für alle Konfigurations-Generatoren für Schlüssel/Werte in Microsoft.Configuration.ConfigurationBuilders
.
Die Konfigurations-Generatoren verwenden eine externe Quelle von Schlüssel-/Wertinformationen, um ausgewählte Schlüssel-/Wertelemente des Konfigurationssystems aufzufüllen. Insbesondere erhalten die <appSettings/>
Abschnitte eine <connectionStrings/>
besondere Behandlung durch die Konfigurations-Generatoren. Die Generatoren arbeiten in drei Modi:
Strict
- Der Standardmodus. In diesem Modus wird der Konfigurations-Generator nur auf bekannten Schlüssel-/Wert-zentrierten Konfigurationsabschnitten ausgeführt.Strict
im Modus werden die einzelnen Schlüssel im Abschnitt aufgelistet. Wenn ein übereinstimmende Schlüssel in der externen Quelle gefunden wird:- Die Konfigurations-Generatoren ersetzen den Wert im resultierenden Konfigurationsabschnitt durch den Wert aus der externen Quelle.
Greedy
- Dieser Modus ist eng mit demStrict
Modus verbunden. Anstatt auf Schlüssel beschränkt zu sein, die bereits in der ursprünglichen Konfiguration vorhanden sind:- Die Konfigurations-Generatoren fügen alle Schlüssel-Wert-Paare aus der externen Quelle zum resultierenden Konfigurationsabschnitt hinzu.
Expand
– Betreibt den unformatierten XML-Code, bevor er in ein Konfigurationsabschnittsobjekt analysiert wird. Es kann als Erweiterung von Token in einer Zeichenfolge betrachtet werden. Jeder Teil der unformatierten XML-Zeichenfolge, die dem Muster${token}
entspricht, ist ein Kandidat für die Tokenerweiterung. Wenn in der externen Quelle kein entsprechender Wert gefunden wird, wird das Token nicht geändert. Generatoren in diesem Modus sind nicht auf die<appSettings/>
Abschnitte und<connectionStrings/>
Abschnitte beschränkt.
Das folgende Markup von "web.config " aktiviert den EnvironmentConfigBuilder im Strict
Modus:
<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>
Der folgende Code liest die <appSettings/>
und <connectionStrings/>
in der vorherigen Datei "web.config " angezeigte Datei:
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;
}
}
}
Der vorangehende Code legt die Eigenschaftswerte auf:
- Die Werte in der Datei "web.config ", wenn die Schlüssel nicht in Umgebungsvariablen festgelegt sind.
- Die Werte der Umgebungsvariable, falls festgelegt.
Enthält z. B ServiceID
. Folgendes:
- "ServiceID-Wert von web.config", wenn die Umgebungsvariable
ServiceID
nicht festgelegt ist. - Der Wert der
ServiceID
Umgebungsvariablen, falls festgelegt.
Die folgende Abbildung zeigt die <appSettings/>
Schlüssel/Werte aus der vorherigen Datei "web.config ", die im Umgebungs-Editor festgelegt wurde:
Hinweis: Möglicherweise müssen Sie Visual Studio beenden und neu starten, um Änderungen in Umgebungsvariablen anzuzeigen.
Schlüsselpräfixe können das Festlegen von Schlüsseln vereinfachen, da:
- Die .NET Framework-Konfiguration ist komplex und geschachtelt.
- Externe Schlüssel-/Wertquellen sind in der Regel einfach und flach. Umgebungsvariablen werden beispielsweise nicht geschachtelt.
Verwenden Sie einen der folgenden Ansätze, um sowohl die Konfiguration als auch <appSettings/>
<connectionStrings/>
die Konfiguration über Umgebungsvariablen einzufügen:
- Mit dem
EnvironmentConfigBuilder
StandardmodusStrict
und den entsprechenden Schlüsselnamen in der Konfigurationsdatei. Der vorangehende Code und das Markup verwenden diesen Ansatz. Mit diesem Ansatz können Sie nicht identisch benannte Schlüssel in beiden<appSettings/>
und<connectionStrings/>
. - Verwenden Sie zwei
EnvironmentConfigBuilder
s imGreedy
Modus mit unterschiedlichen Präfixen undstripPrefix
. Mit diesem Ansatz kann die App lesen<appSettings/>
und<connectionStrings/>
ohne die Konfigurationsdatei aktualisieren zu müssen. Im nächsten Abschnitt , stripPrefix, wird gezeigt, wie dies geschieht. - Verwenden Sie zwei
EnvironmentConfigBuilder
s imGreedy
Modus mit unterschiedlichen Präfixen. Bei diesem Ansatz können Keine doppelten Schlüsselnamen vorhanden sein, da Schlüsselnamen sich je nach Präfix unterscheiden müssen. Zum Beispiel:
<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>
Mit dem vorherigen Markup kann die gleiche Flache Schlüssel-/Wertquelle verwendet werden, um die Konfiguration für zwei verschiedene Abschnitte aufzufüllen.
Die folgende Abbildung zeigt die <appSettings/>
Werte und <connectionStrings/>
Schlüssel/Werte aus der vorherigen Datei "web.config ", die im Umgebungs-Editor festgelegt wurde:
Der folgende Code liest die <appSettings/>
in der vorherigen Datei "web.config" enthaltenen <connectionStrings/>
Schlüssel/Werte:
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;
}
}
Der vorangehende Code legt die Eigenschaftswerte auf:
- Die Werte in der Datei "web.config ", wenn die Schlüssel nicht in Umgebungsvariablen festgelegt sind.
- Die Werte der Umgebungsvariable, falls festgelegt.
Beispielsweise werden mit der vorherigen Datei "web.config ", den Schlüsseln/Werten im vorherigen Umgebungs-Editor-Bild und dem vorherigen Code die folgenden Werte festgelegt:
Schlüssel | Wert |
---|---|
AppSetting_ServiceID | AppSetting_ServiceID aus env-Variablen |
AppSetting_default | AppSetting_default Wert von "env" |
ConnStr_default | ConnStr_default val von env |
stripPrefix
: boolean, defaults to false
.
Das vorangehende XML-Markup trennt App-Einstellungen von Verbindungszeichenfolge s, erfordert jedoch alle Schlüssel in der Datei "web.config", um das angegebene Präfix zu verwenden. Beispielsweise muss das Präfix AppSetting
dem ServiceID
Schlüssel ("AppSetting_ServiceID") hinzugefügt werden. Mit stripPrefix
dem Präfix wird das Präfix nicht in der Datei "web.config " verwendet. Das Präfix ist in der Konfigurations-Generator-Quelle (z. B. in der Umgebung) erforderlich.) Wir gehen davon aus, dass die meisten Entwickler verwenden stripPrefix
werden.
Anwendungen entfernen in der Regel das Präfix. Mit dem folgenden Web.config wird das Präfix entfernt:
<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>
In der vorherigen Datei "web.config " befindet sich der default
Schlüssel sowohl in der <appSettings/>
als <connectionStrings/>
auch in der .
Die folgende Abbildung zeigt die <appSettings/>
Werte und <connectionStrings/>
Schlüssel/Werte aus der vorherigen Datei "web.config ", die im Umgebungs-Editor festgelegt wurde:
Der folgende Code liest die <appSettings/>
in der vorherigen Datei "web.config" enthaltenen <connectionStrings/>
Schlüssel/Werte:
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;
}
}
Der vorangehende Code legt die Eigenschaftswerte auf:
- Die Werte in der Datei "web.config ", wenn die Schlüssel nicht in Umgebungsvariablen festgelegt sind.
- Die Werte der Umgebungsvariable, falls festgelegt.
Beispielsweise werden mit der vorherigen Datei "web.config ", den Schlüsseln/Werten im vorherigen Umgebungs-Editor-Bild und dem vorherigen Code die folgenden Werte festgelegt:
Schlüssel | Wert |
---|---|
ServiceID | AppSetting_ServiceID aus env-Variablen |
default | AppSetting_default Wert von "env" |
default | ConnStr_default val von env |
tokenPattern
: Zeichenfolge, Standardmäßig auf @"\$\{(\w+)\}"
Das Expand
Verhalten der Generatoren durchsucht den unformatierten XML-Code nach Token, die wie ${token}
folgt aussehen. Die Suche erfolgt mit dem standardmäßigen regulären Ausdruck @"\$\{(\w+)\}"
. Der Satz von Zeichen, die übereinstimmen \w
, ist strenger als XML und viele Konfigurationsquellen zulassen. Verwenden Sie diese Eigenschaft tokenPattern
, wenn mehr Zeichen als @"\$\{(\w+)\}"
im Tokennamen erforderlich sind.
tokenPattern
:Schnur:
- Ermöglicht Entwicklern, den regex zu ändern, der für den Tokenabgleich verwendet wird.
- Es wird keine Überprüfung durchgeführt, um sicherzustellen, dass es sich um einen wohlgeformten, nicht gefährlichen Regex handelt.
- Sie muss eine Aufnahmegruppe enthalten. Der gesamte regex muss mit dem gesamten Token übereinstimmen. Die erste Erfassung muss der Tokenname sein, der in der Konfigurationsquelle nachschlagen soll.
<add name="Environment"
[mode|prefix|stripPrefix|tokenPattern]
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment" />
- Ist das einfachste der Konfigurations-Generatoren.
- Liest Werte aus der Umgebung.
- Verfügt nicht über zusätzliche Konfigurationsoptionen.
- Der
name
Attributwert ist beliebig.
Hinweis: In einer Windows-Containerumgebung werden variablen, die zur Laufzeit festgelegt werden, nur in die EntryPoint-Prozessumgebung eingefügt. Apps, die als Dienst oder ein Nicht-EntryPoint-Prozess ausgeführt werden, greifen diese Variablen nicht auf, es sei denn, sie werden anderweitig über einen Mechanismus im Container eingefügt. Bei IIS-ASP.NET-basierten/ Containern behandelt die aktuelle Version von ServiceMonitor.exe dies nur im DefaultAppPool. Andere Windows-basierte Containervarianten müssen möglicherweise einen eigenen Injektionsmechanismus für Nicht-EntryPoint-Prozesse entwickeln.
Warnung
Speichern Sie niemals Kennwörter, vertrauliche Verbindungszeichenfolge oder andere vertrauliche Daten im Quellcode. Produktionsgeheimnisse sollten nicht für die Entwicklung oder den Test verwendet werden.
<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" />
Im vorherigen XML-Code kann der userSecretsFile
Pfad verwendet ~/
oder verwendet werden ~\
. Der Pfad könnte z. B. als userSecretsFile="~/secrets.file
. Weitere Informationen finden Sie in der ConfigurationBuilders Utils-Klasse .
Dieser Konfigurations-Generator bietet ein Feature, das ASP.NET Core Secret Manager ähnelt.
Der UserSecretsConfigBuilder kann in .NET Framework-Projekten verwendet werden, aber eine geheime Datei muss angegeben werden. Alternativ können Sie die UserSecretsId
Eigenschaft in der Projektdatei definieren und die rohe geheime Datei am richtigen Speicherort zum Lesen erstellen. Um externe Abhängigkeiten aus Ihrem Projekt herauszuhalten, ist die geheime Datei XML-formatiert. Die XML-Formatierung ist ein Implementierungsdetails, und das Format sollte nicht verwendet werden. Wenn Sie eine secrets.json Datei für .NET Core-Projekte freigeben müssen, sollten Sie die Verwendung von SimpleJsonConfigBuilder in Betracht ziehen. Das SimpleJsonConfigBuilder
Format für .NET Core sollte auch als Implementierungsdetail betrachtet werden, das geändert werden kann.
Konfigurationsattribute für UserSecretsConfigBuilder
:
userSecretsId
– Dies ist die bevorzugte Methode zum Identifizieren einer GEHEIMEN XML-Datei. Es funktioniert ähnlich wie .NET Core, das eineUserSecretsId
Projekteigenschaft verwendet, um diesen Bezeichner zu speichern. Die Zeichenfolge muss eindeutig sein, sie muss keine GUID sein. Mit diesem Attribut suchenUserSecretsConfigBuilder
Sie an einem bekannten lokalen Speicherort (%APPDATA%\Microsoft\UserSecrets\<UserSecrets Id>\secrets.xml
) nach einer geheimen Datei, die zu diesem Bezeichner gehört.userSecretsFile
- Ein optionales Attribut, das die Datei angibt, die die geheimen Schlüssel enthält. Das~
Zeichen kann am Anfang verwendet werden, um auf den Anwendungsstamm zu verweisen. Entweder dieses Attribut oder dasuserSecretsId
Attribut ist erforderlich. Wenn beide angegeben sind,userSecretsFile
hat dies Vorrang.optional
: boolescher Standardwerttrue
– Verhindert eine Ausnahme, wenn die geheime Datei nicht gefunden werden kann.- Der
name
Attributwert ist beliebig.
Die geheime Datei weist das folgende Format auf:
<?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" />
Der AzureKeyVaultConfigBuilder liest werte, die im Azure Key Vault gespeichert sind.
vaultName
ist erforderlich (entweder der Name des Tresors oder ein URI für den Tresor). Die anderen Attribute ermöglichen die Kontrolle darüber, mit welchem Tresor eine Verbindung hergestellt werden soll, sind aber nur erforderlich, wenn die Anwendung nicht in einer Umgebung ausgeführt wird, die mit Microsoft.Azure.Services.AppAuthentication
. Die Azure Services-Authentifizierungsbibliothek wird verwendet, um nach Möglichkeit Verbindungsinformationen aus der Ausführungsumgebung automatisch aufzunehmen. Sie können verbindungsinformationen automatisch außer Kraft setzen, indem Sie eine Verbindungszeichenfolge bereitstellen.
vaultName
- Erforderlich, wennuri
nicht angegeben. Gibt den Namen des Tresors in Ihrem Azure-Abonnement an, aus dem Schlüssel-Wert-Paare gelesen werden sollen.uri
– Stellt eine Verbindung mit anderen Key Vault-Anbietern mit dem angegebenenuri
Wert bereit. Wenn nicht angegeben, ist Azure (vaultName
) der Tresoranbieter.version
– Azure Key Vault bietet ein Versionsverwaltungsfeature für geheime Schlüssel. Wennversion
angegeben, ruft der Generator nur geheime Schlüssel ab, die dieser Version entsprechen.preloadSecretNames
- Standardmäßig fragt dieser Generator alle Schlüsselnamen im Schlüsseltresor ab, wenn er initialisiert wird. Um das Lesen aller Schlüsselwerte zu verhindern, legen Sie dieses Attribut auffalse
. Wenn Sie dies festlegen, werdenfalse
geheime Schlüssel einzeln gelesen. Das gleichzeitige Lesen geheimer Schlüssel kann nützlich sein, wenn der Tresor den Zugriff auf "Abrufen", aber nicht den Zugriff auf "Liste" zulässt. Hinweis: Bei Verwendung desGreedy
ModuspreloadSecretNames
muss es sich um den Standardwert (Standard) seintrue
.
<add name="KeyPerFile"
[mode|prefix|stripPrefix|tokenPattern]
(directoryPath="PathToSourceDirectory")
[ignorePrefix="ignore."]
[keyDelimiter=":"]
[optional="false"]
type="Microsoft.Configuration.ConfigurationBuilders.KeyPerFileConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.KeyPerFile" />
KeyPerFileConfigBuilder ist ein einfacher Konfigurations-Generator, der die Dateien eines Verzeichnisses als Wertequelle verwendet. Der Name einer Datei ist der Schlüssel, und der Inhalt ist der Wert. Dieser Konfigurations-Generator kann nützlich sein, wenn er in einer koordinierten Containerumgebung ausgeführt wird. Systeme wie Docker-Schwarm und Kubernetes bieten secrets
ihren orchestrierten Windows-Containern auf diese Datei-Pro-Datei-Weise.
Attributdetails:
directoryPath
– Erforderlich. Gibt einen Pfad an, der nach Werten gesucht werden soll. Docker für Windows-Geheimschlüssel werden standardmäßig im Verzeichnis "C:\ProgramData\Docker\secrets " gespeichert.ignorePrefix
- Dateien, die mit diesem Präfix beginnen, werden ausgeschlossen. Der Standardwert ist „ignore“ (ignorieren).keyDelimiter
- Standardwert istnull
. Wenn angegeben, durchläuft der Konfigurations-Generator mehrere Ebenen des Verzeichnisses und erstellt Schlüsselnamen mit diesem Trennzeichen. Wenn dieser Wert lautetnull
, betrachtet der Konfigurations-Generator nur die oberste Ebene des Verzeichnisses.optional
- Standardwert istfalse
. Gibt an, ob der Konfigurations-Generator Fehler verursachen soll, wenn das Quellverzeichnis nicht vorhanden ist.
Warnung
Speichern Sie niemals Kennwörter, vertrauliche Verbindungszeichenfolge oder andere vertrauliche Daten im Quellcode. Produktionsgeheimnisse sollten nicht für die Entwicklung oder den Test verwendet werden.
<add name="SimpleJson"
[mode|prefix|stripPrefix|tokenPattern]
jsonFile="~\config.json"
[optional="true"]
[jsonMode="(Flat|Sectional)"]
type="Microsoft.Configuration.ConfigurationBuilders.SimpleJsonConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Json" />
.NET Core-Projekte verwenden häufig JSON-Dateien für die Konfiguration. Der Generator "SimpleJsonConfigBuilder " ermöglicht die Verwendung von .NET Core JSON-Dateien im .NET Framework. Dieser Konfigurations-Generator bietet eine grundlegende Zuordnung aus einer Flachschlüssel-/Wertquelle zu bestimmten Schlüssel-/Wertbereichen der .NET Framework-Konfiguration. Dieser Konfigurations-Generator bietet keine hierarchischen Konfigurationen. Die JSON-Sicherungsdatei ähnelt einem Wörterbuch, nicht einem komplexen hierarchischen Objekt. Eine hierarchische Datei mit mehreren Ebenen kann verwendet werden. Dieser Anbieter flatten
ist die Tiefe, indem der Eigenschaftsname auf jeder Ebene als :
Trennzeichen angefügt wird.
Attributdetails:
jsonFile
– Erforderlich. Gibt die JSON-Datei an, aus der gelesen werden soll. Das~
Zeichen kann am Anfang verwendet werden, um auf den App-Stamm zu verweisen.optional
- Boolescher Standardwert isttrue
. Verhindert das Auslösen von Ausnahmen, wenn die JSON-Datei nicht gefunden werden kann.jsonMode
-[Flat|Sectional]
.Flat
ist die Standardoption. IstjsonMode
dies der Grund, istFlat
die JSON-Datei eine einzelne Flache Schlüssel/Wertquelle. DieEnvironmentConfigBuilder
undAzureKeyVaultConfigBuilder
sind auch einzelne Flache Schlüssel/Wertquellen. Wenn dieSimpleJsonConfigBuilder
Konfiguration imSectional
Modus erfolgt:- Die JSON-Datei wird konzeptionell nur auf der obersten Ebene in mehrere Wörterbücher unterteilt.
- Jeder der Wörterbücher wird nur auf den Konfigurationsabschnitt angewendet, der dem zugeordneten Eigenschaftsnamen der obersten Ebene entspricht. Zum Beispiel:
{
"appSettings" : {
"setting1" : "value1",
"setting2" : "value2",
"complex" : {
"setting1" : "complex:value1",
"setting2" : "complex:value2",
}
}
}
Siehe ConfigurationBuilders Order of Execution im GitHub-Repository aspnet/MicrosoftConfigurationBuilders .
Wenn die Konfigurations-Generatoren Ihre Anforderungen nicht erfüllen, können Sie einen benutzerdefinierten Erstellen erstellen. Die KeyValueConfigBuilder
Basisklasse behandelt Ersetzungsmodi und die meisten Präfixbedenken. Ein Implementierungsprojekt benötigt nur:
- Erben Sie von der Basisklasse, und implementieren Sie eine grundlegende Quelle von Schlüssel-Wert-Paaren durch und
GetValue
GetAllValues
: - Fügen Sie dem Projekt die Microsoft.Configuration.ConfigurationBuilders.Base hinzu.
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" } };
}
}
Die KeyValueConfigBuilder
Basisklasse bietet einen Großteil der Arbeit und das konsistente Verhalten für Schlüssel-Wert-Konfigurations-Generatoren.