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 auf zuvor nicht verfügbare Quellen (z. B. Azure Key Vault und Umgebungsvariablen) im .NET-Konfigurationssystem zurückgegriffen wird.

Schlüssel-/Wertkonfigurations-Generatoren

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.

Einstellungen für Schlüssel-/Wertkonfigurations-Generatoren

Die folgenden Einstellungen gelten für alle Konfigurations-Generatoren für Schlüssel/Werte in Microsoft.Configuration.ConfigurationBuilders.

Modus

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/> und <connectionStrings/> Abschnitte eine besondere Behandlung durch die Konfigurationsersteller. Die Erbauer 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 Modus enumeriert jeden Schlüssel im Abschnitt. 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 dem Strict 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 – Verarbeitet das rohe XML, bevor es in ein Konfigurationsabschnitt-Objekt geparst 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. Ersteller in diesem Modus sind nicht auf die Abschnitte <appSettings/> und <connectionStrings/> 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 im vorangehenden web.config-Datei angezeigten <appSettings/> und <connectionStrings/> aus.

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.

Zum Beispiel enthält 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:

Screenshot des Editors

Hinweis: Möglicherweise müssen Sie Visual Studio beenden und neu starten, um Änderungen in Umgebungsvariablen anzuzeigen.

Präfixbehandlung

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 eine der folgenden Methoden, um sowohl <appSettings/> als auch <connectionStrings/> in die Konfiguration über Umgebungsvariablen einzufügen.

Mit dem EnvironmentConfigBuilder im Standardmodus Strict und den geeigneten 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/> als auch <connectionStrings/> verwenden.
Verwenden Sie zwei EnvironmentConfigBuilders im Greedy-Modus mit unterschiedlichen Präfixen und stripPrefix. Mit diesem Ansatz kann die App <appSettings/> und <connectionStrings/> lesen, ohne die Konfigurationsdatei aktualisieren zu müssen. Im nächsten Abschnitt , stripPrefix, wird gezeigt, wie dies geschieht.
Verwenden Sie zwei EnvironmentConfigBuilders im Greedy 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 dieselbe flache Schlüssel-/Wertpaar-Quelle verwendet werden, um die Konfiguration für zwei verschiedene Abschnitte festzulegen.

Die folgende Abbildung zeigt die <appSettings/> und <connectionStrings/> Schlüssel/Werte aus der vorhergehenden web.config-Datei, die im Umgebungs-Editor festgelegt wurde.

Screenshot des Editors für Umgebungsvariablen mit hervorgehobenen variablen AppSetting_default, AppSetting_ServiceID und ConnStr_default.

Der folgende Code liest die <appSettings/> und <connectionStrings/> Schlüssel/Werte, die in der zuvor enthaltenen web.config-Datei enthalten sind:

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_Standardwert von Umgebung

stripPrefix

stripPrefix: boolean, standardmäßig false.

Das vorangehende XML-Markup trennt App-Einstellungen von Verbindungszeichenfolgen, erfordert jedoch, dass alle Schlüssel in der web.config-Datei das angegebene Präfix verwenden. Beispielsweise muss das Präfix AppSetting dem ServiceID Schlüssel ("AppSetting_ServiceID") hinzugefügt werden. Ohne stripPrefixPräfix wird das Präfix in der Datei web.config nicht 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 stripPrefixwerden.

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 auch in der <connectionStrings/>.

Die folgende Abbildung zeigt die <appSettings/> Schlüssel/Werte und <connectionStrings/> Schlüssel/Werte aus der vorherigen Datei "web.config", die im Umgebungs-Editor festgelegt wurde:

Screenshot des Editors für Umgebungsvariablen mit hervorgehobenen variablen AppSetting_default, AppSetting_ServiceID und ConnStr_default.

Der folgende Code liest die Schlüssel/Werte der in der vorherigen web.config enthaltenen <appSettings/> und <connectionStrings/> aus.

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
Standardwert	AppSetting_default Wert aus "env"
Standardwert	ConnStr_default-Wert aus der env-Variable

tokenPattern

tokenPattern: Zeichenfolge, Standardmäßig auf @"\$\{(\w+)\}"

Das Expand Verhalten der Ersteller durchsucht den unformatierten XML-Code nach Token, die wie ${token} aussehen. Die Suche erfolgt mit dem standardmäßigen regulären Ausdruck @"\$\{(\w+)\}". Der Zeichensatz, der \w entspricht, ist strenger als das, was XML und viele Konfigurationsquellen erlauben. Verwenden Sie diese Eigenschaft tokenPattern , wenn mehr Zeichen als @"\$\{(\w+)\}" im Tokennamen erforderlich sind.

tokenPattern: String:

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.
Muss eine Erfassungsgruppe enthalten. Der gesamte regex muss mit dem gesamten Token übereinstimmen. Die erste Erfassung muss der Token-Name sein, der in der Konfigurationsquelle nachgeschlagen werden soll.

Konfigurations-Generatoren in Microsoft.Configuration.ConfigurationBuilders

UmgebungsKonfigurationsErsteller

<add name="Environment"
    [mode|prefix|stripPrefix|tokenPattern] 
    type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
    Microsoft.Configuration.ConfigurationBuilders.Environment" />

Der EnvironmentConfigBuilder:

Ist das einfachste der Konfigurations-Generatoren.
Liest Werte aus den Umgebungsvariablen.
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.

UserSecretsConfigBuilder

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 vorhergehenden XML-Code kann der userSecretsFile-Pfad entweder ~/ 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 eine UserSecretsId Projekteigenschaft verwendet, um diesen Bezeichner zu speichern. Die Zeichenfolge muss eindeutig sein, sie muss keine GUID sein. Mit diesem Attribut suchen UserSecretsConfigBuilder 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 das userSecretsId Attribut ist erforderlich. Wenn beide angegeben sind, hat userSecretsFile Vorrang.
optional: boolescher Standardwert true – 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>

AzureKeyVaultConfigBuilder

<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, welcher Tresor verbunden wird, sind aber nur erforderlich, wenn die Anwendung nicht in einer Umgebung ausgeführt wird, die mit Microsoft.Azure.Services.AppAuthentication arbeitet. Die Azure Services-Authentifizierungsbibliothek wird verwendet, um nach Möglichkeit Verbindungsinformationen aus der Ausführungsumgebung automatisch aufzunehmen. Sie können das automatische Erfassen von Verbindungsinformationen außer Kraft setzen, indem Sie eine Verbindungszeichenfolge bereitstellen.

vaultName - Erforderlich, wenn uri 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 angegebenen uri Wert bereit. Wenn nicht angegeben, ist Azure (vaultName) der Tresoranbieter.
version – Azure Key Vault bietet ein Versionsverwaltungsfeature für geheime Schlüssel. Wenn version angegeben, ruft der Generator nur geheime Schlüssel ab, die dieser Version entsprechen.
preloadSecretNames - Standardmäßig fragt dieser Builder alle Schlüsselnamen im Schlüsseltresor ab, wenn er initialisiert wird. Um das Lesen aller Schlüsselwerte zu verhindern, legen Sie dieses Attribut auf false. Wenn Sie dies festlegen, werden false geheime Daten einzeln ausgelesen. Das Lesen geheimer Schlüssel nacheinander kann nützlich sein, wenn der Tresor den Zugriff auf "Abrufen", aber nicht den Zugriff auf "Auflisten" zulässt. Hinweis: Bei Verwendung des Greedy-Modus muss preloadSecretNames der Standardwert true (Standard) sein.

KeyPerFileConfigBuilder

<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 Swarm und Kubernetes bieten secrets ihren orchestrierten Windows-Containern auf diese Key-per-File-Weise.

Attributdetails:

directoryPath – Erforderlich. Gibt einen Pfad an, in dem nach Werten gesucht wird. 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 ist null. Wenn angegeben, durchläuft der Konfigurations-Generator mehrere Ebenen des Verzeichnisses und erstellt Schlüsselnamen mit diesem Trennzeichen. Wenn dieser Wert lautet null, betrachtet der Konfigurations-Generator nur die oberste Ebene des Verzeichnisses.
optional - Standardwert ist false. Gibt an, ob der Konfigurations-Generator Fehler verursachen soll, wenn das Quellverzeichnis nicht vorhanden ist.

SimpleJsonConfigBuilder

Warnung

<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 erweitert die Tiefe, indem er den Eigenschaftsnamen auf jeder Ebene mit : als Trennzeichen anhängt.

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 ist true. Verhindert das Auslösen von Ausnahmen, wenn die JSON-Datei nicht gefunden werden kann.
jsonMode - [Flat|Sectional]. Flat ist die Standardoption. Wenn jsonMode ist, ist Flat die JSON-Datei eine einzelne flache Schlüssel-Wert-Quelle. Die EnvironmentConfigBuilder und AzureKeyVaultConfigBuilder sind auch einzelne flache Schlüssel/Wertquellen. Wenn die SimpleJsonConfigBuilder Konfiguration im Sectional 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",
            }
        }
    }

Reihenfolge der Konfigurations-Generatoren

Siehe ConfigurationBuilders Order of Execution im GitHub-Repository aspnet/MicrosoftConfigurationBuilders .

Implementieren eines benutzerdefinierten Konfigurations-Generators für Schlüssel/Wert

Wenn die Konfigurations-Builders Ihre Anforderungen nicht erfüllen, können Sie einen benutzerdefinierten Builder schreiben. 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 für Schlüssel-Wert-Paare mithilfe von GetValue und 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.

Zusätzliche Ressourcen

Feedback

War diese Seite hilfreich?

Last updated on 2026-03-27

Freigeben über

Konfigurations-Generatoren für ASP.NET

Schlüssel-/Wertkonfigurations-Generatoren

Einstellungen für Schlüssel-/Wertkonfigurations-Generatoren

Modus

Präfixbehandlung

stripPrefix

tokenPattern

Konfigurations-Generatoren in Microsoft.Configuration.ConfigurationBuilders

UmgebungsKonfigurationsErsteller

UserSecretsConfigBuilder

AzureKeyVaultConfigBuilder

KeyPerFileConfigBuilder

SimpleJsonConfigBuilder

Reihenfolge der Konfigurations-Generatoren

Implementieren eines benutzerdefinierten Konfigurations-Generators für Schlüssel/Wert

Zusätzliche Ressourcen

Feedback

Zusätzliche Ressourcen