Konfigurationsanbieter in .NET

Die Konfiguration in .NET kann mit Konfigurationsanbietern durchgeführt werden. Mehrere Typen von Anbietern basieren auf verschiedenen Konfigurationsquellen. In diesem Artikel werden alle unterschiedlichen Konfigurationsanbieter und ihre entsprechenden Quellen ausführlich erläutert.

• Dateikonfigurationsanbieter
• Umgebungsvariablen-Konfigurationsanbieter
• Befehlszeilen-Konfigurationsanbieter
• Schlüssel-pro-Datei-Konfigurationsanbieter
• Speicherkonfigurationsanbieter

Dateikonfigurationsanbieter

FileConfigurationProvider ist die Basisklasse für das Laden einer Konfiguration aus dem Dateisystem. Die folgenden Konfigurationsanbieter leiten sich vom FileConfigurationProvider ab:

• JSON-Konfigurationsanbieter
• XML-Konfigurationsanbieter
• INI-Konfigurationsanbieter

Bei Schlüsseln wird die Groß-/Kleinschreibung nicht beachtet. Alle Dateikonfigurationsanbieter lösen die FormatException aus, wenn doppelte Schlüssel in einem einzelnen Anbieter gefunden werden.

JSON-Konfigurationsanbieter

Die JsonConfigurationProvider-Klasse lädt die Konfiguration aus einer JSON-Datei. Installieren Sie das NuGet-Paket Microsoft.Extensions.Configuration.Json.

Überladungen können Folgendes angeben:

• Ob die Datei optional ist
• Ob die Konfiguration bei Dateiänderungen neu geladen wird

Betrachten Sie folgenden Code:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using ConsoleJson.Example;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.Sources.Clear();

IHostEnvironment env = builder.Environment;

builder.Configuration
    .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
    .AddJsonFile($"appsettings.{env.EnvironmentName}.json", true, true);

TransientFaultHandlingOptions options = new();
builder.Configuration.GetSection(nameof(TransientFaultHandlingOptions))
    .Bind(options);

Console.WriteLine($"TransientFaultHandlingOptions.Enabled={options.Enabled}");
Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={options.AutoRetryDelay}");

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Der vorangehende Code:

• Löscht alle vorhandenen Konfigurationsanbieter, die in der CreateApplicationBuilder(String[])-Methode standardmäßig hinzugefügt wurden
• Konfiguriert den JSON-Konfigurationsanbieter so, dass die Dateien appsettings.json und appsettings.Environment.json mit den folgenden Optionen geladen werden:
  • optional: true: Die Datei ist optional.
  • reloadOnChange: true: Die Datei wird erneut geladen, wenn Änderungen gespeichert werden.

Eine appsettings.json-Beispieldatei mit unterschiedliche Konfigurationseinstellungen geht wie folgt vor:

{
    "SecretKey": "Secret key value",
    "TransientFaultHandlingOptions": {
        "Enabled": true,
        "AutoRetryDelay": "00:00:07"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    }
}

Sie können nach dem Hinzufügen der Konfigurationsanbieter aus der IConfigurationBuilder-Instanz IConfigurationBuilder.Build() aufrufen, um das IConfigurationRoot-Objekt abzurufen. Der Konfigurationsstamm stellt den Stamm einer Konfigurationshierarchie dar. Abschnitte aus der Konfiguration können an Instanzen von .NET-Objekten gebunden werden und später über Abhängigkeitsinjektion (DI) als IOptions<TOptions> bereitgestellt werden.

Sehen Sie sich die TransientFaultHandlingOptions-Klasse in der folgenden Definition an:

namespace ConsoleJson.Example;

public sealed class TransientFaultHandlingOptions
{
    public bool Enabled { get; set; }
    public TimeSpan AutoRetryDelay { get; set; }
}

Der folgende Code erstellt den Konfigurationsstamm, bindet einen Abschnitt an den TransientFaultHandlingOptions-Klassentyp und gibt die gebundenen Werte im Konsolenfenster aus:

TransientFaultHandlingOptions options = new();
builder.Configuration.GetSection(nameof(TransientFaultHandlingOptions))
    .Bind(options);

Console.WriteLine($"TransientFaultHandlingOptions.Enabled={options.Enabled}");
Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={options.AutoRetryDelay}");

Die Anwendung schreibt dann die folgende Beispielausgabe:

// Sample output:
//    TransientFaultHandlingOptions.Enabled=True
//    TransientFaultHandlingOptions.AutoRetryDelay=00:00:07

XML-Konfigurationsanbieter

Die XmlConfigurationProvider-Klasse lädt die Konfiguration zur Laufzeit aus einer XML-Datei. Installieren Sie das NuGet-Paket Microsoft.Extensions.Configuration.Xml.

Im folgenden Code wird die Konfiguration von XML-Dateien mithilfe des XML-Konfigurationsanbieters veranschaulicht.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.Sources.Clear();

builder.Configuration
    .AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true)
    .AddXmlFile("repeating-example.xml", optional: true, reloadOnChange: true);

builder.Configuration.AddEnvironmentVariables();

if (args is { Length: > 0 })
{
    builder.Configuration.AddCommandLine(args);
}

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Der vorangehende Code:

• Löscht alle vorhandenen Konfigurationsanbieter, die in der CreateApplicationBuilder(String[])-Methode standardmäßig hinzugefügt wurden
• Konfiguriert den XML-Konfigurationsanbieter zum Laden der appsettings.xml- und repeating-example.xml-Dateien mit den folgenden Optionen:
  • optional: true: Die Datei ist optional.
  • reloadOnChange: true: Die Datei wird erneut geladen, wenn Änderungen gespeichert werden.
• Konfiguriert den Konfigurationsanbieter für Umgebungsvariablen
• Konfiguriert den Konfigurationsanbieter für die Befehlszeile, wenn args Argumente enthält.

Die XML-Einstellungen werden durch Einstellungen im Umgebungsvariablen-Konfigurationsanbieter und im Befehlszeilen-Konfigurationsanbieter überschrieben.

Eine appsettings.xml-Beispieldatei mit unterschiedliche Konfigurationseinstellungen geht wie folgt vor:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <SecretKey>Secret key value</SecretKey>
  <TransientFaultHandlingOptions>
    <Enabled>true</Enabled>
    <AutoRetryDelay>00:00:07</AutoRetryDelay>
  </TransientFaultHandlingOptions>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

Fügen Sie in .NET 5 und früheren Versionen das name-Attribut hinzu, um sich wiederholende Elemente zu unterscheiden, die den gleichen Elementnamen verwenden. In .NET 6 und höher werden sich wiederholende Elemente vom XML-Konfigurationsanbieter automatisch indiziert. Das bedeutet, dass Sie das name-Attribut nicht angeben müssen, es sei denn, Sie möchten den Index „0“ im Schlüssel und es gibt nur ein Element. (Wenn Sie ein Upgrade auf .NET 6 oder höher durchführen, tritt möglicherweise eine Unterbrechung auf, die sich aus dieser Verhaltensänderung ergibt. Weitere Informationen finden Sie unter Wiederholte XML-Elemente enthalten Index.)

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <section name="section0">
    <key name="key0">value 00</key>
    <key name="key1">value 01</key>
  </section>
  <section name="section1">
    <key name="key0">value 10</key>
    <key name="key1">value 11</key>
  </section>
</configuration>

Der folgende Code liest die vorherige Konfigurationsdatei und zeigt die Schlüssel und Werte an:

IConfigurationRoot configurationRoot = builder.Configuration;

string key00 = "section:section0:key:key0";
string key01 = "section:section0:key:key1";
string key10 = "section:section1:key:key0";
string key11 = "section:section1:key:key1";

string? val00 = configurationRoot[key00];
string? val01 = configurationRoot[key01];
string? val10 = configurationRoot[key10];
string? val11 = configurationRoot[key11];

Console.WriteLine($"{key00} = {val00}");
Console.WriteLine($"{key01} = {val01}");
Console.WriteLine($"{key10} = {val10}");
Console.WriteLine($"{key10} = {val11}");

Die Anwendung schreibt dann die folgende Beispielausgabe:

// Sample output:
//    section:section0:key:key0 = value 00
//    section:section0:key:key1 = value 01
//    section:section1:key:key0 = value 10
//    section:section1:key:key0 = value 11

Mit Attributen können Werte bereitgestellt werden:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <key attribute="value" />
  <section>
    <key attribute="value" />
  </section>
</configuration>

Die vorherige Konfigurationsdatei lädt die folgenden Schlüssel mit value:

• key:attribute
• section:key:attribute

INI-Konfigurationsanbieter

Die IniConfigurationProvider-Klasse lädt die Konfiguration zur Laufzeit aus einer INI-Datei. Installieren Sie das NuGet-Paket Microsoft.Extensions.Configuration.Ini.

Der folgende Code löscht alle Konfigurationsanbieter und fügt IniConfigurationProvider mit zwei INI-Dateien als Quelle hinzu:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
builder.Configuration.Sources.Clear();

IHostEnvironment env = builder.Environment;

builder.Configuration
    .AddIniFile("appsettings.ini", optional: true, reloadOnChange: true)
    .AddIniFile($"appsettings.{env.EnvironmentName}.ini", true, true);

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Eine appsettings.ini-Beispieldatei mit unterschiedliche Konfigurationseinstellungen geht wie folgt vor:

SecretKey="Secret key value"

[TransientFaultHandlingOptions]
Enabled=True
AutoRetryDelay="00:00:07"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Der folgende Code zeigt die vorangehenden Konfigurationseinstellungen an, indem sie in das Konsolenfenster geschrieben wird:

foreach ((string key, string? value) in
    builder.Configuration.AsEnumerable().Where(t => t.Value is not null))
{
    Console.WriteLine($"{key}={value}");
}

Die Anwendung schreibt dann die folgende Beispielausgabe:

// Sample output:
//    TransientFaultHandlingOptions:Enabled=True
//    TransientFaultHandlingOptions:AutoRetryDelay=00:00:07
//    SecretKey=Secret key value
//    Logging:LogLevel:Microsoft=Warning
//    Logging:LogLevel:Default=Information

Konfigurationsanbieter für Umgebungsvariablen

Bei Verwendung der Standardkonfiguration lädt der EnvironmentVariablesConfigurationProvider die Konfiguration aus Schlüssel-Wert-Paaren der Umgebungsvariablen, nachdem appsettings.json, appsettings.Environment.json und Secret Manager gelesen wurden. Daher überschreiben aus der Umgebung gelesene Schlüsselwerte Werte, die aus appsettings.json, appsettings.Environment.json und Secret Manager gelesen wurden.

Das Trennzeichen : funktioniert nicht auf allen Plattformen mit den hierarchischen Schlüsseln von Umgebungsvariablen. Beispielsweise wird das Trennzeichen : von Bash nicht unterstützt. Der doppelte Unterstrich (__), der auf allen Plattformen unterstützt wird, ersetzt automatisch alle :-Trennzeichen in Umgebungsvariablen.

Betrachten Sie die TransientFaultHandlingOptions Klasse:

public class TransientFaultHandlingOptions
{
    public bool Enabled { get; set; }
    public TimeSpan AutoRetryDelay { get; set; }
}

Mit den folgenden set-Befehlen werden die Umgebungsschlüssel und -werte von SecretKey und TransientFaultHandlingOptions festgelegt.

set SecretKey="Secret key from environment"
set TransientFaultHandlingOptions__Enabled="true"
set TransientFaultHandlingOptions__AutoRetryDelay="00:00:13"

Diese Umgebungseinstellungen werden nur in Prozessen festgelegt, die über das Befehlsfenster gestartet werden, in dem sie festgelegt wurden. Sie werden von Web-Apps, die mit Visual Studio gestartet wurden, nicht gelesen.

Mit Visual Studio 2019 und höher können Sie Umgebungsvariablen über das Dialogfeld Startprofile angeben.

Die folgenden setx-Befehle können zum Festlegen der Umgebungsschlüssel und -werte unter Windows verwendet werden. Anders als set werden setx-Einstellungen beibehalten. /M legt die Variable in der Systemumgebung fest. Wenn der /M-Schalter nicht verwendet wird, wird eine Benutzerumgebungsvariable festgelegt.

setx SecretKey "Secret key from setx environment" /M
setx TransientFaultHandlingOptions__Enabled "true" /M
setx TransientFaultHandlingOptions__AutoRetryDelay "00:00:05" /M

So testen Sie, ob die obigen Befehle appsettings.json- und appsettings.Environment.json-Einstellungen außer Kraft setzen

• Mit Visual Studio: Beenden Sie Visual Studio, und starten Sie dann Visual Studio neu.
• Mit der Befehlszeilenschnittstelle: Starten Sie ein neues Befehlsfenster, und geben Sie dotnet run ein.

Präfixe

Um ein Präfix für Umgebungsvariablen anzugeben, rufen Sie AddEnvironmentVariables mit einer Zeichenfolge auf:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.AddEnvironmentVariables(prefix: "CustomPrefix_");

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Für den Code oben gilt:

• config.AddEnvironmentVariables(prefix: "CustomPrefix_") wird nach den Standardkonfigurationsanbietern hinzugefügt. Ein Beispiel für das Festlegen der Reihenfolge der Konfigurationsanbieter finden Sie unter XML-Konfigurationsanbieter.
• Umgebungsvariablen, die mit dem CustomPrefix_-Präfix festgelegt wurden, überschreiben die Standardkonfigurationsanbieter. Dies schließt Umgebungsvariablen ohne das Präfix ein.

Das Präfix wird beim Lesen der Schlüssel-Wert-Paare der Konfiguration entfernt.

Die Standardkonfiguration lädt Umgebungsvariablen und Befehlszeilenargumente, die das Präfix DOTNET_ aufweisen. Das Präfix DOTNET_wird von .NET zum Hosten und für die App-Konfiguration verwendet, jedoch nicht für die Benutzerkonfiguration.

Weitere Informationen zur Host- und App-Konfiguration finden Sie unter .NET Generic Host.

Präfixe für Verbindungszeichenfolgen

Die Konfigurations-API verfügt über spezielle Verarbeitungsregeln für vier Umgebungsvariablen für Verbindungszeichenfolgen. Diese Verbindungszeichenfolgen sind beim Konfigurieren von Azure-Verbindungszeichenfolgen für die App-Umgebung beteiligt. Umgebungsvariablen mit den in der Tabelle aufgeführten Präfixen werden mit der Standardkonfiguration in die App geladen bzw. wenn kein Präfix für AddEnvironmentVariables bereitgestellt wird.

Wenn eine Umgebungsvariable entdeckt und mit einem der vier Präfixe aus der Tabelle in die Konfiguration geladen wird, tritt Folgendes ein:

• Der Konfigurationsschlüssel wird durch Entfernen des Umgebungsvariablenpräfixes und Hinzufügen eines Konfigurationsschlüsselabschnitts (ConnectionStrings) erstellt.
• Ein neues Konfigurations-Schlüssel-Wert-Paar wird erstellt, das den Datenbankverbindungsanbieter repräsentiert (mit Ausnahme des Präfixes CUSTOMCONNSTR_, für das kein Anbieter angegeben ist).

In „launchSettings.json“ festgelegte Umgebungsvariablen

Umgebungsvariablen, die in der Datei launchSettings.json festgelegt sind, überschreiben diejenigen, die in der Systemumgebung festgelegt sind.

Azure App Service-Einstellungen

Wählen Sie in Azure App Service auf der Seite Einstellungen>Konfiguration die Option Neue Anwendungseinstellung aus. Anwendungseinstellungen von Azure App Service werden:

• Im Ruhezustand verschlüsselt und über einen verschlüsselten Kanal übermittelt.
• Als Umgebungsvariablen verfügbar gemacht.

Befehlszeilen-Konfigurationsanbieter

Bei Verwendung der Standard-Konfiguration lädt der CommandLineConfigurationProvider die Konfiguration aus den Schlüssel-Wert-Paaren des Befehlszeilenarguments nach den folgenden Konfigurationsquellen:

• Dateien appsettings.json und appsettings.Environment.json.
• App-Geheimnisse (Secret Manager) in der Development-Umgebung
• Umgebungsvariablen.

Standardmäßig überschreiben in der Befehlszeile festgelegte Konfigurationswerte die Konfigurationswerte, die mit allen anderen Konfigurationsanbietern festgelegt wurden.

Mit Visual Studio 2019  und höher können Sie Befehlszeilenargumente über das Dialogfeld Startprofile angeben.

Befehlszeilenargumente

Der folgende Befehl legt Schlüssel und Werte unter Verwendung von = fest:

dotnet run SecretKey="Secret key from command line"

Der folgende Befehl legt Schlüssel und Werte unter Verwendung von / fest:

dotnet run /SecretKey "Secret key set from forward slash"

Der folgende Befehl legt Schlüssel und Werte unter Verwendung von -- fest:

dotnet run --SecretKey "Secret key set from double hyphen"

Der Schlüsselwert:

• Muss auf = folgen, oder der Schlüssel muss das Präfix -- oder / aufweisen, wenn der Wert auf ein Leerzeichen folgt.
• Ist nicht erforderlich, wenn = verwendet wird. Beispielsweise SomeKey=.

Kombinieren Sie in einem Befehl nicht Schlüssel-Wert-Paare des Befehlszeilenarguments, die = verwenden, mit Schlüssel-Wert-Paaren, die ein Leerzeichen verwenden.

Schlüssel-pro-Datei-Konfigurationsanbieter

KeyPerFileConfigurationProvider verwendet Verzeichnisdateien als Konfigurations-Schlüssel-Wert-Paare. Der Schlüssel ist der Dateiname. Der Wert ist der Inhalt der Datei. Der Schlüssel-pro-Datei-Konfigurationsanbieter wird in Docker-Hostingszenarios verwendet.

Um die Schlüssel-pro-Datei-Konfiguration zu aktivieren, rufen Sie die AddKeyPerFile-Erweiterungsmethode auf einer ConfigurationBuilder-Instanz auf. Der directoryPath zu den Dateien muss ein absoluter Pfad sein.

Überladungen geben Folgendes an:

• Einen Action<KeyPerFileConfigurationSource>-Delegat, der die Quelle konfiguriert
• Ob das Verzeichnis optional ist; und den Pfad zum Verzeichnis

Der doppelte Unterstrich (__) wird als Trennzeichen für Konfigurationsschlüssel in Dateinamen verwendet. Der Dateiname Logging__LogLevel__System erzeugt z.B. den Konfigurationsschlüssel Logging:LogLevel:System.

Rufen Sie ConfigureAppConfiguration beim Erstellen des Hosts auf, um die Konfiguration der App anzugeben:

.ConfigureAppConfiguration((_, configuration) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");

    configuration.AddKeyPerFile(directoryPath: path, optional: true);
})

Speicherkonfigurationsanbieter

MemoryConfigurationProvider verwendet eine In-Memory-Sammlung für Konfigurations-Schlüssel-Wert-Paare.

Der folgende Code fügt eine Arbeitsspeichersammlung zum Konfigurationssystem hinzu:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.AddInMemoryCollection(
    new Dictionary<string, string?>
    {
        ["SecretKey"] = "Dictionary MyKey Value",
        ["TransientFaultHandlingOptions:Enabled"] = bool.TrueString,
        ["TransientFaultHandlingOptions:AutoRetryDelay"] = "00:00:07",
        ["Logging:LogLevel:Default"] = "Warning"
    });

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Im vorangehenden Code fügt MemoryConfigurationBuilderExtensions.AddInMemoryCollection(IConfigurationBuilder, IEnumerable<KeyValuePair<String,String>>) den Speicheranbieter nach den Standardkonfigurationsanbietern hinzu. Ein Beispiel für das Festlegen der Reihenfolge der Konfigurationsanbieter finden Sie unter XML-Konfigurationsanbieter.

Siehe auch

• Konfiguration in .NET
• Generischer .NET-Host
• Implementieren eines benutzerdefinierten Konfigurationsanbieters