Konfiguration in ASP.NET Core

Die App-Konfiguration in ASP.NET Core wird mit einem oder mehreren Konfigurationsanbietern ausgeführt. Konfigurationsanbieter lesen Konfigurationsdaten aus Schlüssel-Wert-Paaren unter Verwendung verschiedener Konfigurationsquellen:

• Einstellungsdateien, z. B. appsettings.json
• Umgebungsvariablen, einschließlich Azure-App-Konfiguration
• Azure Key Vault
• Befehlszeilenargumente
• Benutzerdefinierte Anbieter (installiert oder erstellt)
• Speicherinterne .NET Objekte

Dieser Artikel liefert Informationen zur Konfiguration in ASP.NET Core. Informationen zur Verwendung der Konfiguration in non-ASP.NET Core-Apps finden Sie unter .NET-Konfiguration.

Weitere Blazor Konfigurationsanleitungen, die den Hier aufgeführten Richtlinien hinzufügen oder ersetzen, finden Sie unter ASP.NET Core-KonfigurationBlazor.

Dieser Artikel bezieht sich in erster Linie auf die App-Konfiguration. Andere Konfigurationstypen, z. B. Starteinstellungsdateien und die web.config Datei, werden hier erwähnt, aber ihre primäre Dokumentation befindet sich an anderer Stelle:

• Starten Sie die Einstellungsdateien (launch.json/launchSettings.json), die die Toolkonfigurationsdateien für die Development-Umgebung sind. Weitere Informationen finden Sie unter ASP.NET Core-Laufzeitumgebungen. Einige Details zu den Starteinstellungen werden in diesem Artikel im Abschnitt "Starteinstellungen überschreiben Umgebungsvariableneinstellungen" behandelt.
• web.config, bei dem es sich um eine Serverkonfigurationsdatei für Internetinformationsdienste (Internetinformationsdienste, IIS) handelt. Weitere Informationen finden Sie unter Host ASP.NET Core unter Windows mit IIS und ASP.NET Core Module (ANCM) für IIS.

Weitere Informationen zum Migrieren der App-Konfiguration aus früheren Versionen von ASP.NET finden Sie unter Migrieren der Konfiguration zu ASP.NET Core.

Warning

In diesem Artikel wird die Verwendung von Verbindungszeichenfolgen gezeigt. Bei Verwendung einer lokalen Datenbank für Entwicklung und Tests ist keine Datenbankbenutzerauthentifizierung über die Verbindungszeichenfolge erforderlich. In Produktionsumgebungen enthalten Verbindungszeichenfolgen manchmal ein Kennwort zum Authentifizieren des Datenbankzugriffs oder datenbankvorgänges. Ein RoPC (Resource Owner Password Credential) in einer Verbindungszeichenfolge ist ein Sicherheitsrisiko, das in Produktions-Apps vermieden werden kann. Produktions-Apps sollten den sichersten verfügbaren Ablauf für die Authentifizierung verwenden. Weitere Informationen zur Authentifizierung für Apps, die für Test- oder Produktionsumgebungen bereitgestellt werden, finden Sie unter ASP.NET Core-Sicherheitsthemen.

Beispiele in diesem Artikel verwenden primäre Konstruktoren, die in C# 12 (.NET 8) oder höher verfügbar sind. Weitere Informationen finden Sie unter Declare primary constructors for classes and structs (C# documentation tutorial) und Primary constructors (C# Guide).

Lesen von Konfigurationswerten

Die Konfiguration wird in der Regel durch Auflösen des IConfiguration-Diensts (Namespace Microsoft.Extensions.Configuration) und Verwenden der Schlüssel-Wert-Paare für die Konfiguration zum Abrufen eines Konfigurationswerts gelesen.

Der folgende Razor Komponentencode zeigt, wie ein Konfigurationswert, eine E-Mail-Adresse eines technischen Kontakts, von der Konfiguration anhand des Schlüssels TechnicalContactEmailabgerufen wird.

@inject IConfiguration Config

Technical Contact: @Config["TechnicalContactEmail"]

App- und Hostkonfiguration

Durch ASP.NET Core-Apps kann ein Host gestartet und konfiguriert werden. Der Host ist verantwortlich für das Starten der App und das Verwalten der Lebensdauer. Schlüssel-Wert-Paare der Host-Konfiguration sind in der App-Konfiguration enthalten. Obwohl Sie einige App-Konfigurationen mit Hostkonfigurationsanbietern ausführen können, empfehlen wir nur die Ausführung der Konfiguration, die für den Host in der Hostkonfiguration erforderlich ist.

Die App-Konfiguration ist die höchste Priorität. Weitere Informationen dazu, wie Konfigurationsanbieter beim Erstellen des Hosts verwendet werden, und wie sich Konfigurationsquellen auf die Hostkonfiguration auswirken, finden Sie unter ASP.NET Core – Übersicht über die Grundlagen.

Standard-App-Konfigurationsquellen

ASP.NET Core Web Apps aufrufen WebApplication.CreateBuilder , um eine neue Instanz der WebApplicationBuilder Klasse mit vorkonfigurierten Standardwerten zu initialisieren:

var builder = WebApplication.CreateBuilder(args);

Weitere Informationen finden Sie unter .NET Generic Host in ASP.NET Core.

Die Standardmäßige App-Konfiguration wird in der folgenden Reihenfolge geladen, von der höchsten bis zur niedrigsten Priorität:

1. Befehlszeilenargumente mithilfe des Befehlszeilenkonfigurationsanbieters.
2. Umgebungsvariablen ohne den Präfix ASPNETCORE_ oder DOTNET_, die den Umgebungsvariablen-Konfigurationsanbieter verwenden.
3. Geheime Benutzerschlüssel , wenn die App in der Development Umgebung mit dem Dateikonfigurationsanbieter ausgeführt wird.
4. Konfiguration der App-Einstellungsdatei für die Umgebung über appsettings.{ENVIRONMENT}.json, wobei der Platzhalter {ENVIRONMENT} die Umgebung der App ist, die den JSON-Konfigurationsanbieter verwendet. Wird beispielsweise appsettings.Production.json in der Produktion verwendet und appsettings.Development.json wird während der Entwicklung verwendet.
5. Allgemeine App-Einstellungsdateikonfiguration mithilfe appsettings.json des JSON-Konfigurationsanbieters.
6. Fallback-Host-Konfiguration

Note

Es wird nicht empfohlen, mehr als einmal nur zum Abrufen von Konfigurationswerten zur Laufzeit aufzurufen CreateBuilder . Es wird empfohlen, eine ConfigurationManager (z. B. : builder.Configuration, WebApplicationBuilder.Configuration) oder eine ConfigurationBuilder aus der entsprechenden Konfigurationsquelle zu verwenden.

Damit Befehlszeilenargumente Einstellungen wie den Umgebungsnamen steuern können, was wichtig ist, um zu bestimmen, welche umgebungsbasierte App-Einstellungsdatei geladen werden soll, wird der Befehlszeilenkonfigurationsanbieter am Anfang und Ende der Konfiguration zweimal als Konfigurationsquelle verwendet. Da der Anbieter am Ende verwendet wird, hat er die höchste Priorität.

Wenn ein Konfigurationswert in der Host- und App-Konfiguration festgelegt wird, wird die App-Konfiguration verwendet.

Standard-Hostkonfigurationsquellen

Die Quellen der Standard-Hostkonfiguration in der Reihenfolge von höchster zu niedrigster Priorität, wenn sie auf die Konfiguration der Web-App angewendet werden (WebApplicationBuilder):

1. Befehlszeilenargumente mithilfe des Befehlszeilenkonfigurationsanbieters.
2. Umgebungsvariablen mit dem Präfix DOTNET_, die den Umgebungsvariablen-Konfigurationsanbieter verwenden.
3. Umgebungsvariablen mit dem Präfix ASPNETCORE_, die den Umgebungsvariablen-Konfigurationsanbieter verwenden.

Standardhostkonfigurationsquellen von der höchsten bis zur niedrigsten Priorität, die entweder auf den generischen Host oder den Webhost angewendet werden:

1. Umgebungsvariablen mit dem Präfix ASPNETCORE_, die den Umgebungsvariablen-Konfigurationsanbieter verwenden.
2. Befehlszeilenargumente mithilfe des Befehlszeilenkonfigurationsanbieters.
3. Umgebungsvariablen mit dem Präfix DOTNET_, die den Umgebungsvariablen-Konfigurationsanbieter verwenden.

Weitere Informationen zur Hostkonfiguration finden Sie in den folgenden Ressourcen:

• Generischer Host: Empfohlen für ASP.NET Core-Apps für .NET 6 oder höher, die das minimale Hostingmodell übernehmen.
• Webhost: Erforderlich für ASP.NET Core-Apps, die auf Versionen vor .NET 6 abzielen und nur vom Framework zur Abwärtskompatibilität in .NET 6 oder höher verwaltet werden.

Hostvariablen

Die folgenden Variablen werden frühzeitig in der Host-Generator-Initialisierung festgelegt und können nicht von der App-Konfiguration beeinflusst werden:

• Anwendungsname.
• Umgebungsname.
• Inhaltsstamm.
• Webroot.
• Ob Sie nach Hosting-Startup-Assemblys suchen sollen und welche Assemblys gesucht werden sollen.
• Variablen, die von App- und Bibliothekscode aus HostBuilderContext.Configuration in IHostBuilder.ConfigureAppConfiguration-Rückrufen gelesen werden.

Andere Hosteinstellungen werden aus der App-Konfiguration anstelle der Hostkonfiguration gelesen.

URLS ist eine der vielen allgemeinen Hosteinstellungen, für die kein Bootstrap nach Hostkonfiguration ausgeführt wird. URLS wird später aus der Konfiguration der App ausgelesen. Die Hostkonfiguration ist ein Fallback für die App-Konfiguration, sodass die Hostkonfiguration zum Festlegen von URLS verwendet werden kann. Der Wert wird jedoch von jeder Konfigurationsquelle außer Kraft gesetzt, die URLS in der App-Konfiguration festlegt, z. B. App-Einstellungsdateien (appsettings.{ENVIRONMENT}.json, wobei der Platzhalter{ENVIRONMENT} der Umgebungsname ist, oder appsettings.json).

Weitere Informationen finden Sie unter Ändern des Inhaltsstamms, des App-Namens und der Umgebung und Ändern des Inhaltsstamms, des App-Namens und der Umgebung durch Umgebungsvariablen oder befehlszeile.

Sicherheit und Benutzergeheimnisse

Richtlinien für Konfigurationsdaten:

• Speichern Sie nie Kennwörter oder andere vertrauliche Daten im Konfigurationsanbietercode oder in Nur-Text-Konfigurationsdateien. Das Secret Manager-Tool kann zum Speichern von Geheimnissen in der Entwicklungsumgebung verwendet werden.
• Verwenden Sie keine Produktionsgeheimnisse in Entwicklungs- oder Testumgebungen.
• Geben Sie Geheimnisse außerhalb des Projekts an, damit sie nicht versehentlich in ein Quellcoderepository übernommen werden können.
• Produktions-Apps sollten den sichersten verfügbaren Ablauf für die Authentifizierung verwenden. Weitere Informationen finden Sie unter Sichere Authentifizierungsflüsse.

Die Dateikonfigurationsquelle für Benutzergeheimnisse der Standardkonfigurationsquellen wird nach der JSON-Konfigurationsquelle für App-Einstellungsdateien registriert. Daher besitzen geheime Benutzerschlüssel Vorrang vor Schlüsseln in appsettings.json und appsettings.{ENVIRONMENT}.json.

Weitere Informationen zum Speichern von Kennwörtern oder anderen vertraulichen Daten:

• ASP.NET Core-Laufzeitumgebungen
• Sicheres Speichern von App-Geheimnissen in der Entwicklung in ASP.NET Core: Hier finden Sie Hinweise zur Verwendung von Umgebungsvariablen zum Speichern vertraulicher Daten. Das Tool "Geheimer Manager" verwendet den Dateikonfigurationsanbieter , um geheime Benutzerschlüssel in einer JSON-Datei im lokalen System zu speichern.
• Azure Key Vault speichert App-Geheimnisse für ASP.NET Core-Apps auf sichere Weise. Weitere Informationen finden Sie unter Azure Key Vault-Konfigurationsanbieter in ASP.NET Core.

Zugriffskonfiguration mit Dependency Injection (DI)

Die Konfiguration kann mithilfe von Dependency Injection (DI) in Dienste eingefügt werden, indem der IConfiguration Dienst aufgelöst wird. Im folgenden Beispiel wird der für den vom Platzhalter dargestellte {KEY} Konfigurationsschlüssel gespeicherte Konfigurationswert zugewiesen value. Wenn der Schlüssel nicht gefunden wird, wird nullvalue zugewiesen.

public class CustomService(IConfiguration config)
{
    public void CustomMethod()
    {
        var value = config["{KEY}"];
    }
}

Access-Konfiguration in der Program Datei

Der folgende Code greift auf die Konfiguration in der Datei Program mithilfe von WebApplicationBuilder.Configuration (builder.Configuration) zu.

var defaultConnectionString = 
   builder.Configuration.GetValue<string>("ConnectionStrings:DefaultConnection");

Nachdem die App erstellt wurde (nach der Zeile var app = builder.Build();), verwenden Sie WebApplication.Configuration (app.Configuration):

var defaultLogLevel = app.Configuration.GetValue<string>("Logging:LogLevel:Default");

Access-Konfiguration in der Startup Klasse

Dieser Abschnitt gilt im Allgemeinen für ASP.NET Core-Apps vor der Veröffentlichung von .NET 6.

Der folgende Code zeigt Konfigurationsdaten in Startup-Methoden an:

public class Startup
{
    public Startup(IConfiguration config)
    {
        Config = config;
    }

    public IConfiguration Config { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        var connectionString = Config["ConnectionStrings.DefaultConnection"];

        ...
    }

    public void Configure(...)
    {
        var defaultLogLevel = Config["Logging:LogLevel:Default"];

        ...
    }
}

Anzeigen von Konfigurationseinstellungen beim Start für das Debuggen

Der folgende Code zeigt die Konfigurationsschlüssel-Wert-Paare der App beim App-Start an.

Nachdem die App in der Program Datei (nach der Zeile var app = builder.Build();) erstellt wurde, platzieren Sie den folgenden Code, der eine Compilerdirektive für die DEBUG-Konfiguration enthält:

#if DEBUG
foreach (var c in app.Configuration.AsEnumerable())
{
    Console.WriteLine($"CONFIG: Key: {c.Key} Value: {c.Value}");
}
#endif

Konfigurationsschlüssel und -werte

Konfigurationsschlüssel:

• Die Groß-/Kleinschreibung wird nicht berücksichtigt. Beispielsweise verweisen ConnectionString und connectionstring auf denselben Schlüssel.
• Wenn ein Schlüssel und Wert von mehreren Konfigurationsanbietern festgelegt werden, wird der Wert aus dem letzten hinzugefügten Anbieter verwendet. Weitere Informationen finden Sie unter Standardkonfiguration.
• Hierarchische Schlüssel
  • Innerhalb der Konfigurations-API funktioniert ein Doppelpunkt (:) als Trennzeichen auf allen Plattformen.
  • In Umgebungsvariablen funktioniert ein Doppelpunkttrennzeichen nicht auf allen Plattformen. Ein doppelter Unterstrich (__) wird von allen Plattformen unterstützt und automatisch in einen Doppelpunkt (:) konvertiert, wenn die Konfiguration von der App gelesen wird.
  • In Azure Key Vault verwenden hierarchische Schlüssel doppelte Gedankenstriche (--) als Trennzeichen. Der Azure Key Vault-Konfigurationsanbieter ersetzt automatisch die doppelten Gedankenstriche (--) durch einen Doppelpunkt (:) wenn die geheimen Schlüssel in die Konfiguration der App geladen werden.
• ConfigurationBinder unterstützt das Binden von Arrays an Objekte mit Arrayindizes in Konfigurationsschlüsseln. Die Arraybindung wird im Abschnitt "Binden eines Arrays" beschrieben.

Konfigurationswerte sind Zeichenfolgen. NULL-Werte können nicht in einer Konfiguration gespeichert oder an Objekte gebunden werden.

Struktur von hierarchischen Konfigurationsdaten

Die Konfigurations-API liest hierarchische Konfigurationsdaten, indem sie die hierarchischen Daten mit einem Trennzeichen in den Konfigurationsschlüsseln vereinfacht. Diese sind i. d. R. Doppelpunkte (:). Doppelte Unterstriche (__) werden in der Regel mit umgebungsvariabler Konfiguration für plattformübergreifende Unterstützung verwendet.

Note

In komplexen App-Konfigurationsszenarien ist es am besten, verwandte hierarchische Konfigurationsdaten mithilfe des Optionsmusters zu gruppieren und zu lesen.

Betrachten Sie die folgenden hierarchischen Konfigurationsdaten:

• ConnectionStrings
  • DefaultConnection (Value = 'Data Source=LocalSqlServer\MSSQLDev;')
• Logging
  • LogLevel
    • Default (Value = 'Information')
    • Microsoft (Value = 'Warning')
    • Microsoft.Hosting.Lifetime (Value = 'Information')
• AllowedHosts (Value = '*')

In der folgenden Tabelle werden die Schlüssel angezeigt, die zum Wiederherstellen der Werte in den vorherigen Konfigurationsdaten verwendet werden. Das Trennzeichen ist für AllowedHosts nicht erforderlich.

Schlüssel (Doppelpunkttrennzeichen)	Schlüssel (Trennzeichen doppelter Unterstrich)
ConnectionStrings:DefaultConnection	ConnectionStrings__DefaultConnection
Logging:LogLevel:Default	Logging__LogLevel__Default
Logging:LogLevel:Microsoft	Logging__LogLevel__Microsoft
Logging:LogLevel:Microsoft.Hosting.Lifetime	Logging__LogLevel__Microsoft.Hosting.Lifetime
AllowedHosts	AllowedHosts

Note

In komplexen App-Konfigurationsszenarien wird empfohlen, verwandte hierarchische Konfigurationsdaten mithilfe des Optionsmusters zu gruppieren und zu lesen.

Mit den Methoden GetSection und GetChildren können Abschnitte und Unterabschnitte in den Konfigurationsdaten isoliert werden. Diese Methoden werden beschrieben, wo GetSection, GetChildren, und Exists werden behandelt.

Wenn die Elementstruktur ein Array enthält, sollte der Arrayindex als zusätzlicher Elementname im Pfad behandelt werden. Betrachten Sie die folgenden hierarchischen Konfigurationsdaten als Array.

MainObject (ein Array):

• Erstes Element im Array
  • Object0
  • Object1
    • SubObject0
    • SubObject1
• Zweites Element im Array
  • Object0
  • Object1
    • SubObject0
    • SubObject1

Schlüssel mit Doppelpunkt-Trennzeichen:

• MainObject:0:Object0
• MainObject:0:Object1:SubObject0
• MainObject:0:Object1:SubObject1
• MainObject:1:Object0
• MainObject:1:Object1:SubObject0
• MainObject:1:Object1:SubObject1

Schlüssel mit Unterstrich-Trennzeichen, die zur Sicherstellung plattformübergreifender Kompatibilität empfohlen werden, wenn die Konfiguration von Umgebungsvariablen bereitgestellt wird:

• MainObject__0__Object0
• MainObject__0__Object1:SubObject0
• MainObject__0__Object1:SubObject1
• MainObject__1__Object0
• MainObject__1__Object1:SubObject0
• MainObject__1__Object1:SubObject1

Da die Konfiguration, die aus Arrays stammt, für jede Konfigurationsquelle, die von einer App verwendet wird, vereinfacht und nummeriert wird, können Werte ggf. unerwartet überschrieben werden, wenn beim Strukturieren und Lesen der Daten aus mehreren Quellen nicht sorgfältig darauf geachtet wird. Berücksichtigen Sie die folgenden Konfigurations-Schlüsselwertpaare:

Modules Werte (ein Array):

• Module1
• Module2
• Module3

Das Array wird vereinfacht und sequenziell indiziert, sodass die Schlüssel-Wert-Paare für die Konfiguration in der folgenden Tabelle zurückgegeben werden.

Key	Wert
Modules:0	Module1
Modules:1	Module2
Modules:2	Module3

Nachdem die vorherige Konfiguration eingerichtet wurde, lädt eine andere Konfigurationsquelle die folgende Konfiguration:

Modules Werte (ein Array):

• Module4
• Module5

Dieses Array wird ebenfalls abgeflacht und sequenziell indiziert.

Key	Wert
Modules:0	Module4
Modules:1	Module5

Erinnert daran, dass die letzte Konfigurationsquelle für einen bestimmten Schlüssel den Wert dieses Schlüssels festlegt, werden die endgültigen Konfigurationsschlüssel-Wert-Paare in der folgenden Tabelle angezeigt.

Key	Wert
Modules:0	Module4
Modules:1	Module5
Modules:2	Module3

Angesichts der Art und Weise, wie das Framework Arraydaten aus Konfigurationsquellen vereinfacht und indiziert, ist dieses Ergebnis nicht überraschend, doch sollte man dies im Hinterkopf behalten, um unerwartete Überschreibungen zu vermeiden.

Um solche Überschreibungen zu vermeiden, passen Sie die Arrayindizierung an die verschiedenen Konfigurationsquellen an, die identische Arraydaten bereitstellen. Alternativ besteht eine Problemumgehung darin, Arraywerte in einem Zeichenfolgenwert eines einzelnen Schlüssel-Wert-Paars zu trennen, z. B. mithilfe eines Kommas, Semikolons oder einer Pipe als Trennzeichen. Schreiben Sie benutzerdefinierten Code, um die Zeichenfolge aufzuteilen, und weisen Sie dem Array die getrennten Werte zu.

Konfigurationsanbieter

Die folgende Tabelle zeigt die für ASP.NET Core-Apps verfügbaren Konfigurationsanbieter.

Provider	Bietet Konfiguration von…
Azure Key Vault-Konfigurationsanbieter	Azure Key Vault
Azure App-Konfigurationsanbieter	Azure App Configuration
Anbieter für Befehlszeilenkonfiguration	Befehlszeilenparameter
Benutzerdefinierter Konfigurationsanbieter	Benutzerdefinierte Quelle
Konfigurationsanbieter für Umgebungsvariablen	Umgebungsvariablen
Dateikonfigurationsanbieter	INI-, JSON- und XML-Dateien
Key-Per-File Konfigurationsanbieter	Verzeichnisdateien
Speicherkonfigurationsanbieter	In-Memory-Sammlungen
Geheime Benutzerschlüssel	Datei im Benutzerprofilverzeichnis

Konfigurationsquellen werden in der Reihenfolge gelesen, in der ihre Konfigurationsanbieter angegeben sind. Ordnen Sie die Konfigurationsanbieter im Code so an, dass sie den Prioritäten für die zugrunde liegenden Konfigurationsquellen entsprechen, die für die App erforderlich sind.

Eine typische Konfigurationsanbietersequenz ist:

1. Allgemeine App-Einstellungen über appsettings.json.
2. Umgebungs-App-Einstellungen über appsettings.{ENVIRONMENT}.json, wobei der {ENVIRONMENT} Platzhalter die Umgebung der App ist (Beispiele: Development, Production).
3. Geheime Benutzerschlüssel.
4. Umgebungsvariablen mithilfe des Konfigurationsanbieters für Umgebungsvariablen.
5. Befehlszeilenargumente mithilfe des Befehlszeilenkonfigurationsanbieters.

Üblich ist es, den Befehlszeilenkonfigurationsanbieter zuletzt in einer Reihe von Anbietern hinzuzufügen, damit Befehlszeilenargumente die von den anderen Anbietern festgelegte Konfiguration außer Kraft setzen können.

Die obige Sequenz von Anbietern wird in der Standardkonfiguration verwendet.

Um die Konfigurationsanbieter der App zu prüfen, fügen Sie IConfiguration ein, wandeln Sie es in IConfigurationRoot um, und lesen Sie die Eigenschaft Providers.

In der folgenden ConfigurationProvidersRazor Komponente werden die aktivierten Konfigurationsanbieter in der Reihenfolge angezeigt, in der sie der App hinzugefügt werden.

Pages/ConfigurationProviders.razor:

@page "/configuration-providers"
@inject IConfiguration Config

<h1>Configuration Providers</h1>

@if (ConfigRoot is not null)
{
    <ul>
        @foreach (var provider in ConfigRoot.Providers)
        {
            <li>@provider</li>
        }
    </ul>
}

@code {
    private IConfigurationRoot? ConfigRoot;

    protected override void OnInitialized()
    {
        ConfigRoot = (IConfigurationRoot)Config;
    }
}

Die vorangehende Razor Komponente erzeugt die folgende Ausgabe, wobei der {APP NAMESPACE} Platzhalter der Namespace der App ist:

MemoryConfigurationProvider
EnvironmentVariablesConfigurationProvider Prefix: 'ASPNETCORE_'
MemoryConfigurationProvider
EnvironmentVariablesConfigurationProvider Prefix: 'DOTNET_'
JsonConfigurationProvider for 'appsettings.json' (Optional)
JsonConfigurationProvider for 'appsettings.Development.json' (Optional)
JsonConfigurationProvider for '{APP NAMESPACE}.settings.json' (Optional)
JsonConfigurationProvider for '{APP NAMESPACE}.settings.Development.json' (Optional)
EnvironmentVariablesConfigurationProvider
Microsoft.Extensions.Configuration.ChainedConfigurationProvider

Im Abschnitt "Standard-App-Konfigurationsquellen " weiter oben in diesem Artikel werden Konfigurationsquellen von der höchsten bis zur niedrigsten Priorität aufgeführt. In der vorherigen ConfigurationProviders Komponente werden die Quellen in der Reihenfolge angezeigt, in der sie von der App gelesen werden. Beispielsweise befindet sich der JSON-Konfigurationsanbieter für die Nicht-Umgebungs-App-Einstellungsdatei (appsettings.json) weiter oben in der vorherigen Liste, da er vor dem Anbieter für die Entwicklungsumgebung-App-Einstellungsdatei (appsettings.Development.json) hinzugefügt wird. Die Konfigurationsanbieter werden vom Anfang der Liste bis zum Ende der Liste ausgeführt. Für einen passenden Konfigurationsschlüssel zwischen den beiden JSON-Konfigurationsanbietern in den App-Einstellungen hat die letzte Einstellung Vorrang, wobei der Wert von appsettings.Development.json stammt.

Konfiguration der App-Einstellungsdatei (appsettings.json, appsettings.{ENVIRONMENT}.json)

Lesen Sie die Konfiguration, die mithilfe des JSON-Konfigurationsanbieters aus App-Einstellungsdateien geladen wurde.

Betrachten Sie die folgende appsettings.json -Datei:

{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=LocalSqlServer\\MSSQLDev;"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Einfügen einer Instanz zum Lesen von IConfiguration Konfigurationswerten.

Die folgende AppSettingsConfigurationRazor Komponente liest die Standard-Datenbankverbindungszeichenfolge und die Standard-Protokollierungsstufe aus. IConfiguration wird oben in die Komponente eingefügt und zum Lesen von Konfigurationswerten verwendet. Ein Doppelpunkt-Trennzeichen (:) wird in Zeichenfolgentypkonfigurationsschlüsseln verwendet, um die entsprechenden JSON-Eigenschaften zu finden. Die JSON-Struktur für das Standardverbindungszeichenfolgenobjekt (DefaultConnection) wird z. B. unter dem Verbindungszeichenfolgenobjekt (ConnectionStrings) geschachtelt, sodass die Zeichenfolgennotation für den Zugriff auf die Standardverbindungszeichenfolge einen Doppelpunkt zum Trennen DefaultConnection und ConnectionStrings in der Reihenfolge verwendet, in der die Objekte in der App-Einstellungsdatei angezeigt werden: ConnectionStrings:DefaultConnection.

Pages/AppSettingsConfiguration.razor:

@page "/app-settings-configuration"
@inject IConfiguration Config

<h1>App Settings Configuration</h1>

<ul>
    <li>Default Connection String: @Config["ConnectionStrings:DefaultConnection"]
    <li>Default Log Level: @Config["Logging:LogLevel:Default"]
</ul>

Der gleiche Ansatz wird in einem Razor Pages-Seitenmodell verfolgt:

using Microsoft.Extensions.Configuration;

...

public class AppSettingsPageModel(IConfiguration config) : PageModel
{
    public ContentResult OnGet()
    {
        var defaultConnectionString = config["ConnectionStrings:DefaultConnection"];
        var defaultLogLevel = config["Logging:LogLevel:Default"];

        return Content(
            $"Default Connection String: {defaultConnectionString}\n" +
            $"Default Log Level: {defaultLogLevel}");
    }
}

Die Standardinstanzen JsonConfigurationProvider laden die Konfiguration in der folgenden Reihenfolge:

1. appsettings.json
2. appsettings.{ENVIRONMENT}.json, wobei der {ENVIRONMENT} Platzhalter die Umgebung der App ist (Beispiele: appsettings.Production.json, appsettings.Development.json). Die Umgebungsversion der Datei wird basierend auf IHostingEnvironment.EnvironmentName geladen.

appsettings.{ENVIRONMENT}.json-Werte überschreiben Schlüssel in appsettings.json.

Standardmäßig:

• In der Entwicklungsumgebung überschreibt die appsettings.Development.json-Konfiguration Werte, die in appsettings.json gefunden werden.
• In der Produktionsumgebung überschreibt die Konfiguration in appsettings.Production.json die Werte in appsettings.json.

Im vorherigen Beispiel werden nur Zeichenfolgen gelesen und kein Standardwert unterstützt. Wenn ein Konfigurationswert mit einem Standardwert garantiert werden muss, lesen Sie den Abschnitt " Extrahieren eines einzelnen Werts aus der Konfiguration mit Typkonvertierung (GetValue) ".

Bei Verwendung der Standard-App-Konfigurationsquellen sind die Dateien appsettings.json und appsettings.{ENVIRONMENT}.json aktiviert, wobei reloadOnChange auf true festgelegt ist. Dies bedeutet, dass Änderungen, die an den Dateien appsettings.json oder appsettings.{ENVIRONMENT}.json nach dem Starten der App vorgenommen werden, unmittelbar nach dem Speichern der Datei wirksam werden.

Kommentare in appsettings.json- und appsettings.{ENVIRONMENT}.json-Dateien werden mit JavaScript oder Kommentaren im C#-Format unterstützt. Einige integrierte Entwicklungsumgebungen (IDEs) zeigen beim Bearbeiten einer JSON-Datei, die Kommentare enthält, Fehler an, da die offizielle JSON-Spezifikation (RFC 7159) keine Kommentare in JSON-Dateien erlaubt. In der Regel können Sie Kommentarfehler und Warnungen ignorieren, sie können jedoch auch Warnungen oder Fehler mit einer Einstellung in der IDE deaktivieren. Fügen Sie beispielsweise in Visual Studio Code der settings.json Datei Folgendes hinzu, um die Fehler zu deaktivieren:

"files.associations": {
  "appsettings*.json": "jsonc"
}

Die vorangehende Einstellung gibt an, dass App-Einstellungsdateien, einschließlich umgebungsbasierter Dateien, dem JSONC-Dateiformat ("JSON mit Kommentaren") zugeordnet sind, das Kommentare unterstützt.

Überprüfen Sie bei anderen IDEs die zugehörige Dokumentation und die Produktsupportkanäle, um herauszufinden, wie Fehler oder Warnungen zu Kommentaren in JSON-Dateien unterdrückt werden können.

Konfigurationsanbieter für Umgebungsvariablen

Der Standardkonfigurationsanbieter für Umgebungsvariablen lädt die Konfiguration aus Umgebungsvariablen, die kein PräfixEnvironmentVariablesConfigurationProvider oder ASPNETCORE_ besitzen. Weitere Informationen zu ASPNETCORE_ Variablen und DOTNET_ Umgebungsvariablen finden Sie im Abschnitt "Standardhostkonfigurationsquellen" und DOTNET_ "Umgebungsvariablen" (.NET Core-Dokumentation).

Bei Verwendung des Standardkonfigurationsanbieters für Umgebungsvariablen lädt die App die Konfiguration aus Umgebungsvariablen-Schlüssel-Wert-Paaren nach dem Lesen von appsettings.json, appsettings.{ENVIRONMENT}.json und Benutzergeheimnissen. Daher überschreiben aus der Umgebung gelesene Schlüsselwerte Werte, die aus appsettings.json, appsettings.{ENVIRONMENT}.json und Benutzergeheimnissen 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, __wird von allen Plattformen unterstützt und automatisch durch einen Doppelpunkt :ersetzt.

Anleitungen zum Festlegen von Umgebungsvariablen in einer Befehlsshell unter Windows oder in einer plattformübergreifenden PowerShell-Befehlsshell finden Sie in den folgenden Ressourcen:

• set (Umgebungsvariable)
• setx
• about_Environment_Variables (PowerShell-Dokumentation)

Benutzerdefiniertes Präfix für Umgebungsvariablen

Sie können einen Konfigurationsanbieter für Umgebungsvariablen mit benutzerdefinierten Präfixen hinzufügen. Rufen Sie in der Program Datei AddEnvironmentVariables mit einer Zeichenfolge auf, um ein Präfix anzugeben, nachdem WebApplication.CreateBuilder aufgerufen wurde. Der Anbieter wird nach den Standardkonfigurationsanbietern hinzugefügt, daher hat der hinzugefügte Anbieter eine höhere Priorität, einschließlich der Umgebungsvariablen desselben Namens ohne das Präfix.

Im folgenden Beispiel werden Umgebungsvariablen mit dem CustomPrefix_ Präfix hinzugefügt:

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

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

Starteinstellungen setzen Umgebungsvariableneinstellungen außer Kraft

Umgebungsvariablen, die in der Datei launchSettings.json festgelegt sind, überschreiben diejenigen, die in der Systemumgebung festgelegt sind. Die ASP.NET Core-Webvorlagen generieren z. B. eine launchSettings.json-Datei, mit der die Endpunktkonfiguration auf Folgendes festgelegt wird:

"applicationUrl": "https://localhost:5001;http://localhost:5000"

Beim Konfigurieren der applicationUrl wird die ASPNETCORE_URLS-Umgebungsvariable festgelegt, und die in der Umgebung festgelegten Werte werden überschrieben.

Umgebungsvariablen unter Linux mit einem Escapezeichen versehen

Unter Linux muss der Wert von URL-Umgebungsvariablen mit einem Escapezeichen versehen werden, damit systemd ihn analysieren kann. Im folgenden Beispiel wird das Linux-Tool systemd-escape verwendet, um http:--localhost:5001 aus http://localhost:5001 zu erzeugen:

groot@terminus:~$ systemd-escape http://localhost:5001
http:--localhost:5001

Azure App Service-App-Einstellungen (Umgebungsvariablen)

Anleitungen für Azure App Service-App-Einstellungen (Umgebungsvariable) finden Sie in den folgenden Ressourcen:

• Konfigurieren einer App Service-App (Azure-Dokumentation)
• Präfixe der Azure-Datenbankverbindungszeichenfolge

Präfixe für Verbindungszeichenfolgen

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

Präfix für Verbindungszeichenfolgen	Provider
APIHUBCONNSTR_	Azure-API-Hubs
CUSTOMCONNSTR_	Benutzerdefinierter Anbieter
DOCDBCONNSTR_	Azure Cosmos DB
EVENTHUBCONNSTR_	Azure Event Hubs
MYSQLCONNSTR_	MySQL
NOTIFICATIONHUBCONNSTR_	Azure Notification Hubs
POSTGRESQLCONNSTR_	PostgreSQL
REDISCACHECONNSTR_	Azure Cache for Redis
SERVICEBUSCONNSTR_	Azure Service Bus
SQLAZURECONNSTR_	Azure SQL-Datenbank
SQLCONNSTR_	SQL Server

Wenn eine Umgebungsvariable erkannt und in die Konfiguration mit einem der erkannten Präfixe geladen wird:

• Der Konfigurationsschlüssel wird durch Entfernen des Umgebungsvariablenpräfixes und Hinzufügen eines Konfigurationsschlüsselabschnitts (ConnectionStrings) erstellt.
• Es wird ein neues Konfigurationsschlüssel-Wert-Paar erstellt, das den Datenbankverbindungsanbieter darstellt, wenn dem Präfix ein Anbietername zugeordnet ist.

Umgebungsvariablenschlüssel	Konvertierter Konfigurationsschlüssel	Anbieterkonfigurationseintrag
APIHUBCONNSTR_{KEY}	ConnectionStrings:{KEY}	Konfigurationseintrag wurde nicht erstellt.
CUSTOMCONNSTR_{KEY}	ConnectionStrings:{KEY}	Konfigurationseintrag wurde nicht erstellt.
DOCDBCONNSTR_{KEY}	ConnectionStrings:{KEY}	Konfigurationseintrag wurde nicht erstellt.
EVENTHUBCONNSTR_{KEY}	ConnectionStrings:{KEY}	Konfigurationseintrag wurde nicht erstellt.
MYSQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Schlüssel: ConnectionStrings:{KEY}_ProviderName: Wert: MySql.Data.MySqlClient
NOTIFICATIONHUBCONNSTR_{KEY}	ConnectionStrings:{KEY}	Konfigurationseintrag wurde nicht erstellt.
POSTGRESQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Schlüssel: ConnectionStrings:{KEY}_ProviderName: Wert: Npgsql
REDISCACHECONNSTR_{KEY}	ConnectionStrings:{KEY}	Konfigurationseintrag wurde nicht erstellt.
SERVICEBUSCONNSTR_{KEY}	ConnectionStrings:{KEY}	Konfigurationseintrag wurde nicht erstellt.
SQLAZURECONNSTR_{KEY}	ConnectionStrings:{KEY}	Schlüssel: ConnectionStrings:{KEY}_ProviderName: Wert: System.Data.SqlClient
SQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Schlüssel: ConnectionStrings:{KEY}_ProviderName: Wert: System.Data.SqlClient

Command-line

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

• appsettings.json- und appsettings.{ENVIRONMENT}.json-Dateien.
• Geheime App-Schlüssel in der Development Umgebung.
• Umgebungsvariablen.

Standardmäßig überschreiben die in der Befehlszeile festgelegten Konfigurationswerte die von allen anderen Konfigurationsanbietern festgelegten Werte.

Befehlszeilenargumente

Mit dem folgenden dotnet run Befehl werden Schlüssel und Werte mit Gleichheitszeichen (=) gesetzt:

dotnet run ConnectionStrings:DefaultConnection="Data Source=LocalSqlServer\\MSSQLDev;" Logging:LogLevel:Default=Information

Mit dem folgenden Befehl werden Schlüssel und Werte mithilfe von Schrägstrichen (/) festgelegt:

dotnet run /ConnectionStrings:DefaultConnection "Data Source=LocalSqlServer\\MSSQLDev;" /Logging:LogLevel:Default Information

Mit den folgenden Befehlen werden Tasten und Werte mit doppelten Gedankenstrichen (--) festgelegt:

dotnet run --ConnectionStrings:DefaultConnection "Data Source=LocalSqlServer\\MSSQLDev;" --Logging:LogLevel:Default Information

Argumentkonventionen:

• Der Schlüsselwert muss dem Gleichheitszeichen (=) entsprechen, oder der Schlüssel muss ein Präfix eines doppelten Gedankenstrichs (--) oder Schrägstrichs (/) aufweisen, wenn der Wert einem Leerzeichen folgt.
• Wenn nach einem Gleichheitszeichen (=) kein Wert zugewiesen wird, wird der Konfigurationseinstellung eine leere Zeichenfolge zugewiesen. Beispielsweise ist die Angabe ConnectionStrings:DefaultConnection= gültig und führt dazu, der Standardverbindungszeichenfolge eine leere Zeichenfolge zuzuweisen.
• Mischen Sie innerhalb desselben Befehls keine Argument-Schlüssel-Wert-Paare, die durch ein Gleichheitszeichen (=) getrennt sind, mit solchen, die durch ein Leerzeichen getrennt sind.

Wechseln von Zuordnungen

Switchmappings ermöglichen die Ersetzung von Schlüssel-Namen mittels eines Wörterbuchs von Switchersetzungen, das an die AddCommandLine-Methode übergeben wird.

Wenn das Schalterzuordnungswörterbuch verwendet wird, wird das Wörterbuch auf einen Schlüssel überprüft, der dem durch ein Befehlszeilenargument angegebenen Schlüssel entspricht. Wenn der Befehlszeilenschlüssel im Wörterbuch gefunden wird, wird der Wörterbuchwert zum Festlegen des Schlüssel-Wert-Paares in der App-Konfiguration zurückgegeben. Ein Switchmapping ist für jeden Befehlszeilenschlüssel erforderlich, dem ein einzelner Gedankenstrich (-) vorangestellt ist.

Schlüsselregeln für Switch-Mappings-Wörterbücher:

• Schalter müssen mit einem einzigen Bindestrich (-) oder einem doppelten Bindestrich (--) beginnen.
• Das Switchmappingwörterbuch darf keine doppelten Schlüssel enthalten.

Im folgenden Beispiel wird ein Switchmappingwörterbuch (switchMappings) an AddCommandLine in der Program-Datei der App übergeben:

var switchMappings = 
    new Dictionary<string, string>(){ { "-k1", "key1" }, { "-k2", "key2" } };

builder.Configuration.AddCommandLine(args, switchMappings);

Die folgenden dotnet run-Befehle veranschaulichen die Schlüsselersetzung (value1 in key1 und value2 in key2):

• dotnet run -k1 value1 -k2 value2
• dotnet run --k1=value1 --k2=value2
• dotnet run --k1 value1 --k2 value2
• dotnet run /k1=value1 /k2=value2
• dotnet run /k1 value1 /k2 value2

Bei Apps, die Switchmappings verwenden, sollten im CreateDefaultBuilder-Aufruf keine Argumente übergeben werden. Der CreateDefaultBuilder-Aufruf der AddCommandLine-Methode umfasst keine zugeordneten Switches, und es gibt keine Möglichkeit, das Switch-Mapping-Wörterbuch an CreateDefaultBuilder zu übergeben. Die Lösung besteht nicht darin, die Argumente an CreateDefaultBuilder weiterzugeben, sondern der Methode ConfigurationBuilder von AddCommandLine zu erlauben, sowohl die Argumente als auch das Switch-Mapping-Wörterbuch zu verarbeiten.

Festlegen von Umgebungs- und Befehlszeilenargumenten mit Visual Studio

Umgebungs- und Befehlszeilenargumente können im Dialogfeld „Startprofile“ in Visual Studio festgelegt werden:

• Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt und dann auf Eigenschaften.
• Klicken Sie auf die Registerkarte Debuggen > Allgemein und dann auf Öffnen der Benutzeroberfläche von Debugstartprofilen.

Dateikonfigurationsanbieter

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

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

INI-Konfigurationsanbieter

Der IniConfigurationProvider lädt die Konfiguration aus INI-Datei-Schlüssel-Wert-Paaren. Im folgenden Beispiel wird die Verwendung des Anbieters veranschaulicht. Überladungen können angeben, ob die Datei optional ist und ob die Konfiguration bei Dateiänderungen neu geladen wird.

IniConfig.ini:

[ConnectionStrings]
DefaultConnection="Data Source=LocalSqlServer\\MSSQLDev;"

[Logging:LogLevel]
Default=Debug
Microsoft=Debug

IniConfig.Production.ini:

[ConnectionStrings]
DefaultConnection="Data Source=LocalSqlServer\\MSSQLProd;"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Laden Sie die Konfiguration, indem Sie AddIniFile aufrufen. Im folgenden Beispiel wird für jede der vorherigen Dateien eine Konfigurationsquelle erstellt. Die Nicht-Umgebungsdatei lädt die Konfiguration neu, wenn die Datei geändert wird (reloadOnChange Parameter, Standard: false). Die Umgebungsversion der Datei gibt an, dass die Datei optional ist (optional Parameter, Standard: false). Wenn Sie angeben möchten, dass die Datei bei Änderung neu geladen wird (reloadOnChange: true), müssen Sie auch angeben, ob die Datei optionaloptional () ist.

builder.Configuration
    .AddIniFile("IniConfig.ini", optional: false, reloadOnChange: true);
    .AddIniFile($"IniConfig.{builder.Environment.EnvironmentName}.ini", optional: true);

JSON-Konfigurationsanbieter

Der JsonConfigurationProvider lädt die Konfiguration aus den Schlüssel-Wert-Paaren der JSON-Datei. Im folgenden Beispiel wird die Verwendung des Anbieters veranschaulicht. Überladungen können angeben, ob die Datei optional ist und ob die Konfiguration bei Dateiänderungen neu geladen wird.

Rufen Sie AddJsonFile mit dem Dateipfad (oder dem Dateinamen, wenn sich die Datei im Stammverzeichnis der App befindet) auf. Im Folgenden wird die Datei optional (optional Parameter, Standard: false) und gibt an, dass die Konfiguration neu geladen wird, wenn die Datei geändert wird (reloadOnChange Parameter, Standard: false). Wenn Sie angeben möchten, dass die Datei bei Änderung neu geladen wird (reloadOnChange: true), müssen Sie auch angeben, ob die Datei optionaloptional () ist.

builder.Configuration.AddJsonFile("config.json", optional: true, reloadOnChange: true);

XML-Konfigurationsanbieter

XmlConfigurationProvider lädt die Konfiguration aus Schlüssel-Wert-Paaren der XML-Datei. Im folgenden Beispiel wird die Verwendung des Anbieters veranschaulicht. Überladungen können angeben, ob die Datei optional ist und ob die Konfiguration bei Dateiänderungen neu geladen wird.

XmlFile.xml:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <ConnectionStrings>
    <DefaultConnection>Data Source=LocalSqlServer\\MSSQLDev;</DefaultConnectionString>
  </ConnectionStrings>
  <Logging>
    <LogLevel>
      <Default>Debug</Default>
      <Microsoft>Debug</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

XmlFile.Production.xml:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <ConnectionStrings>
    <DefaultConnectionString>Data Source=LocalSqlServer\\MSSQLProd;</DefaultConnectionString>
  </ConnectionStrings>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

Laden Sie die Konfiguration, indem Sie AddXmlFile aufrufen. Im folgenden Beispiel wird für jede der vorherigen Dateien eine Konfigurationsquelle erstellt. Die Nicht-Umgebungsdatei lädt die Konfiguration neu, wenn die Datei geändert wird (reloadOnChange Parameter, Standard: false). Die Umgebungsversion der Datei gibt an, dass die Datei optional ist (optional Parameter, Standard: false). Wenn Sie angeben möchten, dass die Datei bei Änderung neu geladen wird (reloadOnChange: true), müssen Sie auch angeben, ob die Datei optionaloptional () ist.

builder.Configuration
    .AddXmlFile("XmlFile.xml", optional: false, reloadOnChange: true);
    .AddXmlFile($"XmlFile.{builder.Environment.EnvironmentName}.xml", optional: true);

Wiederholte Elemente mit den gleichen Elementnamen funktionieren, wenn das name-Attribut zur Unterscheidung der Elemente verwendet wird:

<?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>

var value_00 = Config["section:section0:key:key0"];
var value_01 = Config["section:section0:key:key1"];
var value_10 = Config["section:section1:key:key0"];
var value_11 = Config["section:section1:key:key1"];

Attribute, die Werte angeben, werden unterstützt:

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

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

• key:attribute
• section:key:attribute

Schlüssel-Pro-Datei-Konfigurationsanbieter

KeyPerFileConfigurationProvider verwendet Verzeichnisdateien als Konfigurations-Schlüssel-Wert-Paare. Der Schlüssel ist der Dateiname. Der Wert enthält den Inhalt der Datei. Der Schlüssel-Per-File Konfigurationsanbieter wird in Docker-Hostingszenarien 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 erlauben das Angeben von:

• 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.

var path = Path.Combine(Directory.GetCurrentDirectory(), "path/to/files");
builder.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:

var configSettings = new Dictionary<string, string>
{
    { "ConnectionStrings:DefaultConnection", "Data Source=LocalSqlServer\\MSSQLDev;" },
    { "Logging:LogLevel:Default", "Information" }
};

builder.Configuration.AddInMemoryCollection(configSettings);

Kestrel-Endpunktkonfiguration

Kestrel-spezifische Endpunktkonfiguration setzt alle serverübergreifenden Endpunktkonfigurationen außer Kraft. Serverübergreifende Endpunktkonfigurationen umfassen Folgendes:

• UseUrls.
• --urls auf der Befehlszeile.
• Die ASPNETCORE_URLS.

Betrachten Sie den folgenden Kestrel Konfigurationsabschnitt in einer appsettings.json Datei:

"Kestrel": {
  "Endpoints": {
    "Https": {
      "Url": "https://localhost:9999"
    }
  }
},

Die App wird in der Befehlszeile mit dotnet run und der folgenden serverübergreifenden Endpunktkonfiguration gestartet:

dotnet run --urls="https://localhost:7777"

Kestrel bindet an den Endpunkt, der speziell für Kestrel im appsettings.json-Datei konfiguriert ist, und nicht an die serverübergreifende Endpunktkonfiguration, die an den Befehl https://localhost:9999 (dotnet run) übergeben wird.https://localhost:7777

Berücksichtigen Sie jedoch den Kestrel-spezifischen Endpunkt, der als Umgebungsvariable konfiguriert ist.

• Schlüssel: Kestrel__Endpoints__Https__Url
• Wert: https://localhost:8888

In der vorherigen Umgebungsvariable ist "Https" der Name des Kestrel-spezifischen Endpunkts. Die konfiguration der vorherigen App-Einstellungen definiert auch einen Kestrel-spezifischen Endpunkt namens Https. Gemäß den standardmäßigen Hostkonfigurationsanbietern werden die Umgebungsvariablen, die vom Konfigurationsanbieter für Umgebungsvariablen gelesen werden, nach appsettings.{ENVIRONMENT}.json gelesen. Daher wird die vorangehende Umgebungsvariable (Kestrel__Endpoints__Https__Url) für den Https Endpunkt verwendet.

Extrahieren eines einzelnen Werts aus der Konfiguration mit Typkonvertierung (GetValue)

ConfigurationBinder.GetValue extrahiert einen Einzelwert aus der Konfiguration mit einem angegebenen Schlüssel und konvertiert ihn in den angegebenen Typ:

var number = Config.GetValue<int>("NumberKey", 99);

Im vorhergehenden Code:

• Config ist ein eingefügter IConfiguration.
• Wenn NumberKey in der Konfiguration nicht gefunden wird, wird der Standardwert 99 verwendet.

Arbeiten mit Abschnitten, Abrufen der Unterabschnitte eines Abschnitts und Überprüfen, ob ein Abschnitt existiert

Betrachten Sie für die folgenden Beispiele die subsection.json-Datei unten:

{
  "section0": {
    "key0": "value00",
    "key1": "value01"
  },
  "section1": {
    "key0": "value10",
    "key1": "value11"
  },
  "section2": {
    "subsection0": {
      "key0": "value200",
      "key1": "value201"
    },
    "subsection1": {
      "key0": "value210",
      "key1": "value211"
    }
  }
}

Ein Konfigurationsanbieter wird für subsection.json durch Aufrufen von AddJsonFile hinzugefügt.

GetSection

IConfiguration.GetSection gibt einen Konfigurationsunterabschnitt mit dem angegebenen Unterabschnittsschlüssel zurück.

Der folgende Code gibt Werte für section1, wobei Config ein eingefügter IConfigurationWert ist:

var subsection = Config.GetSection("section1");
var value1 = subsection["key0"];
var value2 = subsection["key1"];

Der folgende Code gibt Werte für section2:subsection0, wobei Config ein eingefügter IConfigurationWert ist:

var subsection = Config.GetSection("section2:subsection0");
var value1 = subsection["key0"];
var value2 = subsection["key1"];

GetSection gibt nie null zurück. Wenn kein entsprechender Abschnitt gefunden wird, wird ein leeres IConfigurationSection-Element zurückgegeben.

Wenn GetSection einen entsprechenden Abschnitt zurückgibt, wird Value nicht aufgefüllt. Key und Path werden zurückgegeben, wenn der Abschnitt vorhanden ist.

GetChildren und Exists

Der folgende Code ruft auf:

• ConfigurationExtensions.Exists um zu überprüfen, ob section2 vorhanden ist.
• IConfiguration.GetChildren und gibt Werte für die Unterabschnitte von section2.

var section = Config.GetSection("section2");

if (!section.Exists())
{
    throw new Exception("section2 doesn't exist!");
}

var children = section.GetChildren();

foreach (var subSection in children)
{
    int i = 0;
    var key1 = subSection.Key + ":key" + i++.ToString();
    var key2 = subSection.Key + ":key" + i.ToString();
    Console.WriteLine($"{key1} value: {section[key1]}");
    Console.WriteLine($"{key2} value: {section[key2]}");
}

Ausgabe:

subsection0:key0 value: value200
subsection0:key1 value: value201
subsection1:key0 value: value210
subsection1:key1 value: value211

Binden eines Arrays

ConfigurationBinder.Bind unterstützt das Binden von Arrays an Objekte mit Arrayindizes in Konfigurationsschlüsseln. Jedes Arrayformat, das ein numerisches Schlüsselsegment verfügbar macht, kann ein Array an ein POCO-Klassenarray binden.

array.json:

{
  "array": {
    "entries": {
      "0": "value00",
      "1": "value10",
      "2": "value20",
      "4": "value40",
      "5": "value50"
    }
  }
}

Ein Konfigurationsanbieter wird für array.json durch Aufrufen von AddJsonFile hinzugefügt.

Der folgende Code liest die Konfigurationswerte.

ArrayExample.cs:

public class ArrayExample
{
    public string[]? Entries { get; set; } 
}

var array = Config.GetSection("array").Get<ArrayExample>();

if (array is null)
{
    throw new ArgumentNullException(nameof(array));
}

for (int j = 0; j < array.Entries?.Length; j++)
{
    Console.WriteLine($"Index: {j} Value: {array.Entries[j]}");
}

Ausgabe:

Index: 0 Value: value00
Index: 1 Value: value10
Index: 2 Value: value20
Index: 3 Value: value40
Index: 4 Value: value50

In der obigen Ausgabe hat Index 3 den Wert value40, der "4": "value40", in array.json entspricht. Die gebundenen Arrayindizes sind kontinuierlich und nicht an den Konfigurationsschlüsselindex gebunden. Der Konfigurationsordner ist nicht in der Lage, Werte zu binden null oder Einträge in gebundenen Objekten zu erstellen null .

Das fehlende Konfigurationselement für Index 3 kann vor der Bindung an die ArrayExample Instanz durch einen beliebigen Konfigurationsanbieter bereitgestellt werden, der das Index 3-Schlüssel-Wert-Paar liest. Gehen Sie im folgenden Beispiel davon aus, dass die im vorherigen Beispiel bereitgestellten array.json Werte von einer In-Memory-Auflistung bereitgestellt werden. Das Beispiel zeigt, wie der Index 3-Wert aus dem JSON-Konfigurationsanbieter geladen wird, bevor die Sammlung gebunden wird.

value3.json:

{
  "array:entries:3": "value30"
}

var configSettings = new Dictionary<string, string>
{
    { "array:entries:0", "value00" },
    { "array:entries:1", "value10" },
    { "array:entries:2", "value20" },
    { "array:entries:4", "value40" },
    { "array:entries:5", "value50" }
};

builder.Configuration.AddInMemoryCollection(configSettings);
builder.Configuration.AddJsonFile("value3.json", optional: false, 
    reloadOnChange: false);

Der vorangehende Code führt zu folgendem gebundenen Array:

Index: 0 Value: value00
Index: 1 Value: value10
Index: 2 Value: value20
Index: 3 Value: value30
Index: 4 Value: value40
Index: 5 Value: value50

Benutzerdefinierter Konfigurationsanbieter

Die Beispiel-App veranschaulicht, wie ein Standardkonfigurationsanbieter erstellt wird, der Konfigurations-Schlüssel-Wert-Paare aus einer Datenbank mit Entity Framework (EF) liest.

Der Anbieter weist die folgenden Merkmale auf:

• Die EF-In-Memory-Datenbank wird zu Demonstrationszwecken verwendet. Um eine Datenbank zu verwenden, die eine Verbindungszeichenfolge benötigt, implementieren Sie einen sekundären ConfigurationBuilder, um die Verbindungszeichenfolge aus einem anderen Konfigurationsanbieter anzugeben.
• Der Anbieter liest eine Datenbanktabelle beim Start in die Konfiguration ein. Der Anbieter fragt die Datenbank nicht pro Schlüssel ab.
• Das erneute Laden bei Änderung ist nicht implementiert. Das heißt, das Aktualisieren der Datenbank nach App-Start hat keine Auswirkungen auf die App-Konfiguration.

Definieren Sie eine EFConfigurationValue-Entität zum Speichern von Konfigurationswerten in der Datenbank.

Models/EFConfigurationValue.cs:

public class EFConfigurationValue
{
    public string Id { get; set; } = string.Empty;
    public string Value { get; set; } = string.Empty;
}

Fügen Sie EFConfigurationContext hinzu, um die konfigurierten Werte zu speichern und auf diese zugreifen.

EFConfigurationProvider/EFConfigurationContext.cs:

public class EFConfigurationContext : DbContext
{
    public EFConfigurationContext(
        DbContextOptions<EFConfigurationContext> options) : base(options)
    {
    }

    public DbSet<EFConfigurationValue> Values => Set<EFConfigurationValue>();
}

Erstellen Sie eine Klasse, die das IConfigurationSource implementiert.

EFConfigurationProvider/EFConfigurationSource.cs:

public class EFConfigurationSource : IConfigurationSource
{
    private readonly Action<DbContextOptionsBuilder> _optionsAction;

    public EFConfigurationSource(Action<DbContextOptionsBuilder> optionsAction) => 
        _optionsAction = optionsAction;

    public IConfigurationProvider Build(IConfigurationBuilder builder) => 
        new EFConfigurationProvider(_optionsAction);
}

Erstellen Sie den benutzerdefinierten Konfigurationsanbieter, indem Sie von ConfigurationProvider erben. Der Konfigurationsanbieter initialisiert die Datenbank, wenn diese leer ist. Da bei Konfigurationsschlüsseln die Groß-/Kleinschreibung keine Rolle spielt, wird das zur Initialisierung der Datenbank verwendete Wörterbuch mit einer Vergleichsfunktion erstellt, die die Groß-/Kleinschreibung ignoriert (StringComparer.OrdinalIgnoreCase).

EFConfigurationProvider/EFConfigurationProvider.cs:

using Microsoft.EntityFrameworkCore;

public class EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction) : ConfigurationProvider
{
    public override void Load()
    {
        var builder = new DbContextOptionsBuilder<EFConfigurationContext>();

        optionsAction(builder);

        using var dbContext = new EFConfigurationContext(builder.Options);

        if (dbContext == null || dbContext.Values == null)
        {
            throw new Exception("Null DB context");
        }

        dbContext.Database.EnsureCreated();

        Data = !dbContext.Values.Any()
            ? CreateAndSaveDefaultValues(dbContext)
            : dbContext.Values.ToDictionary(c => c.Id, c => c.Value);
    }

    private static Dictionary<string, string> CreateAndSaveDefaultValues(
        EFConfigurationContext dbContext)
    {
        // Quotes (c)2005 Universal Pictures: Serenity
        // https://www.uphe.com/movies/serenity-2005
        var configValues =
            new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
            {
                { "quote1", "I aim to misbehave." },
                { "quote2", "I swallowed a bug." },
                { "quote3", "You can't stop the signal, Mal." }
            };

        if (dbContext == null || dbContext.Values == null)
        {
            throw new Exception("Null DB context");
        }

        dbContext.Values.AddRange(configValues
            .Select(kvp => new EFConfigurationValue
            {
                Id = kvp.Key,
                Value = kvp.Value
            })
            .ToArray());

        dbContext.SaveChanges();

        return configValues;
    }
}

Durch eine AddEFConfiguration-Erweiterungsmethode kann eine Konfigurationsquelle zu einem ConfigurationBuilder hinzugefügt werden.

Extensions/EntityFrameworkExtensions.cs:

public static class EntityFrameworkExtensions
{
    public static IConfigurationBuilder AddEFConfiguration(
        this IConfigurationBuilder builder,
        Action<DbContextOptionsBuilder> optionsAction)
    {
        return builder.Add(new EFConfigurationSource(optionsAction));
    }
}

Der folgende Code zeigt, wie Sie den benutzerdefinierten EFConfigurationProvider in der Datei der App Program verwenden:

builder.Configuration.AddEFConfiguration(
    opt => opt.UseInMemoryDatabase("InMemoryDb"));

Ein Beispiel für den Zugriff auf die Konfiguration mit den Starthilfsmethoden finden Sie unter Anwendungsstart: Hilfsmethoden.

Hinzufügen von Konfigurationen aus einer externen Assembly

Eine IHostingStartup-Implementierung ermöglicht das Hinzufügen von Erweiterungen zu einer App beim Start von einer externen Assembly außerhalb der Startup-Klasse der App aus. Weitere Informationen finden Sie unter Verwenden von Hostingstartassemblys in ASP.NET Core.

Quell-Generator für Konfigurationsbindung

Der Konfigurationsbindungsquellengenerator bietet AOT und eine trimfreundliche Konfiguration. Weitere Informationen finden Sie unter Konfigurationsbindungsquellengenerator.

Weitere Ressourcen

• ASP.NET Core Blazor-Konfiguration
• Quellcode der Konfiguration
• Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)
• Optionsmuster in ASP.NET Core