Teilen über

Konfiguration in .NET

Die Konfiguration in .NET wird mit einem oder mehreren Konfigurationsanbietern ausgeführt. Konfigurationsanbieter lesen Konfigurationsdaten aus Schlüsselwertpaaren mithilfe verschiedener Konfigurationsquellen:

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

Hinweis

Informationen zum Konfigurieren der .NET-Runtime selbst finden Sie unter .NET-Runtime-Konfigurationseinstellungen.

Konzepte und Abstraktionen

Angesichts einer oder mehrerer Konfigurationsquellen stellt der IConfiguration Typ eine einheitliche Ansicht der Konfigurationsdaten bereit. Die Konfiguration ist schreibgeschützt, und das Konfigurationsmuster ist nicht für die programmatische Schreibbarkeit ausgelegt. Die IConfiguration Schnittstelle ist eine einzelne Darstellung aller Konfigurationsquellen, wie im folgenden Diagramm dargestellt:

Die Schnittstelle

Konfigurieren von Konsolen-Apps

.NET-Konsolenanwendungen, die mit der neuen Dotnet-Befehlsvorlage oder Visual Studio erstellt wurden, machen standardmäßig keine Konfigurationsfunktionen verfügbar. Um eine Konfiguration in einer neuen .NET-Konsolenanwendung hinzuzufügen, fügen Sie einen Paketverweis aufMicrosoft.Extensions.Configuration hinzu. Dieses Paket ist die Grundlage für die Konfiguration in .NET-Apps. Sie bietet die ConfigurationBuilder und verwandte Typen an.

using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string?>()
    {
        ["SomeKey"] = "SomeValue"
    })
    .Build();

Console.WriteLine(configuration["SomeKey"]);

// Outputs:
//   SomeValue

Der vorherige Code:

  • Erstellt eine neue ConfigurationBuilder-Instanz.
  • Fügt dem Konfigurations-Generator eine Speicherauflistung von Schlüssel-Wert-Paaren hinzu.
  • Ruft die Build() Methode auf, um eine IConfiguration Instanz zu erstellen.
  • Schreibt den Wert des SomeKey Schlüssels in die Konsole.

In diesem Beispiel wird zwar eine In-Memory-Konfiguration verwendet, es stehen jedoch viele Konfigurationsanbieter zur Verfügung, die Funktionen für dateibasierte Konfigurationen, Umgebungsvariablen, Befehlszeilenargumente und andere Konfigurationsquellen bereitstellen. Weitere Informationen finden Sie unter Konfigurationsanbieter in .NET.

Alternativer Hostingansatz

Häufig erledigen Ihre Apps mehr als nur die Lesekonfiguration. Sie werden wahrscheinlich Abhängigkeitseinfügungen, Protokollierung und andere Dienste verwenden. Der .NET Generic Host-Ansatz wird für Apps empfohlen, die diese Dienste verwenden. Erwägen Sie stattdessen das Hinzufügen eines Paketverweises zu "Microsoft.Extensions.Hosting". Ändern Sie die Program.cs Datei so, dass sie dem folgenden Code entspricht:

using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Application code should start here.

await host.RunAsync();

Die Host.CreateApplicationBuilder(String[]) Methode stellt die Standardkonfiguration für die App in der folgenden Reihenfolge bereit, von der höchsten bis zur niedrigsten Priorität:

  1. Befehlszeilenargumente, die den Befehlszeilen-Konfigurationsanbieter verwenden
  2. Umgebungsvariablen, die den Umgebungsvariablen-Konfigurationsanbieter verwenden
  3. Geheime App-Schlüssel , wenn die App in der Development Umgebung ausgeführt wird.
  4. appsettings.Environment.json mit dem JSON-Konfigurationsanbieter. Beispiel: Appsettings. Produktion. json und appsettings. Entwicklung. json.
  5. appsettings.json mithilfe des JSON-Konfigurationsanbieters.
  6. ChainedConfigurationProvider : Fügt eine vorhandene IConfiguration als Quelle hinzu.

Durch Hinzufügen eines Konfigurationsanbieters werden vorherige Konfigurationswerte außer Kraft gesetzt. Beispielsweise überschreibt der Befehlszeilenkonfigurationsanbieter alle Werte anderer Anbieter, da er zuletzt hinzugefügt wurde. Wenn SomeKey sowohl in appsettings.json als auch in der Umgebung festgelegt wird, wird der Umgebungswert verwendet, da er nach appsettings.jsonhinzugefügt wurde.

Binding

Einer der wichtigsten Vorteile der Verwendung der .NET-Konfigurationsabstraktionen ist die Möglichkeit, Konfigurationswerte an Instanzen von .NET-Objekten zu binden. Beispielsweise kann der JSON-Konfigurationsanbieter verwendet werden, um appsettings.json-Dateien .NET-Objekten zuzuordnen und wird mit der Abhängigkeitsinjektion verwendet. Dies ermöglicht das Optionsmuster, das Klassen verwendet, um stark typierten Zugriff auf Gruppen verwandter Einstellungen zu ermöglichen. Der Standard-Binder ist reflektionsbasiert, aber es gibt eine Quellgenerator-Alternative, die einfach zu aktivieren ist.

.NET-Konfiguration bietet verschiedene Abstraktionen. Berücksichtigen Sie die folgenden Schnittstellen:

  • IConfiguration: Stellt eine Reihe von Konfigurationseigenschaften für Schlüssel/Wert-Anwendungen dar.
  • IConfigurationRoot: Stellt den Stamm einer IConfiguration Hierarchie dar.
  • IConfigurationSection: Stellt einen Abschnitt mit Anwendungskonfigurationswerten dar.

Diese Abstraktionen sind agnostisch für ihren zugrunde liegenden Konfigurationsanbieter (IConfigurationProvider). Mit anderen Worten, Sie können eine IConfiguration Instanz verwenden, um auf einen beliebigen Konfigurationswert von mehreren Anbietern zuzugreifen.

Der Binder kann verschiedene Ansätze verwenden, um Konfigurationswerte zu verarbeiten.

  • Direkte Deserialisierung (mit integrierten Konvertern) für primitive Typen.
  • Der TypeConverter für einen komplexen Typ, wenn der Typ einen hat.
  • Spiegelung eines komplexen Typs mit Eigenschaften.

Hinweis

Der Ordner hat einige Einschränkungen:

  • Eigenschaften werden ignoriert, wenn sie private Setter haben oder deren Typ nicht konvertiert werden kann.
  • Eigenschaften ohne entsprechende Konfigurationsschlüssel werden ignoriert.

Binden von Hierarchien

Konfigurationswerte können hierarchische Daten enthalten. Hierarchische Objekte werden mit der Verwendung des : Trennzeichens in den Konfigurationsschlüsseln dargestellt. Um auf einen Konfigurationswert zuzugreifen, verwenden Sie das : Zeichen, um eine Hierarchie zu trennen. Betrachten Sie beispielsweise die folgenden Konfigurationswerte:

{
  "Parent": {
    "FavoriteNumber": 7,
    "Child": {
      "Name": "Example",
      "GrandChild": {
        "Age": 3
      }
    }
  }
}

Die folgende Tabelle stellt Beispielschlüssel und die entsprechenden Werte für das vorangehende BEISPIEL-JSON dar:

Key Wert
"Parent:FavoriteNumber" 7
"Parent:Child:Name" "Example"
"Parent:Child:GrandChild:Age" 3

Einfaches Beispiel

Verwenden Sie den Typ direkt, um auf Konfigurationswerte in der grundlegenden Form zuzugreifen, ohne dass der ConfigurationBuilder unterstützt wird.

Tipp

Der System.Configuration.ConfigurationBuilder Typ unterscheidet sich vom Microsoft.Extensions.Configuration.ConfigurationBuilder Typ. All diese Inhalte sind spezifisch für die Microsoft.Extensions.* NuGet-Pakete und Namespaces.

Betrachten Sie das folgende C#-Projekt:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="appsettings.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.1" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.1" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.1" />
  </ItemGroup>

</Project>

Die vorherige Projektdatei verweist auf mehrere Konfigurations-NuGet-Pakete:

Betrachten Sie ein Beispiel appsettings.json Datei:

{
    "Settings": {
        "KeyOne": 1,
        "KeyTwo": true,
        "KeyThree": {
            "Message": "Oh, that's nice...",
            "SupportedVersions": {
                "v1": "1.0.0",
                "v3": "3.0.7"
            }
        },
        "IPAddressRange": [
            "46.36.198.121",
            "46.36.198.122",
            "46.36.198.123",
            "46.36.198.124",
            "46.36.198.125"
        ]
    }
}

In Anbetracht dieser JSON-Datei finden Sie nun ein Beispiel für ein Verbrauchsmuster, das den Konfigurations-Generator direkt verwendet:

using Microsoft.Extensions.Configuration;

// Build a config object, using env vars and JSON providers.
IConfigurationRoot config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddEnvironmentVariables()
    .Build();

// Get values from the config given their key and their target type.
Settings? settings = config.GetRequiredSection("Settings").Get<Settings>();

// Write the values to the console.
Console.WriteLine($"KeyOne = {settings?.KeyOne}");
Console.WriteLine($"KeyTwo = {settings?.KeyTwo}");
Console.WriteLine($"KeyThree:Message = {settings?.KeyThree?.Message}");

// Application code which might rely on the config could start here.

// This will output the following:
//   KeyOne = 1
//   KeyTwo = True
//   KeyThree:Message = Oh, that's nice...

Der vorhergehende C#-Code:

  • Instanziiert ein ConfigurationBuilder.
  • Fügt die "appsettings.json" Datei hinzu, die vom JSON-Konfigurationsanbieter erkannt wird.
  • Fügt Umgebungsvariablen hinzu, die vom Konfigurationsanbieter für Umgebungsvariablen erkannt werden.
  • Ruft den erforderlichen "Settings" Abschnitt und die entsprechende Settings Instanz mithilfe der config Instanz ab.

Das Settings Objekt wird wie folgt geformt:

public sealed class Settings
{
    public required int KeyOne { get; set; }
    public required bool KeyTwo { get; set; }
    public required NestedSettings KeyThree { get; set; } = null!;
}

public sealed class NestedSettings
{
    public required string Message { get; set; } = null!;
}

Einfaches Beispiel mit Hosting

Um auf den IConfiguration Wert zuzugreifen, können Sie sich erneut auf das Microsoft.Extensions.Hosting NuGet-Paket verlassen. Erstellen Sie eine neue Konsolenanwendung, und fügen Sie den folgenden Projektdateiinhalt in sie ein:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="appsettings.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.1" />
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="10.0.1" />
  </ItemGroup>

</Project>

Die vorherige Projektdatei definiert Folgendes:

  • Die Anwendung ist eine ausführbare Datei.
  • Eine appsettings.json Datei soll beim Kompilieren des Projekts in das Ausgabeverzeichnis kopiert werden.
  • Der Microsoft.Extensions.Hosting NuGet-Paketverweis wird hinzugefügt.

Fügen Sie die appsettings.json Datei im Stammverzeichnis des Projekts mit dem folgenden Inhalt hinzu:

{
    "KeyOne": 1,
    "KeyTwo": true,
    "KeyThree": {
        "Message": "Thanks for checking this out!"
    }
}

Ersetzen Sie den Inhalt der Program.cs-Datei durch den folgenden C#-Code:

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

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Ask the service provider for the configuration abstraction.
IConfiguration config = host.Services.GetRequiredService<IConfiguration>();

// Get values from the config given their key and their target type.
int keyOneValue = config.GetValue<int>("KeyOne");
bool keyTwoValue = config.GetValue<bool>("KeyTwo");
string? keyThreeNestedValue = config.GetValue<string>("KeyThree:Message");

// Write the values to the console.
Console.WriteLine($"KeyOne = {keyOneValue}");
Console.WriteLine($"KeyTwo = {keyTwoValue}");
Console.WriteLine($"KeyThree:Message = {keyThreeNestedValue}");

// Application code which might rely on the config could start here.

await host.RunAsync();

// This will output the following:
//   KeyOne = 1
//   KeyTwo = True
//   KeyThree:Message = Thanks for checking this out!

Wenn Sie diese Anwendung ausführen, definiert das Host.CreateApplicationBuilder Verhalten, um die JSON-Konfiguration zu ermitteln und über die IConfiguration Instanz verfügbar zu machen. Aus der host Instanz können Sie den Dienstanbieter nach der IConfiguration Instanz fragen und dann nach Werten fragen.

Tipp

Die Verwendung der rohen IConfiguration Instanz auf diese Weise ist zwar praktisch, wird jedoch nicht sehr gut skaliert. Wenn Anwendungen komplexer werden und die entsprechenden Konfigurationen komplexer werden, empfiehlt es sich, das Optionsmuster als Alternative zu verwenden.

Grundlegendes Beispiel zum Hosten und Verwenden der Indexer-API

Betrachten Sie den gleichen appsettings.json Dateiinhalt aus dem vorherigen Beispiel:

{
    "SupportedVersions": {
        "v1": "1.0.0",
        "v3": "3.0.7"
    },
    "IPAddressRange": [
        "46.36.198.123",
        "46.36.198.124",
        "46.36.198.125"
    ]
}

Ersetzen Sie den Inhalt der Program.cs-Datei durch den folgenden C#-Code:

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

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Ask the service provider for the configuration abstraction.
IConfiguration config = host.Services.GetRequiredService<IConfiguration>();

// Get values from the config given their key and their target type.
string? ipOne = config["IPAddressRange:0"];
string? ipTwo = config["IPAddressRange:1"];
string? ipThree = config["IPAddressRange:2"];
string? versionOne = config["SupportedVersions:v1"];
string? versionThree = config["SupportedVersions:v3"];

// Write the values to the console.
Console.WriteLine($"IPAddressRange:0 = {ipOne}");
Console.WriteLine($"IPAddressRange:1 = {ipTwo}");
Console.WriteLine($"IPAddressRange:2 = {ipThree}");
Console.WriteLine($"SupportedVersions:v1 = {versionOne}");
Console.WriteLine($"SupportedVersions:v3 = {versionThree}");

// Application code which might rely on the config could start here.

await host.RunAsync();

// This will output the following:
//     IPAddressRange:0 = 46.36.198.123
//     IPAddressRange:1 = 46.36.198.124
//     IPAddressRange:2 = 46.36.198.125
//     SupportedVersions:v1 = 1.0.0
//     SupportedVersions:v3 = 3.0.7

Auf die Werte wird mithilfe der Indexer-API zugegriffen, wobei jeder Schlüssel eine Zeichenfolge ist und der Wert eine Zeichenfolge ist. Die Konfiguration unterstützt Eigenschaften, Objekte, Arrays und Wörterbücher.

Konfigurationsanbieter

In der folgenden Tabelle sind die Für .NET Core-Apps verfügbaren Konfigurationsanbieter aufgeführt.

Provider Bereitstellung der Konfiguration über
Azure-App-Konfigurationsanbieter Azure App-Konfiguration
Azure Key Vault-Konfigurationsanbieter Azure Key Vault (ein Dienst zur sicheren Verwaltung kryptografischer Schlüssel)
Befehlszeilen-Konfigurationsanbieter Befehlszeilenparameter
Benutzerdefinierter Konfigurationsanbieter Benutzerdefinierte Quelle
Umgebungsvariablen-Konfigurationsanbieter Umgebungsvariablen
Dateikonfigurationsanbieter JSON-, XML- und INI-Dateien
Schlüssel-pro-Datei-Konfigurationsanbieter Verzeichnisdateien
Speicherkonfigurationsanbieter In-Memory-Sammlungen
Geheime App-Schlüssel (Geheimer Manager) Datei im Benutzerprofilverzeichnis

Tipp

Die Reihenfolge, in der Konfigurationsanbieter hinzugefügt werden, ist wichtig. Wenn mehrere Konfigurationsanbieter verwendet werden und mehrere Anbieter denselben Schlüssel angeben, wird der zuletzt hinzugefügte Verwendet.

Weitere Informationen zu verschiedenen Konfigurationsanbietern finden Sie unter Konfigurationsanbieter in .NET.

Siehe auch

  • Last updated on