Konfiguration in ASP.NET CoreConfiguration in ASP.NET Core

Von Rick Anderson und Kirk LarkinBy Rick Anderson and Kirk Larkin

Die Konfiguration in ASP.NET Core erfolgt mithilfe eines oder mehrerer Konfigurationsanbieter.Configuration in ASP.NET Core is performed using one or more configuration providers. Konfigurationsanbieter lesen Konfigurationsdaten aus Schlüssel-Wert-Paaren unter Verwendung verschiedener Konfigurationsquellen:Configuration providers read configuration data from key-value pairs using a variety of configuration sources:

  • Einstellungsdateien, z. B. appsettings.jsonSettings files, such as appsettings.json
  • UmgebungsvariablenEnvironment variables
  • Azure Key VaultAzure Key Vault
  • Azure App ConfigurationAzure App Configuration
  • BefehlszeilenargumenteCommand-line arguments
  • Benutzerdefinierte Anbieter (installiert oder erstellt)Custom providers, installed or created
  • VerzeichnisdateienDirectory files
  • Speicherinterne .NET ObjekteIn-memory .NET objects

Dieses Thema enthält Informationen zur Konfiguration in ASP.NET Core.This topic provides information on configuration in ASP.NET Core. Informationen zur Verwendung der Konfiguration in Konsolen-Apps finden Sie unter .NET-Konfiguration.For information on using configuration in console apps, see .NET Configuration.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)View or download sample code (how to download)

StandardkonfigurationDefault configuration

ASP.NET Core-Web-Apps, die mit dotnet new oder Visual Studio erstellt wurden, generieren den folgenden Code:ASP.NET Core web apps created with dotnet new or Visual Studio generate the following code:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

CreateDefaultBuilder legt die Standardkonfiguration für die App in der folgenden Reihenfolge fest:CreateDefaultBuilder provides default configuration for the app in the following order:

  1. ChainedConfigurationProvider: Fügt eine vorhandene IConfiguration als Quelle hinzu.ChainedConfigurationProvider : Adds an existing IConfiguration as a source. Im Fall einer Standardkonfiguration wird die Host-Konfiguration hinzugefügt und als erste Quelle für die App- Konfiguration festgelegt.In the default configuration case, adds the host configuration and setting it as the first source for the app configuration.
  2. appsettings.json mithilfe des JSON-Konfigurationsanbietersappsettings.json using the JSON configuration provider.
  3. appsettings. Environment .json mithilfe des JSON-Konfigurationsanbieters.appsettings.Environment.json using the JSON configuration provider. Beispielsweise appsettings.Production**_._json and appsettings.***Development _.json*.For example, appsettings.***Production**._json* and appsettings.***Development** _._json*.
  4. App-Geheimnisse, wenn die App in der Development-Umgebung ausgeführt wirdApp secrets when the app runs in the Development environment.
  5. Umgebungsvariablen, die den Umgebungsvariablen-Konfigurationsanbieter verwendenEnvironment variables using the Environment Variables configuration provider.
  6. Befehlszeilenargumente, die den Befehlszeilen-Konfigurationsanbieter verwendenCommand-line arguments using the Command-line configuration provider.

Später hinzugefügte Konfigurationsanbieter überschreiben vorherige Schlüsseleinstellungen.Configuration providers that are added later override previous key settings. Wenn beispielsweise MyKey sowohl unter appsettings.json als auch unter Umgebung festgelegt wird, wird der Umgebungswert verwendet.For example, if MyKey is set in both appsettings.json and the environment, the environment value is used. Bei Verwendung der Standardkonfigurationsanbieter überschreibt der Befehlszeilen-Konfigurationsanbieter alle anderen Anbieter.Using the default configuration providers, the Command-line configuration provider overrides all other providers.

Weitere Informationen zu CreateDefaultBuilder finden Sie unter Standardeinstellungen für den Generator.For more information on CreateDefaultBuilder, see Default builder settings.

Im folgenden Code werden die aktivierten Konfigurationsanbieter in der Reihenfolge angezeigt, in der sie hinzugefügt wurden:The following code displays the enabled configuration providers in the order they were added:

public class Index2Model : PageModel
{
    private IConfigurationRoot ConfigRoot;

    public Index2Model(IConfiguration configRoot)
    {
        ConfigRoot = (IConfigurationRoot)configRoot;
    }

    public ContentResult OnGet()
    {           
        string str = "";
        foreach (var provider in ConfigRoot.Providers.ToList())
        {
            str += provider.ToString() + "\n";
        }

        return Content(str);
    }
}

appsettings.json

Betrachten Sie die folgende appsettings.json -Datei:Consider the following appsettings.json file:

{
    "Position": {
        "Title": "Editor",
        "Name": "Joe Smith"
    },
    "MyKey": "My appsettings.json Value",
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    },
    "AllowedHosts": "*"
}

Im folgenden Code aus dem Beispieldownload sind mehrere der vorherigen Konfigurationseinstellungen zu sehen:The following code from the sample download displays several of the preceding configurations settings:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Der Standard-JsonConfigurationProvider lädt die Konfiguration in der folgenden Reihenfolge:The default JsonConfigurationProvider loads configuration in the following order:

  1. appsettings.json
  2. appsettings. Environment .json: Beispielsweise die Dateien appsettings.Production**_._json and appsettings.***Development _.json*.appsettings.Environment.json : For example, the appsettings.***Production**._json* and appsettings.***Development** _._json* files. Die Umgebungsversion der Datei wird basierend auf IHostingEnvironment.EnvironmentName geladen.The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName. Weitere Informationen finden Sie unter Verwenden von mehreren Umgebungen in ASP.NET Core.For more information, see Verwenden von mehreren Umgebungen in ASP.NET Core.

appsettings.Environment.json-Werte überschreiben Schlüssel in appsettings.json .appsettings.Environment.json values override keys in appsettings.json. Standardmäßig sind dies z. B.:For example, by default:

  • In der Entwicklung überschreibt die appsettings.*Development _._json-Konfiguration in appsettings.json gefundene Werte.In development, appsettings.Development _._json configuration overwrites values found in appsettings.json.
  • In der Produktion überschreibt die appsettings.Production _._json-Konfiguration in appsettings.json gefundene Werte.In production, appsettings.Production _._json configuration overwrites values found in appsettings.json. Dies ist beispielsweise bei der Bereitstellung der App in Azure der Fall.For example, when deploying the app to Azure.

Binden hierarchischer Konfigurationsdaten mit dem OptionsmusterBind hierarchical configuration data using the options pattern

Die bevorzugte Methode für das Lesen zugehöriger Konfigurationswerte ist die Verwendung des Optionsmusters.The preferred way to read related configuration values is using the options pattern. Um z. B. die folgenden Konfigurationswerte zu lesen:For example, to read the following configuration values:

  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  }

Erstellen Sie die folgende neue PositionOptions-Klasse:Create the following PositionOptions class:

public class PositionOptions
{
    public const string Position = "Position";

    public string Title { get; set; }
    public string Name { get; set; }
}

Eine Optionsklasse:An options class:

  • Eine Optionsklasse muss nicht abstrakt sein und über einen öffentlichen parameterlosen Konstruktor verfügen.Must be non-abstract with a public parameterless constructor.
  • Alle öffentlichen Lese-/Schreibeigenschaften des Typs sind gebunden.All public read-write properties of the type are bound.
  • Felder werden nicht gebunden.Fields are *not _ bound. Im vorangehenden Code ist Position nicht gebunden.In the preceding code, Position is not bound. Die Position-Eigenschaft wird verwendet, sodass die Zeichenfolge "Position" nicht in der App hartcodiert werden muss, wenn die Klasse an einen Konfigurationsanbieter gebunden wird.The Position property is used so the string "Position" doesn't need to be hard coded in the app when binding the class to a configuration provider.

Der folgende CodeThe following code:

_ ruft ConfigurationBinder.Bind auf, um die PositionOptions-Klasse an den Position-Abschnitt zu binden_ Calls ConfigurationBinder.Bind to bind the PositionOptions class to the Position section.

  • Zeigt die Position-Konfigurationsdaten an.Displays the Position configuration data.
public class Test22Model : PageModel
{
    private readonly IConfiguration Configuration;

    public Test22Model(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var positionOptions = new PositionOptions();
        Configuration.GetSection(PositionOptions.Position).Bind(positionOptions);

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

Im vorangehenden Code werden standardmäßig Änderungen an der JSON-Konfigurationsdatei gelesen, nachdem die App gestartet wurde.In the preceding code, by default, changes to the JSON configuration file after the app has started are read.

ConfigurationBinder.Get<T> bindet den angegebenen Typ und gibt ihn zurück.ConfigurationBinder.Get<T> binds and returns the specified type. ConfigurationBinder.Get<T> ist möglicherweise praktischer als die Verwendung von ConfigurationBinder.Bind.ConfigurationBinder.Get<T> may be more convenient than using ConfigurationBinder.Bind. Der folgende Code zeigt die Verwendung von ConfigurationBinder.Get<T> mit der PositionOptions-Klasse:The following code shows how to use ConfigurationBinder.Get<T> with the PositionOptions class:

public class Test21Model : PageModel
{
    private readonly IConfiguration Configuration;
    public PositionOptions positionOptions { get; private set; }

    public Test21Model(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {            
        positionOptions = Configuration.GetSection(PositionOptions.Position)
                                                     .Get<PositionOptions>();

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

Im vorangehenden Code werden standardmäßig Änderungen an der JSON-Konfigurationsdatei gelesen, nachdem die App gestartet wurde.In the preceding code, by default, changes to the JSON configuration file after the app has started are read.

Eine alternative Vorgehensweise bei der Verwendung des Optionsmusters besteht darin, den Position-Abschnitt zu binden und ihn zum Dependency-Injection-Dienstcontainer hinzuzufügen.An alternative approach when using the *options pattern _ is to bind the Position section and add it to the dependency injection service container. Im folgenden Code wird PositionOptions mit <xref:Microsoft.Extensions.DependencyInjection.OptionsConfigurationServiceCollectionExtensions.Configure_> zum Dienstcontainer hinzugefügt und an die Konfiguration gebunden:In the following code, PositionOptions is added to the service container with <xref:Microsoft.Extensions.DependencyInjection.OptionsConfigurationServiceCollectionExtensions.Configure_> and bound to configuration:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<PositionOptions>(Configuration.GetSection(
                                        PositionOptions.Position));
    services.AddRazorPages();
}

Mithilfe des vorangehenden Codes liest der folgende Code die Positionsoptionen:Using the preceding code, the following code reads the position options:

public class Test2Model : PageModel
{
    private readonly PositionOptions _options;

    public Test2Model(IOptions<PositionOptions> options)
    {
        _options = options.Value;
    }

    public ContentResult OnGet()
    {
        return Content($"Title: {_options.Title} \n" +
                       $"Name: {_options.Name}");
    }
}

Im vorangehenden Code werden Änderungen an der JSON-Konfigurationsdatei nach dem Start der App nicht gelesen.In the preceding code, changes to the JSON configuration file after the app has started are not read. Verwenden Sie IOptionsSnapshot, um Änderungen lesen zu können, nachdem die App gestartet wurde.To read changes after the app has started, use IOptionsSnapshot.

Wenn die Standard-Konfiguration verwendet wird, werden die Dateien appsettings.json und appsettings. Environment .json mit reloadOnChange: true aktiviert.Using the default configuration, the appsettings.json and appsettings.Environment.json files are enabled with reloadOnChange: true. Änderungen an den Dateien appsettings.json und appsettings. Environment .json *nach dem Start der App werden vom JSON-Konfigurationsanbieter gelesen.Changes made to the appsettings.json and appsettings.Environment.json file *after _ the app starts are read by the JSON configuration provider.

Weitere Informationen zum Hinzufügen zusätzlicher JSON-Konfigurationsdateien finden Sie unter JSON-Konfigurationsanbieter in diesem Dokument.See JSON configuration provider in this document for information on adding additional JSON configuration files.

Kombinieren von DienstsammlungenCombining service collection

Mit der folgenden ConfigureServices-Methode können Sie Dienste registrieren und Optionen konfigurieren:Consider the following ConfigureServices method, which registers services and configures options:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<PositionOptions>(
        Configuration.GetSection(PositionOptions.Position));
    services.Configure<ColorOptions>(
        Configuration.GetSection(ColorOptions.Color));

    services.AddScoped<IMyDependency, MyDependency>();
    services.AddScoped<IMyDependency2, MyDependency2>();

    services.AddRazorPages();
}

Ähnliche Registrierungsgruppen können in eine Erweiterungsmethode verschoben werden, um Dienste zu registrieren.Related groups of registrations can be moved to an extension method to register services. Die Konfigurationsdienste werden beispielsweise folgender Klasse hinzugefügt:For example, the configuration services are added to the following class:

using ConfigSample.Options;
using Microsoft.Extensions.Configuration;

namespace Microsoft.Extensions.DependencyInjection
{
    public static class MyConfigServiceCollectionExtensions
    {
        public static IServiceCollection AddConfig(
             this IServiceCollection services, IConfiguration config)
        {
            services.Configure<PositionOptions>(
                config.GetSection(PositionOptions.Position));
            services.Configure<ColorOptions>(
                config.GetSection(ColorOptions.Color));

            return services;
        }
    }
}

Die verbleibenden Dienste werden in einer ähnlichen Klasse registriert.The remaining services are registered in a similar class. Die folgende ConfigureServices-Methode verwendet die neuen Erweiterungsmethoden, um die Dienste zu registrieren:The following ConfigureServices method uses the new extension methods to register the services:

public void ConfigureServices(IServiceCollection services)
{
    services.AddConfig(Configuration)
            .AddMyDependencyGroup();

    services.AddRazorPages();
}

Hinweis: Jede services.Add{GROUP_NAME}-Erweiterungsmethode fügt Dienste hinzu und konfiguriert diese möglicherweise.Note: Each services.Add{GROUP_NAME} extension method adds and potentially configures services. Beispielsweise fügt AddControllersWithViews den MVC-Controller für Dienste mit den erforderlichen Ansichten hinzu, und AddRazorPages fügt die für Razor Pages benötigten Dienste hinzu.For example, AddControllersWithViews adds the services MVC controllers with views require, and AddRazorPages adds the services Razor Pages requires. Es wird empfohlen, dass Apps dieser Namenskonvention folgen.We recommended that apps follow this naming convention. Platzieren Sie Erweiterungsmethoden im Namespace Microsoft.Extensions.DependencyInjection, um Gruppen von Dienstregistrierungen zu kapseln.Place extension methods in the Microsoft.Extensions.DependencyInjection namespace to encapsulate groups of service registrations.

Sicherheit und BenutzergeheimnisseSecurity and user secrets

Richtlinien für Konfigurationsdaten:Configuration data guidelines:

_ Speichern Sie nie Kennwörter oder andere vertrauliche Daten im Konfigurationsanbietercode oder in Nur-Text-Konfigurationsdateien._ Never store passwords or other sensitive data in configuration provider code or in plain text configuration files. Das Secret Manager-Tool kann zum Speichern von Geheimnissen in der Entwicklungsumgebung verwendet werden.The Secret Manager tool can be used to store secrets in development.

  • Verwenden Sie keine Produktionsgeheimnisse in Entwicklungs- oder Testumgebungen.Don't use production secrets in development or test environments.
  • Geben Sie Geheimnisse außerhalb des Projekts an, damit sie nicht versehentlich in ein Quellcoderepository übernommen werden können.Specify secrets outside of the project so that they can't be accidentally committed to a source code repository.

Im Standardmodell wird die Quelle der Benutzergeheimniskonfiguration nach den Quellen für die JSON-Konfiguration registriert.By default, the user secrets configuration source is registered after the JSON configuration sources. Daher haben geheime Benutzerschlüssel Vorrang vor Schlüssel in appsettings.json und appsettings. Environment .json.Therefore, user secrets keys take precedence over keys in appsettings.json and appsettings.Environment.json.

Weitere Informationen zum Speichern von Kennwörtern oder anderen vertraulichen Daten:For more information on storing passwords or other sensitive data:

Azure Key Vault speichert App-Geheimnisse für ASP.NET Core-Apps auf sichere Weise.Azure Key Vault safely stores app secrets for ASP.NET Core apps. Weitere Informationen finden Sie unter Azure Key Vault Konfigurations Anbieters in ASP.net Core.For more information, see Azure Key Vault Konfigurations Anbieters in ASP.net Core.

UmgebungsvariablenEnvironment variables

Bei Verwendung der Standard-Konfiguration lädt der EnvironmentVariablesConfigurationProvider die Konfiguration aus Schlüssel-Wert-Paaren der Umgebungsvariablen, nachdem appsettings.json , appsettings. Environment .json und Benutzergeheimnisse gelesen wurden.Using the default configuration, the EnvironmentVariablesConfigurationProvider loads configuration from environment variable key-value pairs after reading appsettings.json, appsettings.Environment.json, and user secrets. Daher überschreiben aus der Umgebung gelesene Schlüsselwerte Werte, die aus appsettings.json , appsettings. Environment .json und Benutzergeheimnissen gelesen wurden.Therefore, key values read from the environment override values read from appsettings.json, appsettings.Environment.json, and user secrets.

Das Trennzeichen : funktioniert nicht auf allen Plattformen mit den hierarchischen Schlüsseln von Umgebungsvariablen.The : separator doesn't work with environment variable hierarchical keys on all platforms. Der doppelte Unterstrich __:__, the double underscore, is:

  • wird auf allen Plattformen unterstützt.Supported by all platforms. Das Trennzeichen : wird beispielsweise nicht von Bash unterstützt, __ hingegen schon.For example, the : separator is not supported by Bash, but __ is.
  • automatisch durch : ersetzt.Automatically replaced by a :

Die folgenden set-Befehle:The following set commands:

  • Legen die Umgebungsschlüssel und -werte des vorangehenden Beispiels unter Windows fest.Set the environment keys and values of the preceding example on Windows.
  • Testen die Einstellungen bei Verwendung des Beispieldownloads.Test the settings when using the sample download. Der dotnet run-Befehl muss im Projektverzeichnis ausgeführt werden.The dotnet run command must be run in the project directory.
set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run

Die obigen Umgebungseinstellungen:The preceding environment settings:

  • Werden nur in Prozessen festgelegt, die über das Befehlsfenster gestartet werden, in dem sie festgelegt wurden.Are only set in processes launched from the command window they were set in.
  • Werden nicht von Browsern gelesen, die mit Visual Studio gestartet wurden.Won't be read by browsers launched with Visual Studio.

Die folgenden setx-Befehle können zum Festlegen der Umgebungsschlüssel und -werte unter Windows verwendet werden.The following setx commands can be used to set the environment keys and values on Windows. Anders als set werden setx-Einstellungen beibehalten.Unlike set, setx settings are persisted. /M legt die Variable in der Systemumgebung fest./M sets the variable in the system environment. Wenn der /M-Schalter nicht verwendet wird, wird eine Benutzerumgebungsvariable festgelegt.If the /M switch isn't used, a user environment variable is set.

setx MyKey "My key from setx Environment" /M
setx Position__Title Setx_Environment_Editor /M
setx Position__Name Environment_Rick /M

Testen Sie wie folgt, ob die obigen Befehle appsettings.json und appsettings. Environment .json überschreiben:To test that the preceding commands override appsettings.json and appsettings.Environment.json:

  • Mit Visual Studio: Beenden Sie Visual Studio, und starten Sie dann Visual Studio neu.With Visual Studio: Exit and restart Visual Studio.
  • Mit der Befehlszeilenschnittstelle: Starten Sie ein neues Befehlsfenster, und geben Sie dotnet run ein.With the CLI: Start a new command window and enter dotnet run.

Rufen Sie AddEnvironmentVariables mit einer Zeichenfolge auf, um ein Präfix für Umgebungsvariablen anzugeben:Call AddEnvironmentVariables with a string to specify a prefix for environment variables:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddEnvironmentVariables(prefix: "MyCustomPrefix_");
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Für den Code oben gilt:In the preceding code:

Das Präfix wird beim Lesen der Schlüssel-Wert-Paare der Konfiguration entfernt.The prefix is stripped off when the configuration key-value pairs are read.

Mit den folgenden Befehlen wird das benutzerdefinierte Präfix getestet:The following commands test the custom prefix:

set MyCustomPrefix_MyKey="My key with MyCustomPrefix_ Environment"
set MyCustomPrefix_Position__Title=Editor_with_customPrefix
set MyCustomPrefix_Position__Name=Environment_Rick_cp
dotnet run

Die Standardkonfiguration lädt Umgebungsvariablen und Befehlszeilenargumente, die das Präfix DOTNET_ und ASPNETCORE_ aufweisen.The default configuration loads environment variables and command line arguments prefixed with DOTNET_ and ASPNETCORE_. Die Präfixe DOTNET_ und ASPNETCORE_ werden von ASP.NET Core für die Host- und App-Konfiguration, jedoch nicht für die Benutzerkonfiguration verwendet.The DOTNET_ and ASPNETCORE_ prefixes are used by ASP.NET Core for host and app configuration, but not for user configuration. Weitere Informationen zur Host- und App-Konfiguration finden Sie unter .NET Generic Host.For more information on host and app configuration, see .NET Generic Host.

Wählen Sie in Azure App Service auf der Seite Einstellungen > Konfiguration die Option Neue Anwendungseinstellung aus.On Azure App Service, select New application setting on the Settings > Configuration page. Anwendungseinstellungen von Azure App Service werden:Azure App Service application settings are:

  • Im Ruhezustand verschlüsselt und über einen verschlüsselten Kanal übermittelt.Encrypted at rest and transmitted over an encrypted channel.
  • Als Umgebungsvariablen verfügbar gemacht.Exposed as environment variables.

Weitere Informationen finden Sie unter Azure-Apps: Überschreiben der App-Konfiguration im Azure-Portal.For more information, see Azure Apps: Override app configuration using the Azure Portal.

Informationen zu Azure-Datenbankverbindungszeichenfolgen finden Sie unter Präfixe für Verbindungszeichenfolgen.See Connection string prefixes for information on Azure database connection strings.

Benennen von UmgebungsvariablenNaming of environment variables

Umgebungsvariablennamen entsprechen der Struktur einer appsettings.json -Datei.Environment variable names reflect the structure of an appsettings.json file. Die Elemente in der Hierarchie werden durch einen doppelten Unterstrich (vorzugsweise) oder einen Doppelpunkt getrennt.Each element in the hierarchy is separated by a double underscore (preferable) or a colon. Wenn die Elementstruktur ein Array enthält, sollte der Arrayindex als zusätzlicher Elementname in diesem Pfad behandelt werden.When the element structure includes an array, the array index should be treated as an additional element name in this path. Schauen Sie sich die folgende appsettings.json -Datei und ihre entsprechenden Werte an, die als Umgebungsvariablen dargestellt werden.Consider the following appsettings.json file and its equivalent values represented as environment variables.

appsettings.json

{
    "SmtpServer": "smtp.example.com",
    "Logging": [
        {
            "Name": "ToEmail",
            "Level": "Critical",
            "Args": {
                "FromAddress": "MySystem@example.com",
                "ToAddress": "SRE@example.com"
            }
        },
        {
            "Name": "ToConsole",
            "Level": "Information"
        }
    ]
}

Umgebungsvariablenenvironment variables

setx SmtpServer=smtp.example.com
setx Logging__0__Name=ToEmail
setx Logging__0__Level=Critical
setx Logging__0__Args__FromAddress=MySystem@example.com
setx Logging__0__Args__ToAddress=SRE@example.com
setx Logging__1__Name=ToConsole
setx Logging__1__Level=Information

In „launchSettings.json“ festgelegte UmgebungsvariablenEnvironment variables set in launchSettings.json

Umgebungsvariablen, die in der Datei launchSettings.json festgelegt sind, überschreiben diejenigen, die in der Systemumgebung festgelegt sind.Environment variables set in launchSettings.json override those set in the system environment.

BefehlszeileCommand-line

Bei Verwendung der Standard-Konfiguration lädt der CommandLineConfigurationProvider die Konfiguration aus den Schlüssel-Wert-Paaren des Befehlszeilenarguments nach den folgenden Konfigurationsquellen:Using the default configuration, the CommandLineConfigurationProvider loads configuration from command-line argument key-value pairs after the following configuration sources:

  • In den Dateien appsettings.json und appsettings.Environment.jsonappsettings.json and appsettings.Environment.json files.
  • App-Geheimnisse in der Entwicklungsumgebung.App secrets in the Development environment.
  • Umgebungsvariablen.Environment variables.

Standardmäßig überschreiben in der Befehlszeile festgelegte Konfigurationswerte die Konfigurationswerte, die mit allen anderen Konfigurationsanbietern festgelegt wurden.By default, configuration values set on the command-line override configuration values set with all the other configuration providers.

BefehlszeilenargumenteCommand-line arguments

Der folgende Befehl legt Schlüssel und Werte unter Verwendung von = fest:The following command sets keys and values using =:

dotnet run MyKey="My key from command line" Position:Title=Cmd Position:Name=Cmd_Rick

Der folgende Befehl legt Schlüssel und Werte unter Verwendung von / fest:The following command sets keys and values using /:

dotnet run /MyKey "Using /" /Position:Title=Cmd_ /Position:Name=Cmd_Rick

Der folgende Befehl legt Schlüssel und Werte unter Verwendung von -- fest:The following command sets keys and values using --:

dotnet run --MyKey "Using --" --Position:Title=Cmd-- --Position:Name=Cmd--Rick

Der Schlüsselwert:The key value:

  • Muss auf = folgen, oder der Schlüssel muss das Präfix -- oder / aufweisen, wenn der Wert auf ein Leerzeichen folgt.Must follow =, or the key must have a prefix of -- or / when the value follows a space.
  • Ist nicht erforderlich, wenn = verwendet wird.Isn't required if = is used. Beispielsweise MySetting=.For example, MySetting=.

Kombinieren Sie in einem Befehl nicht Schlüssel-Wert-Paare des Befehlszeilenarguments, die = verwenden, mit Schlüssel-Wert-Paaren, die ein Leerzeichen verwenden.Within the same command, don't mix command-line argument key-value pairs that use = with key-value pairs that use a space.

SwitchmappingsSwitch mappings

Switchmappings erlauben das Angeben einer Logik zum Ersetzen von Schlüsselnamen.Switch mappings allow key name replacement logic. Stellen Sie ein Wörterbuch mit Switchersetzungen für die AddCommandLine-Methode bereit.Provide a dictionary of switch replacements to the AddCommandLine method.

Wenn das Switchmappingwörterbuch verwendet wird, wird das Wörterbuch für Schlüssel, die dem von einem Befehlszeilenargument angegebenen Schlüssel entsprechen, überprüft.When the switch mappings dictionary is used, the dictionary is checked for a key that matches the key provided by a command-line argument. 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.If the command-line key is found in the dictionary, the dictionary value is passed back to set the key-value pair into the app's configuration. Ein Switchmapping ist für jeden Befehlszeilenschlüssel erforderlich, dem ein einzelner Gedankenstrich (-) vorangestellt ist.A switch mapping is required for any command-line key prefixed with a single dash (-).

Regeln für Schlüssel von Switchmappingwörterbüchern:Switch mappings dictionary key rules:

  • Switches müssen mit - oder -- beginnen.Switches must start with - or --.
  • Das Switchmappingwörterbuch darf keine doppelten Schlüssel enthalten.The switch mappings dictionary must not contain duplicate keys.

Wenn Sie ein Switchmappingwörterbuch verwenden möchten, übergeben Sie es an den AddCommandLine-Abruf:To use a switch mappings dictionary, pass it into the call to AddCommandLine:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var switchMappings = new Dictionary<string, string>()
         {
             { "-k1", "key1" },
             { "-k2", "key2" },
             { "--alt3", "key3" },
             { "--alt4", "key4" },
             { "--alt5", "key5" },
             { "--alt6", "key6" },
         };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddCommandLine(args, switchMappings);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Der folgende Code zeigt die Schlüsselwerte für die ersetzten Schlüssel:The following code shows the key values for the replaced keys:

public class Test3Model : PageModel
{
    private readonly IConfiguration Config;

    public Test3Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        return Content(
                $"Key1: '{Config["Key1"]}'\n" +
                $"Key2: '{Config["Key2"]}'\n" +
                $"Key3: '{Config["Key3"]}'\n" +
                $"Key4: '{Config["Key4"]}'\n" +
                $"Key5: '{Config["Key5"]}'\n" +
                $"Key6: '{Config["Key6"]}'");
    }
}

Mit dem folgenden Befehl kann die Schlüsselersetzung getestet werden:The following command works to test key replacement:

dotnet run -k1 value1 -k2 value2 --alt3=value2 /alt4=value3 --alt5 value5 /alt6 value6

Bei Apps, die Switchmappings verwenden, sollten im CreateDefaultBuilder-Aufruf keine Argumente übergeben werden.For apps that use switch mappings, the call to CreateDefaultBuilder shouldn't pass arguments. Der AddCommandLine-Aufruf der CreateDefaultBuilder-Methode umfasst keine zugeordneten Switches, und das Switchmappingwörterbuch kann nicht an CreateDefaultBuilder übergeben werden.The CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and there's no way to pass the switch-mapping dictionary to CreateDefaultBuilder. Die Lösung besteht nicht darin, die Argumente an CreateDefaultBuilder zu übergeben, sondern der AddCommandLine-Methode der ConfigurationBuilder-Methode zu erlauben, sowohl die Argumente als auch das Switchmappingwörterbuch zu verarbeiten.The solution isn't to pass the arguments to CreateDefaultBuilder but instead to allow the ConfigurationBuilder method's AddCommandLine method to process both the arguments and the switch-mapping dictionary.

Hierarchische KonfigurationsdatenHierarchical configuration data

Die Konfigurations-API liest hierarchische Konfigurationsdaten, indem sie die hierarchischen Daten mit einem Trennzeichen in den Konfigurationsschlüsseln vereinfacht.The Configuration API reads hierarchical configuration data by flattening the hierarchical data with the use of a delimiter in the configuration keys.

Der Beispieldownload enthält die folgende Datei appsettings.json :The sample download contains the following appsettings.json file:

{
    "Position": {
        "Title": "Editor",
        "Name": "Joe Smith"
    },
    "MyKey": "My appsettings.json Value",
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    },
    "AllowedHosts": "*"
}

Der folgende Code aus dem Beispieldownload zeigt einige der Konfigurationseinstellungen:The following code from the sample download displays several of the configurations settings:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Die bevorzugte Methode zum Lesen hierarchischer Konfigurationsdaten ist die Verwendung des Optionsmusters.The preferred way to read hierarchical configuration data is using the options pattern. Weitere Informationen finden Sie unter Binden hierarchischer Konfigurationsdaten in diesem Dokument.For more information, see Bind hierarchical configuration data in this document.

Mit den Methoden GetSection und GetChildren können Abschnitte und untergeordnete Abschnittelemente in den Konfigurationsdaten isoliert werden.GetSection and GetChildren methods are available to isolate sections and children of a section in the configuration data. Diese Methoden werden später im Abschnitt GetSection, GetChildren und Exists beschrieben.These methods are described later in GetSection, GetChildren, and Exists.

Konfigurationsschlüssel und -werteConfiguration keys and values

Konfigurationsschlüssel:Configuration keys:

  • Die Groß-/Kleinschreibung wird nicht berücksichtigt.Are case-insensitive. Beispielsweise verweisen ConnectionString und connectionstring auf denselben Schlüssel.For example, ConnectionString and connectionstring are treated as equivalent keys.
  • Wenn ein Schlüssel und ein Wert in mehreren Konfigurationsanbietern festgelegt ist, wird der Wert des zuletzt hinzugefügten Anbieters verwendet.If a key and value is set in more than one configuration providers, the value from the last provider added is used. Weitere Informationen finden Sie unter Standardkonfiguration.For more information, see Default configuration.
  • Hierarchische SchlüsselHierarchical keys
    • Innerhalb der Konfigurations-API funktioniert ein Doppelpunkt (:) als Trennzeichen auf allen Plattformen.Within the Configuration API, a colon separator (:) works on all platforms.
    • In Umgebungsvariablen funktioniert ein Doppelpunkt als Trennzeichen ggf. nicht auf allen Plattformen.In environment variables, a colon separator may not work on all platforms. Ein doppelter Unterstrich (__) wird von allen Plattformen unterstützt und automatisch in einen Doppelpunkt (:) umgewandelt.A double underscore, __, is supported by all platforms and is automatically converted into a colon :.
    • In Azure Key Vault verwenden hierarchische Schlüssel -- als Trennzeichen.In Azure Key Vault, hierarchical keys use -- as a separator. Der Azure Key Vault-Konfigurationsanbieter ersetzt -- automatisch durch :, wenn die Geheimnisse in die Konfiguration der App geladen werden.The Azure Key Vault configuration provider automatically replaces -- with a : when the secrets are loaded into the app's configuration.
  • ConfigurationBinder unterstützt das Binden von Arrays an Objekte mit Arrayindizes in Konfigurationsschlüsseln.The ConfigurationBinder supports binding arrays to objects using array indices in configuration keys. Die Arraybindung wird im Abschnitt Binden eines Arrays an eine Klasse beschrieben.Array binding is described in the Bind an array to a class section.

Konfigurationswerte:Configuration values:

  • Sind Zeichenfolgen.Are strings.
  • NULL-Werte können nicht in einer Konfiguration gespeichert oder an Objekte gebunden werden.Null values can't be stored in configuration or bound to objects.

KonfigurationsanbieterConfiguration providers

Die folgende Tabelle zeigt die für ASP.NET Core-Apps verfügbaren Konfigurationsanbieter.The following table shows the configuration providers available to ASP.NET Core apps.

AnbieterProvider Bereitstellung der Konfiguration überProvides configuration from
Azure Key Vault-KonfigurationsanbieterAzure Key Vault configuration provider Azure Key VaultAzure Key Vault
Azure-App-KonfigurationsanbieterAzure App configuration provider Azure App ConfigurationAzure App Configuration
Befehlszeilen-KonfigurationsanbieterCommand-line configuration provider BefehlszeilenparameterCommand-line parameters
Benutzerdefinierter KonfigurationsanbieterCustom configuration provider Benutzerdefinierte QuelleCustom source
Umgebungsvariablen-KonfigurationsanbieterEnvironment Variables configuration provider UmgebungsvariablenEnvironment variables
DateikonfigurationsanbieterFile configuration provider INI-, JSON- und XML-DateienINI, JSON, and XML files
Schlüssel-pro-Datei-KonfigurationsanbieterKey-per-file configuration provider VerzeichnisdateienDirectory files
SpeicherkonfigurationsanbieterMemory configuration provider In-Memory-SammlungenIn-memory collections
BenutzergeheimnisseUser secrets Datei im BenutzerprofilverzeichnisFile in the user profile directory

Konfigurationsquellen werden in der Reihenfolge gelesen, in der ihre Konfigurationsanbieter angegeben sind.Configuration sources are read in the order that their configuration providers are specified. 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.Order configuration providers in code to suit the priorities for the underlying configuration sources that the app requires.

Eine typische Konfigurationsanbietersequenz ist:A typical sequence of configuration providers is:

  1. appsettings.json
  2. appsettings.Environment.jsonappsettings.Environment.json
  3. BenutzergeheimnisseUser secrets
  4. Umgebungsvariablen, die den Umgebungsvariablen-Konfigurationsanbieter verwendenEnvironment variables using the Environment Variables configuration provider.
  5. Befehlszeilenargumente, die den Befehlszeilen-Konfigurationsanbieter verwendenCommand-line arguments using the Command-line configuration provider.

In der Regel werden Befehlszeilen-Konfigurationsanbieter in einer Reihe von Anbietern an letzter Stelle hinzugefügt, damit Befehlszeilenargumente die von anderen Anbietern festgelegte Konfiguration überschreiben können.A common practice is to add the Command-line configuration provider last in a series of providers to allow command-line arguments to override configuration set by the other providers.

Die obige Sequenz von Anbietern wird in der Standardkonfiguration verwendet.The preceding sequence of providers is used in the default configuration.

Präfixe für VerbindungszeichenfolgenConnection string prefixes

Die Konfigurations-API verfügt über spezielle Verarbeitungsregeln für vier Umgebungsvariablen für Verbindungszeichenfolgen.The Configuration API has special processing rules for four connection string environment variables. Diese Verbindungszeichenfolgen sind beim Konfigurieren von Azure-Verbindungszeichenfolgen für die App-Umgebung beteiligt.These connection strings are involved in configuring Azure connection strings for the app environment. 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.Environment variables with the prefixes shown in the table are loaded into the app with the default configuration or when no prefix is supplied to AddEnvironmentVariables.

Präfix für VerbindungszeichenfolgenConnection string prefix AnbieterProvider
CUSTOMCONNSTR_ Benutzerdefinierter AnbieterCustom provider
MYSQLCONNSTR_ MySQLMySQL
SQLAZURECONNSTR_ Azure SQL-DatenbankAzure SQL Database
SQLCONNSTR_ SQL ServerSQL Server

Wenn eine Umgebungsvariable entdeckt und mit einem der vier Präfixe aus der Tabelle in die Konfiguration geladen wird, tritt Folgendes ein:When an environment variable is discovered and loaded into configuration with any of the four prefixes shown in the table:

  • Der Konfigurationsschlüssel wird durch Entfernen des Umgebungsvariablenpräfixes und Hinzufügen eines Konfigurationsschlüsselabschnitts (ConnectionStrings) erstellt.The configuration key is created by removing the environment variable prefix and adding a configuration key section (ConnectionStrings).
  • 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).A new configuration key-value pair is created that represents the database connection provider (except for CUSTOMCONNSTR_, which has no stated provider).
UmgebungsvariablenschlüsselEnvironment variable key Konvertierter KonfigurationsschlüsselConverted configuration key AnbieterkonfigurationseintragProvider configuration entry
CUSTOMCONNSTR_{KEY} ConnectionStrings:{KEY} Konfigurationseintrag wurde nicht erstellt.Configuration entry not created.
MYSQLCONNSTR_{KEY} ConnectionStrings:{KEY} Schlüssel: ConnectionStrings:{KEY}_ProviderName:Key: ConnectionStrings:{KEY}_ProviderName:
Wert: MySql.Data.MySqlClientValue: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY} ConnectionStrings:{KEY} Schlüssel: ConnectionStrings:{KEY}_ProviderName:Key: ConnectionStrings:{KEY}_ProviderName:
Wert: System.Data.SqlClientValue: System.Data.SqlClient
SQLCONNSTR_{KEY} ConnectionStrings:{KEY} Schlüssel: ConnectionStrings:{KEY}_ProviderName:Key: ConnectionStrings:{KEY}_ProviderName:
Wert: System.Data.SqlClientValue: System.Data.SqlClient

DateikonfigurationsanbieterFile configuration provider

FileConfigurationProvider ist die Basisklasse für das Laden einer Konfiguration aus dem Dateisystem.FileConfigurationProvider is the base class for loading configuration from the file system. Die folgenden Konfigurationsanbieter leiten sich vom FileConfigurationProvider ab:The following configuration providers derive from FileConfigurationProvider:

INI-KonfigurationsanbieterINI configuration provider

IniConfigurationProvider lädt während der Laufzeit die Konfiguration aus den Schlüssel-Wert-Paaren der INI-Datei.The IniConfigurationProvider loads configuration from INI file key-value pairs at runtime.

Mit dem folgenden Code werden alle Konfigurationsanbieter gelöscht und mehrere Konfigurationsanbieter hinzugefügt:The following code clears all the configuration providers and adds several configuration providers:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddIniFile("MyIniConfig.ini", optional: true, reloadOnChange: true)
                      .AddIniFile($"MyIniConfig.{env.EnvironmentName}.ini",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Im obigen Code werden Einstellungen in den Dateien MyIniConfig.ini und MyIniConfig.Environment.ini überschrieben durch Einstellungen im:In the preceding code, settings in the MyIniConfig.ini and MyIniConfig.Environment.ini files are overridden by settings in the:

Der Beispieldownload enthält die folgende Datei MyIniConfig.ini:The sample download contains the following MyIniConfig.ini file:

MyKey="MyIniConfig.ini Value"

[Position]
Title="My INI Config title"
Name="My INI Config name"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Im folgenden Code aus dem Beispieldownload sind mehrere der vorherigen Konfigurationseinstellungen zu sehen:The following code from the sample download displays several of the preceding configurations settings:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

JSON-KonfigurationsanbieterJSON configuration provider

Der JsonConfigurationProvider lädt die Konfiguration aus den Schlüssel-Wert-Paaren der JSON-Datei.The JsonConfigurationProvider loads configuration from JSON file key-value pairs.

Überladungen können Folgendes angeben:Overloads can specify:

  • Ob die Datei optional istWhether the file is optional.
  • Ob die Konfiguration bei Dateiänderungen neu geladen wirdWhether the configuration is reloaded if the file changes.

Betrachten Sie folgenden Code:Consider the following code:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("MyConfig.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Der vorangehende Code:The preceding code:

In der Regel möchten Sie *nicht, dass eine benutzerdefinierte JSON-Datei Werte überschreibt, die im Umgebungsvariablen-Konfigurationsanbieter und im Befehlszeilen-Konfigurationsanbieter festgelegt sind.You typically *don't _ want a custom JSON file overriding values set in the Environment variables configuration provider and the Command-line configuration provider.

Mit dem folgenden Code werden alle Konfigurationsanbieter gelöscht und mehrere Konfigurationsanbieter hinzugefügt:The following code clears all the configuration providers and adds several configuration providers:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

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

                config.AddJsonFile("MyConfig.json", optional: true, reloadOnChange: true)
                      .AddJsonFile($"MyConfig.{env.EnvironmentName}.json",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Im obigen Code gilt für Einstellungen in den Dateien _MyConfig.json* und MyConfig.Environment.json:In the preceding code, settings in the _MyConfig.json* and MyConfig.Environment.json files:

Der Beispieldownload enthält die folgende Datei MyConfig.json:The sample download contains the following MyConfig.json file:

{
    "Position": {
        "Title": "Eigener Konfigurationstitel",
        "Name": "My Config Smith"
    },
    "MyKey": "MyConfig.json Value",
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    },
    "AllowedHosts": "*"
}

Im folgenden Code aus dem Beispieldownload sind mehrere der vorherigen Konfigurationseinstellungen zu sehen:The following code from the sample download displays several of the preceding configurations settings:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

XML-KonfigurationsanbieterXML configuration provider

XmlConfigurationProvider lädt während der Laufzeit die Konfiguration aus den Schlüssel-Wert-Paaren der XML-Datei.The XmlConfigurationProvider loads configuration from XML file key-value pairs at runtime.

Mit dem folgenden Code werden alle Konfigurationsanbieter gelöscht und mehrere Konfigurationsanbieter hinzugefügt:The following code clears all the configuration providers and adds several configuration providers:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddXmlFile("MyXMLFile.xml", optional: true, reloadOnChange: true)
                      .AddXmlFile($"MyXMLFile.{env.EnvironmentName}.xml",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Im obigen Code werden Einstellungen in den Dateien MyXMLFile.xml und MyXMLFile.Environment.xml überschrieben durch Einstellungen im:In the preceding code, settings in the MyXMLFile.xml and MyXMLFile.Environment.xml files are overridden by settings in the:

Der Beispieldownload enthält die folgende Datei MyXMLFile.xml:The sample download contains the following MyXMLFile.xml file:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <MyKey>MyXMLFile Value</MyKey>
  <Position>
    <Title>Title from  MyXMLFile</Title>
    <Name>Name from MyXMLFile</Name>
  </Position>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

Im folgenden Code aus dem Beispieldownload sind mehrere der vorherigen Konfigurationseinstellungen zu sehen:The following code from the sample download displays several of the preceding configurations settings:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Wiederholte Elemente mit den gleichen Elementnamen funktionieren, wenn das name-Attribut zur Unterscheidung der Elemente verwendet wird:Repeating elements that use the same element name work if the name attribute is used to distinguish the elements:

<?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:The following code reads the previous configuration file and displays the keys and values:

public class IndexModel : PageModel
{
    private readonly IConfiguration Configuration;

    public IndexModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var key00 = "section:section0:key:key0";
        var key01 = "section:section0:key:key1";
        var key10 = "section:section1:key:key0";
        var key11 = "section:section1:key:key1";

        var val00 = Configuration[key00];
        var val01 = Configuration[key01];
        var val10 = Configuration[key10];
        var val11 = Configuration[key11];

        return Content($"{key00} value: {val00} \n" +
                       $"{key01} value: {val01} \n" +
                       $"{key10} value: {val10} \n" +
                       $"{key10} value: {val11} \n"
                       );
    }
}

Mit Attributen können Werte bereitgestellt werden:Attributes can be used to supply values:

<?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:The previous configuration file loads the following keys with value:

  • key:attributekey:attribute
  • section:key:attributesection:key:attribute

Schlüssel-pro-Datei-KonfigurationsanbieterKey-per-file configuration provider

KeyPerFileConfigurationProvider verwendet Verzeichnisdateien als Konfigurations-Schlüssel-Wert-Paare.The KeyPerFileConfigurationProvider uses a directory's files as configuration key-value pairs. Der Schlüssel ist der Dateiname.The key is the file name. Der Wert enthält den Inhalt der Datei.The value contains the file's contents. Der Schlüssel-pro-Datei-Konfigurationsanbieter wird in Docker-Hostingszenarios verwendet.The Key-per-file configuration provider is used in Docker hosting scenarios.

Um die Schlüssel-pro-Datei-Konfiguration zu aktivieren, rufen Sie die AddKeyPerFile-Erweiterungsmethode auf einer ConfigurationBuilder-Instanz auf.To activate key-per-file configuration, call the AddKeyPerFile extension method on an instance of ConfigurationBuilder. Der directoryPath zu den Dateien muss ein absoluter Pfad sein.The directoryPath to the files must be an absolute path.

Überladungen geben Folgendes an:Overloads permit specifying:

  • Einen Action<KeyPerFileConfigurationSource>-Delegat, der die Quelle konfiguriertAn Action<KeyPerFileConfigurationSource> delegate that configures the source.
  • Ob das Verzeichnis optional ist; und den Pfad zum VerzeichnisWhether the directory is optional and the path to the directory.

Der doppelte Unterstrich (__) wird als Trennzeichen für Konfigurationsschlüssel in Dateinamen verwendet.The double-underscore (__) is used as a configuration key delimiter in file names. Der Dateiname Logging__LogLevel__System erzeugt z.B. den Konfigurationsschlüssel Logging:LogLevel:System.For example, the file name Logging__LogLevel__System produces the configuration key Logging:LogLevel:System.

Rufen Sie ConfigureAppConfiguration beim Erstellen des Hosts auf, um die Konfiguration der App anzugeben:Call ConfigureAppConfiguration when building the host to specify the app's configuration:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");
    config.AddKeyPerFile(directoryPath: path, optional: true);
})

SpeicherkonfigurationsanbieterMemory configuration provider

MemoryConfigurationProvider verwendet eine In-Memory-Sammlung für Konfigurations-Schlüssel-Wert-Paare.The MemoryConfigurationProvider uses an in-memory collection as configuration key-value pairs.

Der folgende Code fügt eine Arbeitsspeichersammlung zum Konfigurationssystem hinzu:The following code adds a memory collection to the configuration system:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var Dict = new Dictionary<string, string>
        {
           {"MyKey", "Dictionary MyKey Value"},
           {"Position:Title", "Dictionary_Title"},
           {"Position:Name", "Dictionary_Name" },
           {"Logging:LogLevel:Default", "Warning"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(Dict);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Der folgende Code aus dem Beispieldownload zeigt die vorherigen Konfigurationseinstellungen an:The following code from the sample download displays the preceding configurations settings:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Im obigen Code wird config.AddInMemoryCollection(Dict) nach den Standardkonfigurationsanbietern hinzugefügt.In the preceding code, config.AddInMemoryCollection(Dict) is added after the default configuration providers. Ein Beispiel für das Festlegen der Reihenfolge der Konfigurationsanbieter finden Sie unter JSON-Konfigurationsanbieter.For an example of ordering the configuration providers, see JSON configuration provider.

Ein weiteres Beispiel für die Verwendung von MemoryConfigurationProvider finden Sie unter Binden eines Arrays.See Bind an array for another example using MemoryConfigurationProvider.

GetValueGetValue

ConfigurationBinder.GetValue<T> extrahiert einen Einzelwert aus der Konfiguration mit einem angegebenen Schlüssel und konvertiert ihn in den angegebenen Typ:ConfigurationBinder.GetValue<T> extracts a single value from configuration with a specified key and converts it to the specified type:

public class TestNumModel : PageModel
{
    private readonly IConfiguration Configuration;

    public TestNumModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var number = Configuration.GetValue<int>("NumberKey", 99);
        return Content($"{number}");
    }
}

Wenn im obigen Code NumberKey nicht in der Konfiguration gefunden wird, wird der Standardwert 99 verwendet.In the preceding code, if NumberKey isn't found in the configuration, the default value of 99 is used.

GetSection, GetChildren und ExistsGetSection, GetChildren, and Exists

Beachten Sie für die nachstehenden Beispiele die folgende Datei MySubsection.json:For the examples that follow, consider the following MySubsection.json file:

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

Der folgende Code fügt MySubsection.json zu den Konfigurationsanbietern hinzu:The following code adds MySubsection.json to the configuration providers:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("MySubsection.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

GetSectionGetSection

IConfiguration.GetSection gibt einen Konfigurationsunterabschnitt mit dem angegebenen Unterabschnittsschlüssel zurück.IConfiguration.GetSection returns a configuration subsection with the specified subsection key.

Der folgende Code gibt Werte für section1 zurück:The following code returns values for section1:

public class TestSectionModel : PageModel
{
    private readonly IConfiguration Config;

    public TestSectionModel(IConfiguration configuration)
    {
        Config = configuration.GetSection("section1");
    }

    public ContentResult OnGet()
    {
        return Content(
                $"section1:key0: '{Config["key0"]}'\n" +
                $"section1:key1: '{Config["key1"]}'");
    }
}

Der folgende Code gibt Werte für section2:subsection0 zurück:The following code returns values for section2:subsection0:

public class TestSection2Model : PageModel
{
    private readonly IConfiguration Config;

    public TestSection2Model(IConfiguration configuration)
    {
        Config = configuration.GetSection("section2:subsection0");
    }

    public ContentResult OnGet()
    {
        return Content(
                $"section2:subsection0:key0 '{Config["key0"]}'\n" +
                $"section2:subsection0:key1:'{Config["key1"]}'");
    }
}

GetSection gibt nie null zurück.GetSection never returns null. Wenn kein entsprechender Abschnitt gefunden wird, wird ein leeres IConfigurationSection-Element zurückgegeben.If a matching section isn't found, an empty IConfigurationSection is returned.

Wenn GetSection einen entsprechenden Abschnitt zurückgibt, wird Value nicht aufgefüllt.When GetSection returns a matching section, Value isn't populated. Eine Eigenschaft Key und Path werden zurückgegeben, wenn der Abschnitt vorhanden ist.A Key and Path are returned when the section exists.

GetChildren und ExistsGetChildren and Exists

Mit dem folgenden Code wird IConfiguration.GetChildren abgerufen, und es werden Werte für section2:subsection0 zurückgegeben:The following code calls IConfiguration.GetChildren and returns values for section2:subsection0:

public class TestSection4Model : PageModel
{
    private readonly IConfiguration Config;

    public TestSection4Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        string s = null;
        var selection = Config.GetSection("section2");
        if (!selection.Exists())
        {
            throw new System.Exception("section2 does not exist.");
        }
        var children = selection.GetChildren();

        foreach (var subSection in children)
        {
            int i = 0;
            var key1 = subSection.Key + ":key" + i++.ToString();
            var key2 = subSection.Key + ":key" + i.ToString();
            s += key1 + " value: " + selection[key1] + "\n";
            s += key2 + " value: " + selection[key2] + "\n";
        }
        return Content(s);
    }
}

Der obige Code ruft ConfigurationExtensions.Exists auf, um zu überprüfen, ob der Abschnitt vorhanden ist:The preceding code calls ConfigurationExtensions.Exists to verify the section exists:

Binden eines ArraysBind an array

ConfigurationBinder.Bind unterstützt das Binden von Arrays an Objekte mithilfe von Arrayindizes in Konfigurationsschlüsseln.The ConfigurationBinder.Bind supports binding arrays to objects using array indices in configuration keys. Jedes Arrayformat, das ein numerisches Schlüsselsegment verfügbar macht, kann ein Array an ein POCO-Klassenarray binden.Any array format that exposes a numeric key segment is capable of array binding to a POCO class array.

Beachten Sie MyArray.json aus dem Beispieldownload:Consider MyArray.json from the sample download:

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

Der folgende Code fügt MyArray.json zu den Konfigurationsanbietern hinzu:The following code adds MyArray.json to the configuration providers:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("MyArray.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Der folgende Code liest die Konfiguration und zeigt die Werte an:The following code reads the configuration and displays the values:

public class ArrayModel : PageModel
{
    private readonly IConfiguration Config;
    public ArrayExample _array { get; private set; }

    public ArrayModel(IConfiguration config)
    {
        Config = config;
    }

    public ContentResult OnGet()
    {
        _array = Config.GetSection("array").Get<ArrayExample>();
        string s = null;

        for (int j = 0; j < _array.Entries.Length; j++)
        {
            s += $"Index: {j}  Value:  {_array.Entries[j]} \n";
        }

        return Content(s);
    }
}

Der obige Code erzeugt die folgende Ausgabe:The preceding code returns the following output:

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 MyArray.json entspricht.In the preceding output, Index 3 has value value40, corresponding to "4": "value40", in MyArray.json. Die gebundenen Arrayindizes sind kontinuierlich und nicht an den Konfigurationsschlüsselindex gebunden.The bound array indices are continuous and not bound to the configuration key index. Der Konfigurationsbinder ist nicht in der Lage, NULL-Werte zu binden oder NULL-Einträge in gebundenen Objekten zu erstellen.The configuration binder isn't capable of binding null values or creating null entries in bound objects

Mit dem folgenden Code wird die array:entries-Konfiguration mit der AddInMemoryCollection-Erweiterungsmethode geladen:The following code loads the array:entries configuration with the AddInMemoryCollection extension method:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var arrayDict = new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            //              3   Skipped
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Der folgende Code liest die Konfiguration im arrayDict Dictionary und zeigt die Werte an:The following code reads the configuration in the arrayDict Dictionary and displays the values:

public class ArrayModel : PageModel
{
    private readonly IConfiguration Config;
    public ArrayExample _array { get; private set; }

    public ArrayModel(IConfiguration config)
    {
        Config = config;
    }

    public ContentResult OnGet()
    {
        _array = Config.GetSection("array").Get<ArrayExample>();
        string s = null;

        for (int j = 0; j < _array.Entries.Length; j++)
        {
            s += $"Index: {j}  Value:  {_array.Entries[j]} \n";
        }

        return Content(s);
    }
}

Der obige Code erzeugt die folgende Ausgabe:The preceding code returns the following output:

Index: 0  Value: value0
Index: 1  Value: value1
Index: 2  Value: value2
Index: 3  Value: value4
Index: 4  Value: value5

Index #3 im gebundenen Objekt enthält die Konfigurationsdaten für den array:4-Konfigurationsschlüssel und die Wert für value4.Index #3 in the bound object holds the configuration data for the array:4 configuration key and its value of value4. Beim Binden von Konfigurationsdaten, die ein Array enthalten, werden die Arrayindizes in den Konfigurationsschlüsseln zum Durchlaufen der Konfigurationsdaten beim Erstellen des Objekts verwendet.When configuration data containing an array is bound, the array indices in the configuration keys are used to iterate the configuration data when creating the object. Ein NULL-Wert kann in den Konfigurationsdaten nicht beibehalten werden, und ein NULL-Eintrag wird nicht in einem gebundenen Objekt erstellt, wenn ein Array in Konfigurationsschlüsseln mindestens einen Index überspringt.A null value can't be retained in configuration data, and a null-valued entry isn't created in a bound object when an array in configuration keys skip one or more indices.

Das fehlende Konfigurationselement für Index #3 kann vor dem Binden an die ArrayExample-Instanz von jedem Konfigurationsanbieter bereitgestellt werden, der das Schlüssel-Wert-Paar von Index #3 liest.The missing configuration item for index #3 can be supplied before binding to the ArrayExample instance by any configuration provider that reads the index #3 key/value pair. Beachten Sie die folgende Datei Value3.json aus dem Beispieldownload:Consider the following Value3.json file from the sample download:

{
  "array:entries:3": "value3"
}

Der folgende Code enthält die Konfiguration für Value3.json und das arrayDict Dictionary:The following code includes configuration for Value3.json and the arrayDict Dictionary:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var arrayDict = new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            //              3   Skipped
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile("Value3.json",
                                    optional: false, reloadOnChange: false);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Der folgende Code liest die obige Konfiguration und zeigt die Werte an:The following code reads the preceding configuration and displays the values:

public class ArrayModel : PageModel
{
    private readonly IConfiguration Config;
    public ArrayExample _array { get; private set; }

    public ArrayModel(IConfiguration config)
    {
        Config = config;
    }

    public ContentResult OnGet()
    {
        _array = Config.GetSection("array").Get<ArrayExample>();
        string s = null;

        for (int j = 0; j < _array.Entries.Length; j++)
        {
            s += $"Index: {j}  Value:  {_array.Entries[j]} \n";
        }

        return Content(s);
    }
}

Der obige Code erzeugt die folgende Ausgabe:The preceding code returns the following output:

Index: 0  Value: value0
Index: 1  Value: value1
Index: 2  Value: value2
Index: 3  Value: value3
Index: 4  Value: value4
Index: 5  Value: value5

Benutzerdefinierte Konfigurationsanbieter sind nicht erforderlich, um Arraybindung zu implementieren.Custom configuration providers aren't required to implement array binding.

Benutzerdefinierter KonfigurationsanbieterCustom configuration provider

Die Beispiel-App veranschaulicht, wie ein Standardkonfigurationsanbieter erstellt wird, der Konfigurations-Schlüssel-Wert-Paare aus einer Datenbank mit Entity Framework (EF) liest.The sample app demonstrates how to create a basic configuration provider that reads configuration key-value pairs from a database using Entity Framework (EF).

Der Anbieter weist die folgenden Merkmale auf:The provider has the following characteristics:

  • Die EF-In-Memory-Datenbank wird zu Demonstrationszwecken verwendet.The EF in-memory database is used for demonstration purposes. Um eine Datenbank zu verwenden, die eine Verbindungszeichenfolge benötigt, implementieren Sie einen sekundären ConfigurationBuilder, um die Verbindungszeichenfolge aus einem anderen Konfigurationsanbieter anzugeben.To use a database that requires a connection string, implement a secondary ConfigurationBuilder to supply the connection string from another configuration provider.
  • Der Anbieter liest eine Datenbanktabelle beim Start in die Konfiguration.The provider reads a database table into configuration at startup. Der Anbieter fragt die Datenbank nicht pro Schlüssel ab.The provider doesn't query the database on a per-key basis.
  • 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.Reload-on-change isn't implemented, so updating the database after the app starts has no effect on the app's configuration.

Definieren Sie eine EFConfigurationValue-Entität zum Speichern von Konfigurationswerten in der Datenbank.Define an EFConfigurationValue entity for storing configuration values in the database.

Models/EFConfigurationValue.cs:Models/EFConfigurationValue.cs:

public class EFConfigurationValue
{
    public string Id { get; set; }
    public string Value { get; set; }
}

Fügen Sie EFConfigurationContext hinzu, um die konfigurierten Werte zu speichern und auf diese zugreifen.Add an EFConfigurationContext to store and access the configured values.

EFConfigurationProvider/EFConfigurationContext.cs:EFConfigurationProvider/EFConfigurationContext.cs:

// using Microsoft.EntityFrameworkCore;

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

    public DbSet<EFConfigurationValue> Values { get; set; }
}

Erstellen Sie eine Klasse, die das IConfigurationSource implementiert.Create a class that implements IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs:EFConfigurationProvider/EFConfigurationSource.cs:

// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;

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

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

    public IConfigurationProvider Build(IConfigurationBuilder builder)
    {
        return new EFConfigurationProvider(_optionsAction);
    }
}

Erstellen Sie den benutzerdefinierten Konfigurationsanbieter durch Vererbung von ConfigurationProvider.Create the custom configuration provider by inheriting from ConfigurationProvider. Der Konfigurationsanbieter initialisiert die Datenbank, wenn diese leer ist.The configuration provider initializes the database when it's empty. Da Konfigurationsschlüssel die Groß-/Kleinschreibung nicht beachten, wird das zum Initialisieren der Datenbank verwendete Wörterbuch mit der Vergleichsfunktion, die die Groß-/Kleinschreibung nicht beachtet, erstellt (StringComparer.OrdinalIgnoreCase).Since configuration keys are case-insensitive, the dictionary used to initialize the database is created with the case-insensitive comparer (StringComparer.OrdinalIgnoreCase).

EFConfigurationProvider/EFConfigurationProvider.cs:EFConfigurationProvider/EFConfigurationProvider.cs:

// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;

public class EFConfigurationProvider : ConfigurationProvider
{
    public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
    {
        OptionsAction = optionsAction;
    }

    Action<DbContextOptionsBuilder> OptionsAction { get; }

    public override void Load()
    {
        var builder = new DbContextOptionsBuilder<EFConfigurationContext>();

        OptionsAction(builder);

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

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

    private static IDictionary<string, string> CreateAndSaveDefaultValues(
        EFConfigurationContext dbContext)
    {
        // Quotes (c)2005 Universal Pictures: Serenity
        // https://www.uphe.com/movies/serenity
        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." }
            };

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

        dbContext.SaveChanges();

        return configValues;
    }
}

Mit einer AddEFConfiguration-Erweiterungsmethode kann die Konfigurationsquelle ConfigurationBuilder hinzugefügt werden.An AddEFConfiguration extension method permits adding the configuration source to a ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs:Extensions/EntityFrameworkExtensions.cs:

// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;

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

Der folgende Code veranschaulicht die Verwendung des benutzerdefinierten Anbieters EFConfigurationProvider in Program.cs:The following code shows how to use the custom EFConfigurationProvider in Program.cs:

// using Microsoft.EntityFrameworkCore;

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddEFConfiguration(
                options => options.UseInMemoryDatabase("InMemoryDb"));
        })

Zugriffskonfiguration beim StartAccess configuration in Startup

Der folgende Code zeigt Konfigurationsdaten in Startup-Methoden an:The following code displays configuration data in Startup methods:

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
        Console.WriteLine($"MyKey : {Configuration["MyKey"]}");
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        Console.WriteLine($"Position:Title : {Configuration["Position:Title"]}");

        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

        app.UseHttpsRedirection();
        app.UseStaticFiles();

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Ein Beispiel für den Zugriff auf die Konfiguration mit den Starthilfsmethoden finden Sie unter Anwendungsstart: Hilfsmethoden.For an example of accessing configuration using startup convenience methods, see App startup: Convenience methods.

Zugriffskonfiguration in Razor PagesAccess configuration in Razor Pages

Der folgende Code zeigt Konfigurationsdaten auf einer Razor-Seite an:The following code displays configuration data in a Razor Page:

@page
@model Test5Model
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

Configuration value for 'MyKey': @Configuration["MyKey"]

Im folgenden Code wird MyOptions mit Configure zum Dienstcontainer hinzugefügt und an die Konfiguration gebunden:In the following code, MyOptions is added to the service container with Configure and bound to configuration:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<MyOptions>(Configuration.GetSection("MyOptions"));

    services.AddRazorPages();
}

Das folgende Markup verwendet die @inject Razor Direktive, um die Optionswerte aufzulösen und anzuzeigen:The following markup uses the @inject Razor directive to resolve and display the options values:

@page
@model SampleApp.Pages.Test3Model
@using Microsoft.Extensions.Options
@inject IOptions<MyOptions> optionsAccessor


<p><b>Option1:</b> @optionsAccessor.Value.Option1</p>
<p><b>Option2:</b> @optionsAccessor.Value.Option2</p>

Zugriffskonfiguration in einer MVC-AnsichtsdateiAccess configuration in a MVC view file

Der folgende Code zeigt Konfigurationsdaten in einer MVC-Ansicht an:The following code displays configuration data in a MVC view:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

Configuration value for 'MyKey': @Configuration["MyKey"]

Konfigurieren von Optionen mit einem DelegatenConfigure options with a delegate

In einem Delegaten konfigurierte Optionen überschreiben die in den Konfigurationsanbietern festgelegten Werte.Options configured in a delegate override values set in the configuration providers.

Das Konfigurieren von Optionen mit einem Delegaten wird als Beispiel 2 in der Beispiel-App veranschaulicht.Configuring options with a delegate is demonstrated as Example 2 in the sample app.

Im folgenden Code wird ein dritter IConfigureOptions<TOptions>-Dienst zum Dienstcontainer hinzugefügt.In the following code, an IConfigureOptions<TOptions> service is added to the service container. Er verwendet einen Delegaten, um Werte für MyOptions zu konfigurieren:It uses a delegate to configure values for MyOptions:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<MyOptions>(myOptions =>
    {
        myOptions.Option1 = "Value configured in delegate";
        myOptions.Option2 = 500;
    });

    services.AddRazorPages();
}

Im folgenden Code werden die Optionswerte angezeigt:The following code displays the options values:

public class Test2Model : PageModel
{
    private readonly IOptions<MyOptions> _optionsDelegate;

    public Test2Model(IOptions<MyOptions> optionsDelegate )
    {
        _optionsDelegate = optionsDelegate;
    }

    public ContentResult OnGet()
    {
        return Content($"Option1: {_optionsDelegate.Value.Option1} \n" +
                       $"Option2: {_optionsDelegate.Value.Option2}");
    }
}

Im vorherigen Beispiel wurden die Werte von Option1 und Option2 in appsettings.json angegeben und anschließend vom konfigurierten Delegaten überschrieben.In the preceding example, the values of Option1 and Option2 are specified in appsettings.json and then overridden by the configured delegate.

Hostkonfiguration und App-Konfiguration im VergleichHost versus app configuration

Bevor die App konfiguriert und gestartet wird, wird ein Host konfiguriert und gestartet.Before the app is configured and started, a host is configured and launched. Der Host ist verantwortlich für das Starten der App und das Verwalten der Lebensdauer.The host is responsible for app startup and lifetime management. Die App und der Host werden mit den in diesem Thema beschriebenen Konfigurationsanbietern konfiguriert.Both the app and the host are configured using the configuration providers described in this topic. Schlüssel-Wert-Paare der Hostkonfiguration sind ebenfalls in der globalen App-Konfiguration enthalten.Host configuration key-value pairs are also included in the app's configuration. 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 – Grundlagen.For more information on how the configuration providers are used when the host is built and how configuration sources affect host configuration, see ASP.NET Core – Grundlagen.

StandardhostkonfigurationDefault host configuration

Ausführliche Informationen zur Standardkonfiguration bei Verwendung des Webhosts finden Sie in der ASP.NET Core 2.2-Version dieses Themas.For details on the default configuration when using the Web Host, see the ASP.NET Core 2.2 version of this topic.

  • Die Konfiguration des Hosts wird durch Folgendes festgelegt:Host configuration is provided from:
  • Die Webhost-Standardkonfiguration wird eingerichtet (ConfigureWebHostDefaults):Web Host default configuration is established (ConfigureWebHostDefaults):
    • Als Webserver wird Kestrel verwendet und mithilfe der Konfigurationsanbieter der App konfiguriert.Kestrel is used as the web server and configured using the app's configuration providers.
    • Fügen Sie Middleware zum Filtern von Hosts hinzu.Add Host Filtering Middleware.
    • Fügen Sie Middleware für weitergeleitete Header hinzu, wenn die Umgebungsvariable ASPNETCORE_FORWARDEDHEADERS_ENABLED auf true festgelegt ist.Add Forwarded Headers Middleware if the ASPNETCORE_FORWARDEDHEADERS_ENABLED environment variable is set to true.
    • Aktivieren Sie die IIS-Integration.Enable IIS integration.

Sonstige KonfigurationOther configuration

Dieses Thema bezieht sich nur auf App-Konfigurationen.This topic only pertains to app configuration. Andere Aspekte des Ausführens und Hostings von ASP.NET Core-Apps werden mithilfe von Konfigurationsdateien konfiguriert, die in diesem Thema nicht behandelt werden:Other aspects of running and hosting ASP.NET Core apps are configured using configuration files not covered in this topic:

  • launch.json/launchSettings.json sind Toolkonfigurationsdateien für die Entwicklungsumgebung, die hier beschrieben werden:launch.json/launchSettings.json are tooling configuration files for the Development environment, described:
  • web.config ist eine Serverkonfigurationsdatei, die in den folgenden Themen beschrieben wird:web.config is a server configuration file, described in the following topics:

Umgebungsvariablen, die in der Datei launchSettings.json festgelegt sind, überschreiben diejenigen, die in der Systemumgebung festgelegt sind.Environment variables set in launchSettings.json override those set in the system environment.

Weitere Informationen zum Migrieren der App-Konfiguration aus früheren Versionen von ASP.NET finden Sie unter Migrieren von ASP.NET zu ASP.NET Core.For more information on migrating app configuration from earlier versions of ASP.NET, see Migrieren von ASP.NET zu ASP.NET Core.

Hinzufügen von Konfigurationen aus einer externen AssemblyAdd configuration from an external 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.An IHostingStartup implementation allows adding enhancements to an app at startup from an external assembly outside of the app's Startup class. Weitere Informationen finden Sie unter Verwenden von Hostingstartassemblys in ASP.NET Core.For more information, see Verwenden von Hostingstartassemblys in ASP.NET Core.

Zusätzliche RessourcenAdditional resources

Die App-Konfiguration in ASP.NET Core basiert auf Schlüssel-Wert-Paaren, die von Konfigurationsanbietern erstellt wurden.App configuration in ASP.NET Core is based on key-value pairs established by configuration providers. Konfigurationsanbieter lesen Konfigurationsdaten in Schlüssel-Wert-Paare aus verschiedenen Konfigurationsquellen:Configuration providers read configuration data into key-value pairs from a variety of configuration sources:

  • Azure Key VaultAzure Key Vault
  • Azure App ConfigurationAzure App Configuration
  • BefehlszeilenargumenteCommand-line arguments
  • Benutzerdefinierte Anbieter (installiert oder erstellt)Custom providers (installed or created)
  • VerzeichnisdateienDirectory files
  • UmgebungsvariablenEnvironment variables
  • Speicherinterne .NET ObjekteIn-memory .NET objects
  • EinstellungsdateienSettings files

Konfigurationspakete für gängige Konfigurationsanbieterszenarien (Microsoft.Extensions.Configuration) sind im Microsoft.AspNetCore.App-Metapaket enthalten.Configuration packages for common configuration provider scenarios (Microsoft.Extensions.Configuration) are included in the Microsoft.AspNetCore.App metapackage.

Codebeispiele, die den Microsoft.Extensions.Configuration-Namespace befolgen und in der Beispiel-App verwenden:Code examples that follow and in the sample app use the Microsoft.Extensions.Configuration namespace:

using Microsoft.Extensions.Configuration;

Das Optionsmuster ist eine Erweiterung der in diesem Thema beschriebenen Konfigurationskonzepte.The options pattern is an extension of the configuration concepts described in this topic. Optionen verwenden Klassen, um Gruppen von zusammengehörigen Einstellungen darzustellen.Options use classes to represent groups of related settings. Weitere Informationen finden Sie unter Optionsmuster in ASP.NET Core.For more information, see Optionsmuster in ASP.NET Core.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)View or download sample code (how to download)

Hostkonfiguration und App-Konfiguration im VergleichHost versus app configuration

Bevor die App konfiguriert und gestartet wird, wird ein Host konfiguriert und gestartet.Before the app is configured and started, a host is configured and launched. Der Host ist verantwortlich für das Starten der App und das Verwalten der Lebensdauer.The host is responsible for app startup and lifetime management. Die App und der Host werden mit den in diesem Thema beschriebenen Konfigurationsanbietern konfiguriert.Both the app and the host are configured using the configuration providers described in this topic. Schlüssel-Wert-Paare der Hostkonfiguration sind ebenfalls in der globalen App-Konfiguration enthalten.Host configuration key-value pairs are also included in the app's configuration. 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 – Grundlagen.For more information on how the configuration providers are used when the host is built and how configuration sources affect host configuration, see ASP.NET Core – Grundlagen.

Sonstige KonfigurationOther configuration

Dieses Thema bezieht sich nur auf App-Konfigurationen.This topic only pertains to app configuration. Andere Aspekte des Ausführens und Hostings von ASP.NET Core-Apps werden mithilfe von Konfigurationsdateien konfiguriert, die in diesem Thema nicht behandelt werden:Other aspects of running and hosting ASP.NET Core apps are configured using configuration files not covered in this topic:

  • launch.json/launchSettings.json sind Toolkonfigurationsdateien für die Entwicklungsumgebung, die hier beschrieben werden:launch.json/launchSettings.json are tooling configuration files for the Development environment, described:
  • web.config ist eine Serverkonfigurationsdatei, die in den folgenden Themen beschrieben wird:web.config is a server configuration file, described in the following topics:

Weitere Informationen zum Migrieren der App-Konfiguration aus früheren Versionen von ASP.NET finden Sie unter Migrieren von ASP.NET zu ASP.NET Core.For more information on migrating app configuration from earlier versions of ASP.NET, see Migrieren von ASP.NET zu ASP.NET Core.

StandardkonfigurationDefault configuration

Web-Apps, die auf den dotnet new-Vorlagen von ASP.NET Core basieren, rufen beim Erstellen eines Hosts CreateDefaultBuilder auf.Web apps based on the ASP.NET Core dotnet new templates call CreateDefaultBuilder when building a host. CreateDefaultBuilder legt die Standardkonfiguration für die App in der folgenden Reihenfolge fest:CreateDefaultBuilder provides default configuration for the app in the following order:

Folgendes gilt für Apps, die den Webhost verwenden.The following applies to apps using the Web Host. Ausführliche Informationen zur Standardkonfiguration bei Verwendung des generischen Hosts finden Sie in der neuesten Version dieses Themas.For details on the default configuration when using the Generic Host, see the latest version of this topic.

SicherheitSecurity

Wenden Sie die folgenden Verfahren an, um vertrauliche Konfigurationsdaten zu schützen:Adopt the following practices to secure sensitive configuration data:

  • Speichern Sie nie Kennwörter oder andere vertrauliche Daten im Konfigurationsanbietercode oder in Nur-Text-Konfigurationsdateien.Never store passwords or other sensitive data in configuration provider code or in plain text configuration files.
  • Verwenden Sie keine Produktionsgeheimnisse in Entwicklungs- oder Testumgebungen.Don't use production secrets in development or test environments.
  • Geben Sie Geheimnisse außerhalb des Projekts an, damit sie nicht versehentlich in ein Quellcoderepository übernommen werden können.Specify secrets outside of the project so that they can't be accidentally committed to a source code repository.

Weitere Informationen finden Sie unter den folgenden Themen:For more information, see the following topics:

Azure Key Vault speichert App-Geheimnisse für ASP.NET Core-Apps auf sichere Weise.Azure Key Vault safely stores app secrets for ASP.NET Core apps. Weitere Informationen finden Sie unter Azure Key Vault Konfigurations Anbieters in ASP.net Core.For more information, see Azure Key Vault Konfigurations Anbieters in ASP.net Core.

Hierarchische KonfigurationsdatenHierarchical configuration data

Die Konfigurations-API kann hierarchische Konfigurationsdaten erhalten, indem sie die hierarchischen Daten mit einem Trennzeichen in den Konfigurationsschlüsseln vereinfacht.The Configuration API is capable of maintaining hierarchical configuration data by flattening the hierarchical data with the use of a delimiter in the configuration keys.

Die folgende JSON-Datei enthält vier Schlüssel in einer strukturierten Hierarchie von zwei Abschnitten:In the following JSON file, four keys exist in a structured hierarchy of two sections:

{
  "section0": {
    "key0": "value",
    "key1": "value"
  },
  "section1": {
    "key0": "value",
    "key1": "value"
  }
}

Wenn die Datei in die Konfiguration gelesen wird, werden eindeutige Schlüssel erstellt, um die ursprüngliche hierarchische Datenstruktur der Konfigurationsquelle zu erhalten.When the file is read into configuration, unique keys are created to maintain the original hierarchical data structure of the configuration source. Die Abschnitte und Schlüssel werden mithilfe eines Doppelpunkts (:) vereinfacht, um die Originalstruktur zu erhalten:The sections and keys are flattened with the use of a colon (:) to maintain the original structure:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:key0section1:key0
  • section1:key1section1:key1

Mit den Methoden GetSection und GetChildren können Abschnitte und untergeordnete Abschnittelemente in den Konfigurationsdaten isoliert werden.GetSection and GetChildren methods are available to isolate sections and children of a section in the configuration data. Diese Methoden werden später im Abschnitt GetSection, GetChildren und Exists beschrieben.These methods are described later in GetSection, GetChildren, and Exists.

KonventionenConventions

Quellen und AnbieterSources and providers

Beim Starten der Anwendung werden Konfigurationsquellen in der Reihenfolge gelesen, in der ihre Konfigurationsanbieter angegeben sind.At app startup, configuration sources are read in the order that their configuration providers are specified.

Konfigurationsanbieter, die Änderungserkennung implementieren, können Konfigurationen erneut laden, wenn zugrunde liegende Einstellungen geändert werden.Configuration providers that implement change detection have the ability to reload configuration when an underlying setting is changed. Der Dateikonfigurationsanbieter (weiter unten in diesem Thema beschrieben) und der Azure Key Vault-Konfigurationsanbieter implementieren beispielsweise die Änderungserkennung.For example, the File Configuration Provider (described later in this topic) and the Azure Key Vault Configuration Provider implement change detection.

IConfiguration steht im App-Container Abhängigkeitsinjektion zur Verfügung.IConfiguration is available in the app's dependency injection (DI) container. IConfiguration kann in PageModel von Razor Pages oder Controller von MVC eingefügt werden, um die Konfiguration für die Klasse abzurufen.IConfiguration can be injected into a Razor Pages PageModel or MVC Controller to obtain configuration for the class.

In den folgenden Beispielen wird das Feld _config verwendet, um auf Konfigurationswerte zuzugreifen:In the following examples, the _config field is used to access configuration values:

public class IndexModel : PageModel
{
    private readonly IConfiguration _config;

    public IndexModel(IConfiguration config)
    {
        _config = config;
    }
}
public class HomeController : Controller
{
    private readonly IConfiguration _config;

    public HomeController(IConfiguration config)
    {
        _config = config;
    }
}

Konfigurationsanbieter können die Abhängigkeitsinjektion nicht verwenden, weil sie nicht verfügbar ist, wenn sie vom Host eingerichtet werden.Configuration providers can't utilize DI, as it's not available when they're set up by the host.

TastenKeys

Konfigurationsschlüssel entsprechen den folgenden Konventionen:Configuration keys adopt the following conventions:

  • Bei Schlüsseln wird die Groß-/Kleinschreibung nicht beachtet.Keys are case-insensitive. Beispielsweise verweisen ConnectionString und connectionstring auf denselben Schlüssel.For example, ConnectionString and connectionstring are treated as equivalent keys.
  • Wenn ein Wert für denselben Schlüssel von denselben oder unterschiedlichen Konfigurationsanbietern festgelegt wird, wird der zuletzt für den Schlüssel bestimmte Wert verwendet.If a value for the same key is set by the same or different configuration providers, the last value set on the key is the value used. Weitere Informationen zu doppelten JSON-Schlüsseln finden Sie in diesem GitHub-Issue.For more information on duplicate JSON keys, see this GitHub issue.
  • Hierarchische SchlüsselHierarchical keys
    • Innerhalb der Konfigurations-API funktioniert ein Doppelpunkt (:) als Trennzeichen auf allen Plattformen.Within the Configuration API, a colon separator (:) works on all platforms.
    • In Umgebungsvariablen funktioniert ein Doppelpunkt als Trennzeichen ggf. nicht auf allen Plattformen.In environment variables, a colon separator may not work on all platforms. Ein doppelter Unterstrich (__) wird auf allen Plattformen unterstützt und automatisch in einen Doppelpunkt konvertiert.A double underscore (__) is supported by all platforms and is automatically converted into a colon.
    • In Azure Key Vault verwenden hierarchische Schlüssel zwei Bindestriche (--) als Trennzeichen.In Azure Key Vault, hierarchical keys use -- (two dashes) as a separator. Schreiben Sie Code, um die Bindestriche durch einen Doppelpunkt zu ersetzen, wenn die Geheimnisse in die App-Konfiguration geladen werden.Write code to replace the dashes with a colon when the secrets are loaded into the app's configuration.
  • ConfigurationBinder unterstützt das Binden von Arrays an Objekte mit Arrayindizes in Konfigurationsschlüsseln.The ConfigurationBinder supports binding arrays to objects using array indices in configuration keys. Die Arraybindung wird im Abschnitt Binden eines Arrays an eine Klasse beschrieben.Array binding is described in the Bind an array to a class section.

WerteValues

Konfigurationswerte entsprechen den folgenden Konventionen:Configuration values adopt the following conventions:

  • Die Werte sind Zeichenfolgen.Values are strings.
  • NULL-Werte können nicht in einer Konfiguration gespeichert oder an Objekte gebunden werden.Null values can't be stored in configuration or bound to objects.

AnbieterProviders

Die folgende Tabelle zeigt die für ASP.NET Core-Apps verfügbaren Konfigurationsanbieter.The following table shows the configuration providers available to ASP.NET Core apps.

AnbieterProvider Bereitstellung der Konfiguration über…Provides configuration from…
Azure Key Vault-Konfigurationsanbieter (Thema Sicherheit)Azure Key Vault Configuration Provider (Security topics) Azure Key VaultAzure Key Vault
Azure App Configuration-Anbieter (Azure-Dokumentation)Azure App Configuration Provider (Azure documentation) Azure App ConfigurationAzure App Configuration
Befehlszeilen-KonfigurationsanbieterCommand-line Configuration Provider BefehlszeilenparameterCommand-line parameters
Benutzerdefinierter KonfigurationsanbieterCustom configuration provider Benutzerdefinierte QuelleCustom source
Umgebungsvariablen-KonfigurationsanbieterEnvironment Variables Configuration Provider UmgebungsvariablenEnvironment variables
DateikonfigurationsanbieterFile Configuration Provider Dateien (INI, JSON, XML)Files (INI, JSON, XML)
Schlüssel-pro-Datei-KonfigurationsanbieterKey-per-file Configuration Provider VerzeichnisdateienDirectory files
SpeicherkonfigurationsanbieterMemory Configuration Provider In-Memory-SammlungenIn-memory collections
Benutzergeheimnisse (Sicherheitsthemen)User secrets (Security topics) Datei im BenutzerprofilverzeichnisFile in the user profile directory

Konfigurationsquellen werden beim Start in der Reihenfolge gelesen, in der ihre Konfigurationsanbieter angegeben sind.Configuration sources are read in the order that their configuration providers are specified at startup. Die in diesem Thema beschriebenen Konfigurationsanbieter werden in alphabetischer Reihenfolge beschrieben, nicht in der Reihenfolge, in der der Code sie anordnet.The configuration providers described in this topic are described in alphabetical order, not in the order that the code arranges them. 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.Order configuration providers in code to suit the priorities for the underlying configuration sources that the app requires.

Eine typische Konfigurationsanbietersequenz ist:A typical sequence of configuration providers is:

  1. Dateien ( appsettings.json , appsettings.{Environment}.json, wobei {Environment} die aktuelle Hostingumgebung der App ist)Files (appsettings.json, appsettings.{Environment}.json, where {Environment} is the app's current hosting environment)
  2. Azure Key VaultAzure Key Vault
  3. Benutzergeheimnisse (nur Entwicklungsumgebung)User secrets (Development environment only)
  4. UmgebungsvariablenEnvironment variables
  5. BefehlszeilenargumenteCommand-line arguments

In der Regel werden Befehlszeilen-Konfigurationsanbieter in einer Reihe von Anbietern an letzter Stelle positioniert, damit Befehlszeilenargumente die von anderen Anbietern festgelegte Konfiguration überschreiben können.A common practice is to position the Command-line Configuration Provider last in a series of providers to allow command-line arguments to override configuration set by the other providers.

Die vorhergehende Anbieterfolge wird verwendet, wenn Sie einen neuen Host-Generator mit CreateDefaultBuilder initialisieren.The preceding sequence of providers is used when a new host builder is initialized with CreateDefaultBuilder. Weitere Informationen finden Sie im Abschnitt Standardkonfiguration.For more information, see the Default configuration section.

Konfigurieren des Host-Generators mit UseConfigurationConfigure the host builder with UseConfiguration

Um den Host-Generator zu konfigurieren, rufen Sie UseConfiguration mit der Konfiguration für den Host-Generator auf.To configure the host builder, call UseConfiguration on the host builder with the configuration.

public static IWebHostBuilder CreateWebHostBuilder(string[] args)
{
    var dict = new Dictionary<string, string>
    {
        {"MemoryCollectionKey1", "value1"},
        {"MemoryCollectionKey2", "value2"}
    };

    var config = new ConfigurationBuilder()
        .AddInMemoryCollection(dict)
        .Build();

    return WebHost.CreateDefaultBuilder(args)
        .UseConfiguration(config)
        .UseStartup<Startup>();
}

ConfigureAppConfigurationConfigureAppConfiguration

Rufen Sie ConfigureAppConfiguration beim Erstellen des Hosts auf, um die Konfigurationsanbieter der App zusätzlich zu denen anzugeben, die automatisch von CreateDefaultBuilder hinzugefügt werden:Call ConfigureAppConfiguration when building the host to specify the app's configuration providers in addition to those added automatically by CreateDefaultBuilder:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

Überschreiben der vorherigen Konfiguration mit BefehlszeilenargumentenOverride previous configuration with command-line arguments

Um die App-Konfiguration bereitzustellen, die mit Befehlszeilenargumenten überschrieben werden kann, rufen Sie AddCommandLine zuletzt auf:To provide app configuration that can be overridden with command-line arguments, call AddCommandLine last:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    // Call other providers here
    config.AddCommandLine(args);
})

Entfernen von durch CreateDefaultBuilder hinzugefügten AnbieternRemove providers added by CreateDefaultBuilder

Rufen Sie zunächst Clear in IConfigurationBuilder.Sources auf, um die durch CreateDefaultBuilder hinzugefügten Anbieter zu entfernen:To remove the providers added by CreateDefaultBuilder, call Clear on the IConfigurationBuilder.Sources first:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();
    // Add providers here
})

Verarbeiten der Konfiguration während des App-StartsConsume configuration during app startup

Die für die App in der ConfigureAppConfiguration-Methode angegebene Konfiguration, einschließlich Startup.ConfigureServices, ist während des Starts der App verfügbar.Configuration supplied to the app in ConfigureAppConfiguration is available during the app's startup, including Startup.ConfigureServices. Weitere Informationen finden Sie im Abschnitt Hinzufügen von Konfigurationen aus einer externen Assembly.For more information, see the Access configuration during startup section.

Befehlszeilen-KonfigurationsanbieterCommand-line Configuration Provider

CommandLineConfigurationProvider lädt während der Laufzeit die Konfiguration aus den Schlüssel-Wert-Paaren des Befehlszeilenarguments.The CommandLineConfigurationProvider loads configuration from command-line argument key-value pairs at runtime.

Um die Befehlszeilenkonfiguration zu aktivieren, wird die AddCommandLine-Erweiterungsmethode für eine Instanz von ConfigurationBuilder aufgerufen.To activate command-line configuration, the AddCommandLine extension method is called on an instance of ConfigurationBuilder.

AddCommandLine wird automatisch aufgerufen, wenn CreateDefaultBuilder(string []) aufgerufen wird.AddCommandLine is automatically called when CreateDefaultBuilder(string []) is called. Weitere Informationen finden Sie im Abschnitt Standardkonfiguration.For more information, see the Default configuration section.

CreateDefaultBuilder lädt außerdem:CreateDefaultBuilder also loads:

  • Optionale Konfiguration aus den Dateien appsettings.json und appsettings.{Environment}.jsonOptional configuration from appsettings.json and appsettings.{Environment}.json files.
  • Benutzergeheimnisse in der Entwicklungsumgebung.User secrets in the Development environment.
  • Umgebungsvariablen.Environment variables.

CreateDefaultBuilder fügt den Befehlszeilen-Konfigurationsanbieter zuletzt hinzu.CreateDefaultBuilder adds the Command-line Configuration Provider last. Während der Laufzeit übergebene Befehlszeilenargumente überschreiben die von anderen Anbietern festgelegte Konfiguration.Command-line arguments passed at runtime override configuration set by the other providers.

CreateDefaultBuilder wird aktiv, wenn der Host erstellt wurde.CreateDefaultBuilder acts when the host is constructed. Deswegen kann die durch CreateDefaultBuilder aktivierte Befehlszeilenkonfiguration die Konfiguration des Hosts beeinflussen.Therefore, command-line configuration activated by CreateDefaultBuilder can affect how the host is configured.

Für Apps, die auf den ASP.NET Core-Vorlagen basieren, wurde AddCommandLine bereits von CreateDefaultBuilder aufgerufen.For apps based on the ASP.NET Core templates, AddCommandLine has already been called by CreateDefaultBuilder. Um weitere Konfigurationsanbieter hinzuzufügen und die Möglichkeit einer Überschreibung der Konfiguration dieser Anbieter durch Befehlszeilenargumente beizubehalten, rufen Sie die zusätzlichen Anbieter in ConfigureAppConfiguration und zuletzt AddCommandLine auf.To add additional configuration providers and maintain the ability to override configuration from those providers with command-line arguments, call the app's additional providers in ConfigureAppConfiguration and call AddCommandLine last.

.ConfigureAppConfiguration((hostingContext, config) =>
{
    // Call other providers here
    config.AddCommandLine(args);
})

BeispielExample

Die Beispiel-App nutzt zum Erstellen des Hosts die statische Hilfsmethode CreateDefaultBuilder, die einen Aufruf von AddCommandLine enthält.The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes a call to AddCommandLine.

  1. Öffnen Sie im Projektverzeichnis eine Eingabeaufforderung.Open a command prompt in the project's directory.
  2. Geben Sie ein Befehlszeilenargument für den dotnet run-Befehl an, dotnet run CommandLineKey=CommandLineValue.Supply a command-line argument to the dotnet run command, dotnet run CommandLineKey=CommandLineValue.
  3. Wenn die App ausgeführt wird, öffnen Sie einen Browser für die App unter http://localhost:5000.After the app is running, open a browser to the app at http://localhost:5000.
  4. Beachten Sie, dass die Ausgabe das Schlüssel-Wert-Paar für das an dotnet run übergebene Konfigurations-Befehlszeilenargument enthält.Observe that the output contains the key-value pair for the configuration command-line argument provided to dotnet run.

ArgumenteArguments

Der Wert muss einem Gleichheitszeichen (=) folgen, oder der Schlüssel muss ein Präfix (-- oder /) haben, wenn der Wert einem Leerzeichen folgt.The value must follow an equals sign (=), or the key must have a prefix (-- or /) when the value follows a space. Der Wert ist nicht erforderlich, wenn ein Gleichheitszeichen verwendet wird (z. B. CommandLineKey=).The value isn't required if an equals sign is used (for example, CommandLineKey=).

SchlüsselpräfixKey prefix BeispielExample
Ohne PräfixNo prefix CommandLineKey1=value1
Zwei Gedankenstriche (--)Two dashes (--) --CommandLineKey2=value2, --CommandLineKey2 value2--CommandLineKey2=value2, --CommandLineKey2 value2
Schrägstrich (/)Forward slash (/) /CommandLineKey3=value3, /CommandLineKey3 value3/CommandLineKey3=value3, /CommandLineKey3 value3

Kombinieren Sie in einem Befehl nicht Schlüssel-Wert-Paare, die ein Gleichheitszeichen verwenden, mit Schlüssel-Wert-Paaren, die ein Leerzeichen verwenden.Within the same command, don't mix command-line argument key-value pairs that use an equals sign with key-value pairs that use a space.

Beispielbefehle:Example commands:

dotnet run CommandLineKey1=value1 --CommandLineKey2=value2 /CommandLineKey3=value3
dotnet run --CommandLineKey1 value1 /CommandLineKey2 value2
dotnet run CommandLineKey1= CommandLineKey2=value2

SwitchmappingsSwitch mappings

Switchmappings erlauben das Angeben einer Logik zum Ersetzen von Schlüsselnamen.Switch mappings allow key name replacement logic. Wenn Sie die Konfiguration manuell mit ConfigurationBuilder erstellen, können Sie ein Wörterbuch der Switchersetzungen für die AddCommandLine-Methode bereitstellen.When manually building configuration with a ConfigurationBuilder, provide a dictionary of switch replacements to the AddCommandLine method.

Wenn das Switchmappingwörterbuch verwendet wird, wird das Wörterbuch für Schlüssel, die dem von einem Befehlszeilenargument angegebenen Schlüssel entsprechen, überprüft.When the switch mappings dictionary is used, the dictionary is checked for a key that matches the key provided by a command-line argument. Wenn der Befehlszeilenschlüssel im Wörterbuch gefunden wird, wird der Wörterbuchwert (der Schlüsselersatz) zum Festlegen des Schlüssel-Wert-Paares in der App-Konfiguration zurückgegeben.If the command-line key is found in the dictionary, the dictionary value (the key replacement) is passed back to set the key-value pair into the app's configuration. Ein Switchmapping ist für jeden Befehlszeilenschlüssel erforderlich, dem ein einzelner Gedankenstrich (-) vorangestellt ist.A switch mapping is required for any command-line key prefixed with a single dash (-).

Regeln für Schlüssel von Switchmappingwörterbüchern:Switch mappings dictionary key rules:

  • Switchmappings müssen mit einem Gedankenstrich (-) oder zwei Gedankenstrichen (--) beginnen.Switches must start with a dash (-) or double-dash (--).
  • Das Switchmappingwörterbuch darf keine doppelten Schlüssel enthalten.The switch mappings dictionary must not contain duplicate keys.

Erstellen Sie ein Switchmappingwörterbuch.Create a switch mappings dictionary. Im folgenden Beispiel werden zwei Switchmappings erstellt:In the following example, two switch mappings are created:

public static readonly Dictionary<string, string> _switchMappings = 
    new Dictionary<string, string>
    {
        { "-CLKey1", "CommandLineKey1" },
        { "-CLKey2", "CommandLineKey2" }
    };

Wenn der Host erstellt wird, rufen Sie AddCommandLine mit dem Switchmappingwörterbuch auf:When the host is built, call AddCommandLine with the switch mappings dictionary:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddCommandLine(args, _switchMappings);
})

Bei Apps, die Switchmappings verwenden, sollten im CreateDefaultBuilder-Aufruf keine Argumente übergeben werden.For apps that use switch mappings, the call to CreateDefaultBuilder shouldn't pass arguments. Der Aufruf von CreateDefaultBuilder der AddCommandLine-Methode umfasst keine zugeordneten Switches, und das Switchmappingwörterbuch kann nicht an CreateDefaultBuilder übergeben werden.The CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and there's no way to pass the switch mapping dictionary to CreateDefaultBuilder. Die Lösung besteht nicht darin, die Argumente an CreateDefaultBuilder zu übergeben, sondern der Methode AddCommandLine der ConfigurationBuilder-Methode zu erlauben, sowohl die Argumente als auch das Switchmappingwörterbuch zu verarbeiten.The solution isn't to pass the arguments to CreateDefaultBuilder but instead to allow the ConfigurationBuilder method's AddCommandLine method to process both the arguments and the switch mapping dictionary.

Das erstellte Switchmappingwörterbuch enthält die in der folgenden Tabelle gezeigten Daten.After the switch mappings dictionary is created, it contains the data shown in the following table.

KeyKey WertValue
-CLKey1 CommandLineKey1
-CLKey2 CommandLineKey2

Wenn Switches zugeordnete Schlüssel beim Start der App verwendet werden, erhält die Konfiguration den Konfigurationswert auf dem vom Wörterbuch bereitgestellten Schlüssel:If the switch-mapped keys are used when starting the app, configuration receives the configuration value on the key supplied by the dictionary:

dotnet run -CLKey1=value1 -CLKey2=value2

Nach dem Ausführen des obigen Befehls enthält die Konfiguration die in der folgenden Tabelle angegebenen Werte.After running the preceding command, configuration contains the values shown in the following table.

KeyKey WertValue
CommandLineKey1 value1
CommandLineKey2 value2

Umgebungsvariablen-KonfigurationsanbieterEnvironment Variables Configuration Provider

EnvironmentVariablesConfigurationProvider lädt während der Laufzeit die Konfiguration aus den Schlüssel-Wert-Paaren der Umgebungsvariablen.The EnvironmentVariablesConfigurationProvider loads configuration from environment variable key-value pairs at runtime.

Um die Umgebungsvariablenkonfiguration zu aktivieren, rufen Sie die AddEnvironmentVariables-Erweiterungsmethode auf einer ConfigurationBuilder-Instanz auf.To activate environment variables configuration, call the AddEnvironmentVariables extension method on an instance of ConfigurationBuilder.

Das Trennzeichen : funktioniert nicht auf allen Plattformen mit den hierarchischen Schlüsseln von Umgebungsvariablen.The : separator doesn't work with environment variable hierarchical keys on all platforms. Der doppelte Unterstrich __:__, the double underscore, is:

  • wird auf allen Plattformen unterstützt.Supported by all platforms. Das Trennzeichen : wird beispielsweise nicht von Bash unterstützt, __ hingegen schon.For example, the : separator is not supported by Bash, but __ is.
  • automatisch durch : ersetzt.Automatically replaced by a :

Azure App Service ermöglicht Ihnen Umgebungsvariablen im Azure-Portal festzulegen, die die App-Konfiguration mit dem Konfigurationsanbieter für Umgebungsvariablen überschreiben können.Azure App Service permits setting environment variables in the Azure Portal that can override app configuration using the Environment Variables Configuration Provider. Weitere Informationen finden Sie unter Azure-Apps: Überschreiben der App-Konfiguration im Azure-Portal.For more information, see Azure Apps: Override app configuration using the Azure Portal.

AddEnvironmentVariables wird zum Laden von Umgebungsvariablen verwendet, die das Präfix ASPNETCORE_ für die Hostkonfiguration aufweisen, wenn ein neuer Host-Generator mit dem Webhost initialisiert und CreateDefaultBuilder aufgerufen wird.AddEnvironmentVariables is used to load environment variables prefixed with ASPNETCORE_ for host configuration when a new host builder is initialized with the Web Host and CreateDefaultBuilder is called. Weitere Informationen finden Sie im Abschnitt Standardkonfiguration.For more information, see the Default configuration section.

CreateDefaultBuilder lädt außerdem:CreateDefaultBuilder also loads:

  • App-Konfiguration über Umgebungsvariablen ohne Präfix durch Aufruf von AddEnvironmentVariables ohne Präfix.App configuration from unprefixed environment variables by calling AddEnvironmentVariables without a prefix.
  • Optionale Konfiguration aus den Dateien appsettings.json und appsettings.{Environment}.jsonOptional configuration from appsettings.json and appsettings.{Environment}.json files.
  • Benutzergeheimnisse in der Entwicklungsumgebung.User secrets in the Development environment.
  • BefehlszeilenargumentenCommand-line arguments.

Der Umgebungsvariablen-Konfigurationsanbieter wird aufgerufen, nachdem die Konfiguration aus Benutzergeheimnissen und appsettings-Dateien erstellt wurde.The Environment Variables Configuration Provider is called after configuration is established from user secrets and appsettings files. Das Aufrufen des Anbieters an dieser Stelle ermöglicht den während der Laufzeit gelesenen Umgebungsvariablen, die von Benutzergeheimnissen und appsettings-Dateien festgelegte Konfiguration zu überschreiben.Calling the provider in this position allows the environment variables read at runtime to override configuration set by user secrets and appsettings files.

Wenn Sie App-Konfigurationen aus zusätzlichen Umgebungsvariablen bereitstellen müssen, rufen Sie die zusätzlichen Anbieter der App in ConfigureAppConfiguration auf, und rufen Sie AddEnvironmentVariables mit dem Präfix auf:To provide app configuration from additional environment variables, call the app's additional providers in ConfigureAppConfiguration and call AddEnvironmentVariables with the prefix:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddEnvironmentVariables(prefix: "PREFIX_");
})

Rufen Sie AddEnvironmentVariables zuletzt auf, um Umgebungsvariablen mit dem angegebenen Präfix zuzulassen, um Werte von anderen Anbietern zu überschreiben.Call AddEnvironmentVariables last to allow environment variables with the given prefix to override values from other providers.

BeispielExample

Die Beispiel-App nutzt zum Erstellen des Hosts die statische Hilfsmethode CreateDefaultBuilder, die einen Aufruf von AddEnvironmentVariables enthält.The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes a call to AddEnvironmentVariables.

  1. Führen Sie die Beispiel-App aus.Run the sample app. Öffnen Sie einen Browser für die App unter http://localhost:5000.Open a browser to the app at http://localhost:5000.
  2. Beachten Sie, dass die Ausgabe das Schlüssel-Wert-Paar für die Umgebungsvariable ENVIRONMENT enthält.Observe that the output contains the key-value pair for the environment variable ENVIRONMENT. Der Wert entspricht der Umgebung, in der die App ausgeführt wird. In der Regel ist das Development bei lokaler Ausführung.The value reflects the environment in which the app is running, typically Development when running locally.

Um die Liste der von der App gerenderten Umgebungsvariablen kurz zu halten, filtert die App Umgebungsvariablen.To keep the list of environment variables rendered by the app short, the app filters environment variables. Weitere Informationen finden Sie in der Datei Pages/Index.cshtml.cs der Beispiel-App.See the sample app's Pages/Index.cshtml.cs file.

Wenn Sie alle für die App verfügbaren Umgebungsvariablen verfügbar machen möchten, ändern Sie FilteredConfiguration in Pages/Index.cshtml.cs wie folgt:To expose all of the environment variables available to the app, change the FilteredConfiguration in Pages/Index.cshtml.cs to the following:

FilteredConfiguration = _config.AsEnumerable();

PräfixePrefixes

Umgebungsvariablen, die in die Konfiguration der App geladen werden, werden gefiltert, wenn Sie ein Präfix für die Methode AddEnvironmentVariables angeben.Environment variables loaded into the app's configuration are filtered when supplying a prefix to the AddEnvironmentVariables method. Um beispielsweise Umgebungsvariablen nach dem Präfix CUSTOM_ zu filtern, geben Sie das Präfix für den Konfigurationsanbieter an:For example, to filter environment variables on the prefix CUSTOM_, supply the prefix to the configuration provider:

var config = new ConfigurationBuilder()
    .AddEnvironmentVariables("CUSTOM_")
    .Build();

Das Präfix wird beim Erstellen der Schlüssel-Wert-Paare der Konfiguration entfernt.The prefix is stripped off when the configuration key-value pairs are created.

Beim Erstellen des Host-Generators wird die Hostkonfiguration durch Umgebungsvariablen bereitgestellt.When the host builder is created, host configuration is provided by environment variables. Weitere Informationen zu dem Präfix, das für diese Umgebungsvariablen verwendet wird, finden Sie im Abschnitt Standardkonfiguration.For more information on the prefix used for these environment variables, see the Default configuration section.

Präfixe für VerbindungszeichenfolgenConnection string prefixes

Die Konfigurations-API verfügt über spezielle Verarbeitungsregeln für vier Umgebungsvariablen für Verbindungszeichenfolgen, die beim Konfigurieren von Azure-Verbindungszeichenfolgen für die App-Umgebung verwendet werden.The Configuration API has special processing rules for four connection string environment variables involved in configuring Azure connection strings for the app environment. Umgebungsvariablen mit Präfixen, die in der Tabelle aufgeführt werden, werden in die App geladen, wenn für AddEnvironmentVariables kein Präfix angegeben wird.Environment variables with the prefixes shown in the table are loaded into the app if no prefix is supplied to AddEnvironmentVariables.

Präfix für VerbindungszeichenfolgenConnection string prefix AnbieterProvider
CUSTOMCONNSTR_ Benutzerdefinierter AnbieterCustom provider
MYSQLCONNSTR_ MySQLMySQL
SQLAZURECONNSTR_ Azure SQL-DatenbankAzure SQL Database
SQLCONNSTR_ SQL ServerSQL Server

Wenn eine Umgebungsvariable entdeckt und mit einem der vier Präfixe aus der Tabelle in die Konfiguration geladen wird, tritt Folgendes ein:When an environment variable is discovered and loaded into configuration with any of the four prefixes shown in the table:

  • Der Konfigurationsschlüssel wird durch Entfernen des Umgebungsvariablenpräfixes und Hinzufügen eines Konfigurationsschlüsselabschnitts (ConnectionStrings) erstellt.The configuration key is created by removing the environment variable prefix and adding a configuration key section (ConnectionStrings).
  • 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).A new configuration key-value pair is created that represents the database connection provider (except for CUSTOMCONNSTR_, which has no stated provider).
UmgebungsvariablenschlüsselEnvironment variable key Konvertierter KonfigurationsschlüsselConverted configuration key AnbieterkonfigurationseintragProvider configuration entry
CUSTOMCONNSTR_{KEY} ConnectionStrings:{KEY} Konfigurationseintrag wurde nicht erstellt.Configuration entry not created.
MYSQLCONNSTR_{KEY} ConnectionStrings:{KEY} Schlüssel: ConnectionStrings:{KEY}_ProviderName:Key: ConnectionStrings:{KEY}_ProviderName:
Wert: MySql.Data.MySqlClientValue: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY} ConnectionStrings:{KEY} Schlüssel: ConnectionStrings:{KEY}_ProviderName:Key: ConnectionStrings:{KEY}_ProviderName:
Wert: System.Data.SqlClientValue: System.Data.SqlClient
SQLCONNSTR_{KEY} ConnectionStrings:{KEY} Schlüssel: ConnectionStrings:{KEY}_ProviderName:Key: ConnectionStrings:{KEY}_ProviderName:
Wert: System.Data.SqlClientValue: System.Data.SqlClient

BeispielExample

Eine benutzerdefinierte Umgebungsvariable einer Verbindungszeichenfolge wird auf dem Server erstellt:A custom connection string environment variable is created on the server:

  • Name: CUSTOMCONNSTR_ReleaseDBName: CUSTOMCONNSTR_ReleaseDB
  • Wert: Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=TrueValue: Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True

Wenn IConfiguration eingefügt und einem Feld namens _config zugewiesen wird, sieht der Wert so aus:If IConfiguration is injected and assigned to a field named _config, read the value:

_config["ConnectionStrings:ReleaseDB"]

DateikonfigurationsanbieterFile Configuration Provider

FileConfigurationProvider ist die Basisklasse für das Laden einer Konfiguration aus dem Dateisystem.FileConfigurationProvider is the base class for loading configuration from the file system. Die folgenden Konfigurationsanbieter sind für bestimmte Dateitypen vorgesehen:The following configuration providers are dedicated to specific file types:

INI-KonfigurationsanbieterINI Configuration Provider

IniConfigurationProvider lädt während der Laufzeit die Konfiguration aus den Schlüssel-Wert-Paaren der INI-Datei.The IniConfigurationProvider loads configuration from INI file key-value pairs at runtime.

Um die INI-Dateikonfiguration zu aktivieren, rufen Sie die AddIniFile-Erweiterungsmethode auf einer ConfigurationBuilder-Instanz auf.To activate INI file configuration, call the AddIniFile extension method on an instance of ConfigurationBuilder.

Der Doppelpunkt kann in einer INI-Dateikonfiguration als Abschnittstrennzeichen verwendet werden.The colon can be used to as a section delimiter in INI file configuration.

Überladungen geben Folgendes an:Overloads permit specifying:

  • Ob die Datei optional istWhether the file is optional.
  • Ob die Konfiguration bei Dateiänderungen neu geladen wirdWhether the configuration is reloaded if the file changes.
  • Dass mit IFileProvider auf die Datei zugegriffen wirdThe IFileProvider used to access the file.

Rufen Sie ConfigureAppConfiguration beim Erstellen des Hosts auf, um die Konfiguration der App anzugeben:Call ConfigureAppConfiguration when building the host to specify the app's configuration:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddIniFile(
        "config.ini", optional: true, reloadOnChange: true);
})

Ein allgemeines Beispiel einer INI-Konfigurationsdatei:A generic example of an INI configuration file:

[section0]
key0=value
key1=value

[section1]
subsection:key=value

[section2:subsection0]
key=value

[section2:subsection1]
key=value

Die vorherige Konfigurationsdatei lädt die folgenden Schlüssel mit value:The previous configuration file loads the following keys with value:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:subsection:keysection1:subsection:key
  • section2:subsection0:keysection2:subsection0:key
  • section2:subsection1:keysection2:subsection1:key

JSON-KonfigurationsanbieterJSON Configuration Provider

JsonConfigurationProvider lädt während der Laufzeit die Konfiguration aus den Schlüssel-Wert-Paaren der JSON-Datei.The JsonConfigurationProvider loads configuration from JSON file key-value pairs during runtime.

Um die JSON-Dateikonfiguration zu aktivieren, rufen Sie die AddJsonFile-Erweiterungsmethode auf einer ConfigurationBuilder-Instanz auf.To activate JSON file configuration, call the AddJsonFile extension method on an instance of ConfigurationBuilder.

Überladungen geben Folgendes an:Overloads permit specifying:

  • Ob die Datei optional istWhether the file is optional.
  • Ob die Konfiguration bei Dateiänderungen neu geladen wirdWhether the configuration is reloaded if the file changes.
  • Dass mit IFileProvider auf die Datei zugegriffen wirdThe IFileProvider used to access the file.

AddJsonFile wird automatisch zweimal aufgerufen, wenn Sie einen neuen Host-Generator mit CreateDefaultBuilder initialisieren.AddJsonFile is automatically called twice when a new host builder is initialized with CreateDefaultBuilder. Die Methode wird aufgerufen, um die Konfiguration aus folgenden Dateien zu laden:The method is called to load configuration from:

  • appsettings.json : Diese Datei wird zuerst gelesen.appsettings.json: This file is read first. Die Umgebungsversion der Datei kann die Werte der Datei appsettings.json überschreiben.The environment version of the file can override the values provided by the appsettings.json file.
  • appsettings.{Environment}.json: Die Umgebungsversion der Datei wird basierend auf IHostingEnvironment.EnvironmentName geladen.appsettings.{Environment}.json: The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName.

Weitere Informationen finden Sie im Abschnitt Standardkonfiguration.For more information, see the Default configuration section.

CreateDefaultBuilder lädt außerdem:CreateDefaultBuilder also loads:

  • Umgebungsvariablen.Environment variables.
  • Benutzergeheimnisse in der Entwicklungsumgebung.User secrets in the Development environment.
  • BefehlszeilenargumentenCommand-line arguments.

Der JSON-Konfigurationsanbieter wird zuerst eingerichtet.The JSON Configuration Provider is established first. Daher überschreiben Benutzergeheimnisse, Umgebungsvariablen und Befehlszeilenargumente die von appsettings-Dateien festgelegte Konfiguration.Therefore, user secrets, environment variables, and command-line arguments override configuration set by the appsettings files.

Rufen Sie ConfigureAppConfiguration beim Erstellen des Hosts auf, um Konfiguration der App für andere Dateien als appsettings.json und appsettings.{Environment}.json anzugeben:Call ConfigureAppConfiguration when building the host to specify the app's configuration for files other than appsettings.json and appsettings.{Environment}.json:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddJsonFile(
        "config.json", optional: true, reloadOnChange: true);
})

BeispielExample

Die Beispiel-App nutzt zum Erstellen des Hosts die statische Hilfsmethode CreateDefaultBuilder, die zwei Aufrufe von AddJsonFile enthält:The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes two calls to AddJsonFile:

  • Der erste Aufruf auf AddJsonFile lädt die Konfiguration aus appsettings.json :The first call to AddJsonFile loads configuration from appsettings.json:

    {
      "Logging": {
        "LogLevel": {
          "Default": "Warning"
        }
      },
      "AllowedHosts": "*"
    }
    
  • Der zweite Aufruf auf AddJsonFile lädt die Konfiguration aus appsettings.{Environment}.json.The second call to AddJsonFile loads configuration from appsettings.{Environment}.json. Die folgende Datei wird für appsettings.Development.json in der Beispiel-App geladen:For appsettings.Development.json in the sample app, the following file is loaded:

    {
      "Logging": {
        "LogLevel": {
          "Default": "Debug",
          "System": "Information",
          "Microsoft": "Information"
        }
      }
    }
    
  1. Führen Sie die Beispiel-App aus.Run the sample app. Öffnen Sie einen Browser für die App unter http://localhost:5000.Open a browser to the app at http://localhost:5000.
  2. Die Ausgabe enthält Schlüssel-Wert-Paare für die Konfiguration basierend auf der Umgebung der App.The output contains key-value pairs for the configuration based on the app's environment. Die Protokollebene für den Schlüssel Logging:LogLevel:Default ist Debug, wenn die App in der Entwicklungsumgebung ausgeführt wird.The log level for the key Logging:LogLevel:Default is Debug when running the app in the Development environment.
  3. Führen Sie die Beispiel-App noch mal in der Produktionsumgebung aus:Run the sample app again in the Production environment:
    1. Öffnen Sie die Datei Properties/launchSettings.json.Open the Properties/launchSettings.json file.
    2. Ändern Sie im ConfigurationSample-Profil den Wert der Umgebungsvariablen ASPNETCORE_ENVIRONMENT in Production.In the ConfigurationSample profile, change the value of the ASPNETCORE_ENVIRONMENT environment variable to Production.
    3. Speichern Sie die Datei, und führen Sie die App mit dotnet run in einer Befehlsshell aus.Save the file and run the app with dotnet run in a command shell.
  4. Die Einstellungen in der appsettings.Development.json-Datei setzen die Einstellungen in der Datei appsettings.json nicht länger außer Kraft.The settings in the appsettings.Development.json no longer override the settings in appsettings.json. Die Protokollebene für den Schlüssel Logging:LogLevel:Default lautet Warning.The log level for the key Logging:LogLevel:Default is Warning.

XML-KonfigurationsanbieterXML Configuration Provider

XmlConfigurationProvider lädt während der Laufzeit die Konfiguration aus den Schlüssel-Wert-Paaren der XML-Datei.The XmlConfigurationProvider loads configuration from XML file key-value pairs at runtime.

Um die XML-Dateikonfiguration zu aktivieren, rufen Sie die AddXmlFile-Erweiterungsmethode auf einer ConfigurationBuilder-Instanz auf.To activate XML file configuration, call the AddXmlFile extension method on an instance of ConfigurationBuilder.

Überladungen geben Folgendes an:Overloads permit specifying:

  • Ob die Datei optional istWhether the file is optional.
  • Ob die Konfiguration bei Dateiänderungen neu geladen wirdWhether the configuration is reloaded if the file changes.
  • Dass mit IFileProvider auf die Datei zugegriffen wirdThe IFileProvider used to access the file.

Der Stammknoten der Konfigurationsdatei wird beim Erstellen der Konfigurations-Schlüssel-Wert-Paare ignoriert.The root node of the configuration file is ignored when the configuration key-value pairs are created. Geben Sie keine Dokumenttypdefinition (DTD) und keinen Namespace in der Datei an.Don't specify a Document Type Definition (DTD) or namespace in the file.

Rufen Sie ConfigureAppConfiguration beim Erstellen des Hosts auf, um die Konfiguration der App anzugeben:Call ConfigureAppConfiguration when building the host to specify the app's configuration:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddXmlFile(
        "config.xml", optional: true, reloadOnChange: true);
})

XML-Konfigurationsdateien können unterschiedliche Elementnamen für wiederholte Abschnitte verwenden:XML configuration files can use distinct element names for repeating sections:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <section0>
    <key0>value</key0>
    <key1>value</key1>
  </section0>
  <section1>
    <key0>value</key0>
    <key1>value</key1>
  </section1>
</configuration>

Die vorherige Konfigurationsdatei lädt die folgenden Schlüssel mit value:The previous configuration file loads the following keys with value:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:key0section1:key0
  • section1:key1section1:key1

Wiederholte Elemente mit den gleichen Elementnamen funktionieren, wenn das name-Attribut zur Unterscheidung der Elemente verwendet wird:Repeating elements that use the same element name work if the name attribute is used to distinguish the elements:

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

Die vorherige Konfigurationsdatei lädt die folgenden Schlüssel mit value:The previous configuration file loads the following keys with value:

  • section:section0:key:key0section:section0:key:key0
  • section:section0:key:key1section:section0:key:key1
  • section:section1:key:key0section:section1:key:key0
  • section:section1:key:key1section:section1:key:key1

Mit Attributen können Werte bereitgestellt werden:Attributes can be used to supply values:

<?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:The previous configuration file loads the following keys with value:

  • key:attributekey:attribute
  • section:key:attributesection:key:attribute

Schlüssel-pro-Datei-KonfigurationsanbieterKey-per-file Configuration Provider

KeyPerFileConfigurationProvider verwendet Verzeichnisdateien als Konfigurations-Schlüssel-Wert-Paare.The KeyPerFileConfigurationProvider uses a directory's files as configuration key-value pairs. Der Schlüssel ist der Dateiname.The key is the file name. Der Wert enthält den Inhalt der Datei.The value contains the file's contents. Der Schlüssel-pro-Datei-Konfigurationsanbieter wird in Docker-Hostingszenarien verwendet.The Key-per-file Configuration Provider is used in Docker hosting scenarios.

Um die Schlüssel-pro-Datei-Konfiguration zu aktivieren, rufen Sie die AddKeyPerFile-Erweiterungsmethode auf einer ConfigurationBuilder-Instanz auf.To activate key-per-file configuration, call the AddKeyPerFile extension method on an instance of ConfigurationBuilder. Der directoryPath zu den Dateien muss ein absoluter Pfad sein.The directoryPath to the files must be an absolute path.

Überladungen geben Folgendes an:Overloads permit specifying:

  • Einen Action<KeyPerFileConfigurationSource>-Delegat, der die Quelle konfiguriertAn Action<KeyPerFileConfigurationSource> delegate that configures the source.
  • Ob das Verzeichnis optional ist; und den Pfad zum VerzeichnisWhether the directory is optional and the path to the directory.

Der doppelte Unterstrich (__) wird als Trennzeichen für Konfigurationsschlüssel in Dateinamen verwendet.The double-underscore (__) is used as a configuration key delimiter in file names. Der Dateiname Logging__LogLevel__System erzeugt z.B. den Konfigurationsschlüssel Logging:LogLevel:System.For example, the file name Logging__LogLevel__System produces the configuration key Logging:LogLevel:System.

Rufen Sie ConfigureAppConfiguration beim Erstellen des Hosts auf, um die Konfiguration der App anzugeben:Call ConfigureAppConfiguration when building the host to specify the app's configuration:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");
    config.AddKeyPerFile(directoryPath: path, optional: true);
})

SpeicherkonfigurationsanbieterMemory Configuration Provider

MemoryConfigurationProvider verwendet eine In-Memory-Sammlung für Konfigurations-Schlüssel-Wert-Paare.The MemoryConfigurationProvider uses an in-memory collection as configuration key-value pairs.

Um die In-Memory-Sammlungskonfiguration zu aktivieren, rufen Sie die AddInMemoryCollection-Erweiterungsmethode auf einer ConfigurationBuilder-Instanz auf.To activate in-memory collection configuration, call the AddInMemoryCollection extension method on an instance of ConfigurationBuilder.

Der Konfigurationsanbieter kann mit IEnumerable<KeyValuePair<String,String>> initialisiert werden.The configuration provider can be initialized with an IEnumerable<KeyValuePair<String,String>>.

Rufen Sie ConfigureAppConfiguration beim Erstellen des Hosts auf, um die Konfiguration der App anzugeben.Call ConfigureAppConfiguration when building the host to specify the app's configuration.

Im folgenden Beispiel wird ein Konfigurationswörterbuch erstellt:In the following example, a configuration dictionary is created:

public static readonly Dictionary<string, string> _dict = 
    new Dictionary<string, string>
    {
        {"MemoryCollectionKey1", "value1"},
        {"MemoryCollectionKey2", "value2"}
    };

Das Wörterbuch wird mit einem Aufruf von AddInMemoryCollection verwendet, um die Konfiguration bereitzustellen:The dictionary is used with a call to AddInMemoryCollection to provide the configuration:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddInMemoryCollection(_dict);
})

GetValueGetValue

ConfigurationBinder.GetValue<T> extrahiert einen Einzelwert aus der Konfiguration mit einem angegebenen Schlüssel und konvertiert ihn in den angegebenen Typ, der kein Sammlungstyp ist.ConfigurationBinder.GetValue<T> extracts a single value from configuration with a specified key and converts it to the specified noncollection type. Eine Überladung akzeptiert einen Standardwert.An overload accepts a default value.

Im Beispiel unten geschieht Folgendes:The following example:

  • Der Zeichenfolgenwert aus der Konfiguration wird mit dem Schlüssel NumberKey extrahiert.Extracts the string value from configuration with the key NumberKey. Wenn NumberKey nicht in den Konfigurationsschlüsseln gefunden wird, wird der Standardwert 99 verwendet.If NumberKey isn't found in the configuration keys, the default value of 99 is used.
  • Der Typ für den Wert wird als int festgelegt.Types the value as an int.
  • Der Wert wird in der NumberConfig-Eigenschaft für die Verwendung durch die Seite gespeichert.Stores the value in the NumberConfig property for use by the page.
public class IndexModel : PageModel
{
    public IndexModel(IConfiguration config)
    {
        _config = config;
    }

    public int NumberConfig { get; private set; }

    public void OnGet()
    {
        NumberConfig = _config.GetValue<int>("NumberKey", 99);
    }
}

GetSection, GetChildren und ExistsGetSection, GetChildren, and Exists

Betrachten Sie für die folgenden Beispiele die JSON-Datei unten.For the examples that follow, consider the following JSON file. Vier Schlüssel befinden sich in zwei Abschnitten, von denen einer ein Paar Unterabschnitte enthält:Four keys are found across two sections, one of which includes a pair of subsections:

{
  "section0": {
    "key0": "value",
    "key1": "value"
  },
  "section1": {
    "key0": "value",
    "key1": "value"
  },
  "section2": {
    "subsection0" : {
      "key0": "value",
      "key1": "value"
    },
    "subsection1" : {
      "key0": "value",
      "key1": "value"
    }
  }
}

Wenn die Datei in die Konfiguration gelesen wird, werden die folgenden eindeutigen hierarchischen Schlüssel erstellt, um die Konfigurationswerte zu enthalten:When the file is read into configuration, the following unique hierarchical keys are created to hold the configuration values:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:key0section1:key0
  • section1:key1section1:key1
  • section2:subsection0:key0section2:subsection0:key0
  • section2:subsection0:key1section2:subsection0:key1
  • section2:subsection1:key0section2:subsection1:key0
  • section2:subsection1:key1section2:subsection1:key1

GetSectionGetSection

IConfiguration.GetSection extrahiert einen Konfigurationsunterabschnitt mit dem angegebenen Unterabschnittsschlüssel.IConfiguration.GetSection extracts a configuration subsection with the specified subsection key.

Um ein IConfigurationSection-Element zurückzugeben, das nur die Schlüssel-Wert-Paare in section1 enthält, rufen Sie GetSection auf, und geben Sie den Abschnittsnamen an:To return an IConfigurationSection containing only the key-value pairs in section1, call GetSection and supply the section name:

var configSection = _config.GetSection("section1");

Das Element configSection weist keinen Wert auf, nur einen Schlüssel und einen Pfad.The configSection doesn't have a value, only a key and a path.

Um die Werte für Schlüssel in section2:subsection0 zu erhalten, rufen Sie GetSection auf, und geben Sie den Abschnittspfad an:Similarly, to obtain the values for keys in section2:subsection0, call GetSection and supply the section path:

var configSection = _config.GetSection("section2:subsection0");

GetSection gibt nie null zurück.GetSection never returns null. Wenn kein entsprechender Abschnitt gefunden wird, wird ein leeres IConfigurationSection-Element zurückgegeben.If a matching section isn't found, an empty IConfigurationSection is returned.

Wenn GetSection einen entsprechenden Abschnitt zurückgibt, wird Value nicht aufgefüllt.When GetSection returns a matching section, Value isn't populated. Eine Eigenschaft Key und Path werden zurückgegeben, wenn der Abschnitt vorhanden ist.A Key and Path are returned when the section exists.

GetChildrenGetChildren

Ein Aufruf von IConfiguration.GetChildren auf section2 erhält IEnumerable<IConfigurationSection> mit folgenden Elementen:A call to IConfiguration.GetChildren on section2 obtains an IEnumerable<IConfigurationSection> that includes:

  • subsection0
  • subsection1
var configSection = _config.GetSection("section2");

var children = configSection.GetChildren();

VorhandenExists

Verwenden Sie ConfigurationExtensions.Exists um zu bestimmen, ob ein Konfigurationsabschnitt vorhanden ist:Use ConfigurationExtensions.Exists to determine if a configuration section exists:

var sectionExists = _config.GetSection("section2:subsection2").Exists();

Im Falle der Beispieldaten ist sectionExists``false, weil in den Konfigurationsdaten kein Abschnitt section2:subsection2 vorhanden ist.Given the example data, sectionExists is false because there isn't a section2:subsection2 section in the configuration data.

Binden an ein ObjektdiagrammBind to an object graph

Bind kann ein ganzes POCO-Objektdiagramm binden.Bind is capable of binding an entire POCO object graph. Wie beim Binden eines einfachen Objekts werden nur öffentliche Lese-/Schreibeigenschaften gebunden.As with binding a simple object, only public read/write properties are bound.

Das Beispiel enthält ein TvShow-Modell, dessen Objektdiagramm die Klassen Metadata und Actors enthält (Models/TvShow.cs):The sample contains a TvShow model whose object graph includes Metadata and Actors classes (Models/TvShow.cs):

public class TvShow
{
    public Metadata Metadata { get; set; }
    public Actors Actors { get; set; }
    public string Legal { get; set; }
}

public class Metadata
{
    public string Series { get; set; }
    public string Title { get; set; }
    public DateTime AirDate { get; set; }
    public int Episodes { get; set; }
}

public class Actors
{
    public string Names { get; set; }
}

Die Beispiel-App verfügt über eine tvshow.xml-Datei mit den Konfigurationsdaten:The sample app has a tvshow.xml file containing the configuration data:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <tvshow>
    <metadata>
      <series>Dr. Who</series>
      <title>The Sun Makers</title>
      <airdate>11/26/1977</airdate>
      <episodes>4</episodes>
    </metadata>
    <actors>
      <names>Tom Baker, Louise Jameson, John Leeson</names>
    </actors>
    <legal>(c)1977 BBC https://www.bbc.co.uk/programmes/b006q2x0</legal>
  </tvshow>
</configuration>

Die Konfiguration wird mit der Bind-Methode an das gesamte TvShow-Objektdiagramm gebunden.Configuration is bound to the entire TvShow object graph with the Bind method. Die gebundene Instanz ist einer Eigenschaft zum Rendern zugewiesen:The bound instance is assigned to a property for rendering:

var tvShow = new TvShow();
_config.GetSection("tvshow").Bind(tvShow);
TvShow = tvShow;

ConfigurationBinder.Get<T> bindet den angegebenen Typ und gibt ihn zurück.ConfigurationBinder.Get<T> binds and returns the specified type. Get<T> ist praktischer als Bind.Get<T> is more convenient than using Bind. Der folgende Code zeigt, wie Get<T> in Bezug auf das vorherige Beispiel verwendet wird:The following code shows how to use Get<T> with the preceding example:

TvShow = _config.GetSection("tvshow").Get<TvShow>();

Binden eines Arrays an eine KlasseBind an array to a class

Die Beispiel-App veranschaulicht die in diesem Abschnitt erläuterten Konzepte.The sample app demonstrates the concepts explained in this section.

Bind unterstützt das Binden von Arrays an Objekte mit Arrayindizes in Konfigurationsschlüsseln.The Bind supports binding arrays to objects using array indices in configuration keys. Jedes Arrayformat, das ein numerisches Schlüsselsegment (:0:, :1:, … :{n}:) verfügbar macht, kann ein Array an ein POCO-Klassenarray binden.Any array format that exposes a numeric key segment (:0:, :1:, … :{n}:) is capable of array binding to a POCO class array.

Hinweis

Das Binden ist standardmäßig möglich.Binding is provided by convention. Benutzerdefinierte Konfigurationsanbieter sind nicht erforderlich, um Arraybindung zu implementieren.Custom configuration providers aren't required to implement array binding.

In-Memory-ArrayverarbeitungIn-memory array processing

Betrachten Sie die Konfigurationsschlüssel und -werte in der folgenden Tabelle.Consider the configuration keys and values shown in the following table.

KeyKey WertValue
array:entries:0array:entries:0 value0value0
array:entries:1array:entries:1 value1value1
array:entries:2array:entries:2 value2value2
array:entries:4array:entries:4 value4value4
array:entries:5array:entries:5 value5value5

Diese Schlüssel und Werte werden mit dem Speicherkonfigurationsanbieter in die Beispiel-App geladen:These keys and values are loaded in the sample app using the Memory Configuration Provider:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

Das Array überspringt einen Wert für Index #3.The array skips a value for index #3. Der Konfigurationsbinder kann weder NULL-Werte binden noch NULL-Einträge in gebundenen Objekten erstellen. Dies wird deutlich, wenn das Ergebnis der Bindung dieses Arrays an ein Objekt demonstriert wird.The configuration binder isn't capable of binding null values or creating null entries in bound objects, which becomes clear in a moment when the result of binding this array to an object is demonstrated.

In der Beispiel-App ist eine POCO-Klasse verfügbar, um die gebundenen Konfigurationsdaten zu enthalten:In the sample app, a POCO class is available to hold the bound configuration data:

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

Die Konfigurationsdaten werden an das Objekt gebunden:The configuration data is bound to the object:

var arrayExample = new ArrayExample();
_config.GetSection("array").Bind(arrayExample);

ConfigurationBinder.Get<T>-Syntax kann ebenfalls verwendet werden, was zu kompakteren Code führt:ConfigurationBinder.Get<T> syntax can also be used, which results in more compact code:

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

Das gebundene Objekt, eine Instanz von ArrayExample, empfängt die Arraydaten aus der Konfiguration.The bound object, an instance of ArrayExample, receives the array data from configuration.

ArrayExample.Entries-IndexArrayExample.Entries Index ArrayExample.Entries-WertArrayExample.Entries Value
00 value0value0
11 value1value1
22 value2value2
33 value4value4
44 value5value5

Index #3 im gebundenen Objekt enthält die Konfigurationsdaten für den array:4-Konfigurationsschlüssel und die Wert für value4.Index #3 in the bound object holds the configuration data for the array:4 configuration key and its value of value4. Beim Binden von Konfigurationsdaten, die ein Array enthalten, werden die Arrayindizes in den Konfigurationsschlüsseln lediglich zum Durchlaufen der Konfigurationsdaten beim Erstellen des Objekts verwendet.When configuration data containing an array is bound, the array indices in the configuration keys are merely used to iterate the configuration data when creating the object. Ein NULL-Wert kann in den Konfigurationsdaten nicht beibehalten werden, und ein NULL-Eintrag wird nicht in einem gebundenen Objekt erstellt, wenn ein Array in Konfigurationsschlüsseln mindestens einen Index überspringt.A null value can't be retained in configuration data, and a null-valued entry isn't created in a bound object when an array in configuration keys skip one or more indices.

Das fehlende Konfigurationselement für Index #3 kann vor dem Binden an die ArrayExampleInstanz von jedem Konfigurationsanbieter bereitgestellt werden, der das richtige Schlüssel-Wert-Paar in der Konfiguration erzeugt.The missing configuration item for index #3 can be supplied before binding to the ArrayExample instance by any configuration provider that produces the correct key-value pair in configuration. Wenn das Beispiel einen zusätzlichen JSON-Konfigurationsanbieter mit dem fehlenden Schlüssel-Wert-Paar enthält, entspricht ArrayExample.Entries dem kompletten Konfigurationsarray:If the sample included an additional JSON Configuration Provider with the missing key-value pair, the ArrayExample.Entries matches the complete configuration array:

missing_value.json:missing_value.json:

{
  "array:entries:3": "value3"
}

In ConfigureAppConfiguration:In ConfigureAppConfiguration:

config.AddJsonFile(
    "missing_value.json", optional: false, reloadOnChange: false);

Das Schlüssel-Wert-Paar in der Tabelle wird in die Konfiguration geladen.The key-value pair shown in the table is loaded into configuration.

KeyKey WertValue
array:entries:3array:entries:3 value3value3

Wenn die ArrayExample-Klasseninstanz gebunden wird, nachdem der JSON-Konfigurationsanbieter den Eintrag für Index #3 enthält, enthält das ArrayExample.Entries-Array den Wert.If the ArrayExample class instance is bound after the JSON Configuration Provider includes the entry for index #3, the ArrayExample.Entries array includes the value.

ArrayExample.Entries-IndexArrayExample.Entries Index ArrayExample.Entries-WertArrayExample.Entries Value
00 value0value0
11 value1value1
22 value2value2
33 value3value3
44 value4value4
55 value5value5

JSON-ArrayverarbeitungJSON array processing

Wenn eine JSON-Datei ein Array enthält, werden Konfigurationsschlüssel für die Arrayelemente mit einem nullbasierten Abschnittsindex erstellt.If a JSON file contains an array, configuration keys are created for the array elements with a zero-based section index. In der folgenden Konfigurationsdatei ist subsection ein Array:In the following configuration file, subsection is an array:

{
  "json_array": {
    "key": "valueA",
    "subsection": [
      "valueB",
      "valueC",
      "valueD"
    ]
  }
}

Der JSON-Konfigurationsanbieter liest die Konfigurationsdaten in die folgenden Schlüssel-Wert-Paare:The JSON Configuration Provider reads the configuration data into the following key-value pairs:

KeyKey WertValue
json_array:keyjson_array:key valueAvalueA
json_array:subsection:0json_array:subsection:0 valueBvalueB
json_array:subsection:1json_array:subsection:1 valueCvalueC
json_array:subsection:2json_array:subsection:2 valueDvalueD

In der Beispiel-App können die Konfigurations-Schlüssel-Wert-Paare mit dieser POCO-Klasse gebunden werden:In the sample app, the following POCO class is available to bind the configuration key-value pairs:

public class JsonArrayExample
{
    public string Key { get; set; }
    public string[] Subsection { get; set; }
}

Nach dem Binden enthält JsonArrayExample.Key den Wert valueA.After binding, JsonArrayExample.Key holds the value valueA. Die Unterabschnittwerte werden in der POCO-Arrayeigenschaft Subsection gespeichert.The subsection values are stored in the POCO array property, Subsection.

JsonArrayExample.Subsection-IndexJsonArrayExample.Subsection Index JsonArrayExample.Subsection-WertJsonArrayExample.Subsection Value
00 valueBvalueB
11 valueCvalueC
22 valueDvalueD

Benutzerdefinierter KonfigurationsanbieterCustom configuration provider

Die Beispiel-App veranschaulicht, wie ein Standardkonfigurationsanbieter erstellt wird, der Konfigurations-Schlüssel-Wert-Paare aus einer Datenbank mit Entity Framework (EF) liest.The sample app demonstrates how to create a basic configuration provider that reads configuration key-value pairs from a database using Entity Framework (EF).

Der Anbieter weist die folgenden Merkmale auf:The provider has the following characteristics:

  • Die EF-In-Memory-Datenbank wird zu Demonstrationszwecken verwendet.The EF in-memory database is used for demonstration purposes. Um eine Datenbank zu verwenden, die eine Verbindungszeichenfolge benötigt, implementieren Sie einen sekundären ConfigurationBuilder, um die Verbindungszeichenfolge aus einem anderen Konfigurationsanbieter anzugeben.To use a database that requires a connection string, implement a secondary ConfigurationBuilder to supply the connection string from another configuration provider.
  • Der Anbieter liest eine Datenbanktabelle beim Start in die Konfiguration.The provider reads a database table into configuration at startup. Der Anbieter fragt die Datenbank nicht pro Schlüssel ab.The provider doesn't query the database on a per-key basis.
  • 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.Reload-on-change isn't implemented, so updating the database after the app starts has no effect on the app's configuration.

Definieren Sie eine EFConfigurationValue-Entität zum Speichern von Konfigurationswerten in der Datenbank.Define an EFConfigurationValue entity for storing configuration values in the database.

Models/EFConfigurationValue.cs:Models/EFConfigurationValue.cs:

public class EFConfigurationValue
{
    public string Id { get; set; }
    public string Value { get; set; }
}

Fügen Sie EFConfigurationContext hinzu, um die konfigurierten Werte zu speichern und auf diese zugreifen.Add an EFConfigurationContext to store and access the configured values.

EFConfigurationProvider/EFConfigurationContext.cs:EFConfigurationProvider/EFConfigurationContext.cs:

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

    public DbSet<EFConfigurationValue> Values { get; set; }
}

Erstellen Sie eine Klasse, die das IConfigurationSource implementiert.Create a class that implements IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs:EFConfigurationProvider/EFConfigurationSource.cs:

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

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

    public IConfigurationProvider Build(IConfigurationBuilder builder)
    {
        return new EFConfigurationProvider(_optionsAction);
    }
}

Erstellen Sie den benutzerdefinierten Konfigurationsanbieter durch Vererbung von ConfigurationProvider.Create the custom configuration provider by inheriting from ConfigurationProvider. Der Konfigurationsanbieter initialisiert die Datenbank, wenn diese leer ist.The configuration provider initializes the database when it's empty.

EFConfigurationProvider/EFConfigurationProvider.cs:EFConfigurationProvider/EFConfigurationProvider.cs:

public class EFConfigurationProvider : ConfigurationProvider
{
    public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
    {
        OptionsAction = optionsAction;
    }

    Action<DbContextOptionsBuilder> OptionsAction { get; }

    // Load config data from EF DB.
    public override void Load()
    {
        var builder = new DbContextOptionsBuilder<EFConfigurationContext>();

        OptionsAction(builder);

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

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

    private static IDictionary<string, string> CreateAndSaveDefaultValues(
        EFConfigurationContext dbContext)
    {
        // Quotes (c)2005 Universal Pictures: Serenity
        // https://www.uphe.com/movies/serenity
        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." }
            };

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

        dbContext.SaveChanges();

        return configValues;
    }
}

Mit einer AddEFConfiguration-Erweiterungsmethode kann die Konfigurationsquelle ConfigurationBuilder hinzugefügt werden.An AddEFConfiguration extension method permits adding the configuration source to a ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs: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 veranschaulicht die Verwendung des benutzerdefinierten Anbieters EFConfigurationProvider in Program.cs:The following code shows how to use the custom EFConfigurationProvider in Program.cs:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

Zugreifen auf die Konfiguration während des StartsAccess configuration during startup

Fügen Sie IConfiguration in den Startup-Konstruktor ein, um auf Konfigurationswerte in Startup.ConfigureServices zuzugreifen.Inject IConfiguration into the Startup constructor to access configuration values in Startup.ConfigureServices. Um auf die Konfiguration in Startup.Configure zuzugreifen, fügen Sie entweder IConfiguration direkt in die Methode ein, oder verwenden Sie die Instanz aus dem Konstruktor:To access configuration in Startup.Configure, either inject IConfiguration directly into the method or use the instance from the constructor:

public class Startup
{
    private readonly IConfiguration _config;

    public Startup(IConfiguration config)
    {
        _config = config;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        var value = _config["key"];
    }

    public void Configure(IApplicationBuilder app, IConfiguration config)
    {
        var value = config["key"];
    }
}

Ein Beispiel für den Zugriff auf die Konfiguration mit den Starthilfsmethoden finden Sie unter Anwendungsstart: Hilfsmethoden.For an example of accessing configuration using startup convenience methods, see App startup: Convenience methods.

Zugreifen auf die Konfiguration auf einer Razor Pages-Seite oder in einer MVC-AnsichtAccess configuration in a Razor Pages page or MVC view

Um auf die Konfigurationseinstellungen auf einer Razor Pages-Seite oder in einer MVC-Ansicht zuzugreifen, fügen Sie eine using-Anweisung (C#-Referenz: using-Anweisung) für den Microsoft.Extensions.Configuration-Namespace hinzu, und fügen Sie IConfiguration auf der Seite bzw. in der Ansicht ein.To access configuration settings in a Razor Pages page or an MVC view, add a using directive (C# reference: using directive) for the Microsoft.Extensions.Configuration namespace and inject IConfiguration into the page or view.

Auf einer Razor Pages-Seite:In a Razor Pages page:

@page
@model IndexModel
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Index Page</title>
</head>
<body>
    <h1>Access configuration in a Razor Pages page</h1>
    <p>Configuration value for 'key': @Configuration["key"]</p>
</body>
</html>

In einer MVC-Ansicht:In an MVC view:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Index View</title>
</head>
<body>
    <h1>Access configuration in an MVC view</h1>
    <p>Configuration value for 'key': @Configuration["key"]</p>
</body>
</html>

Hinzufügen von Konfigurationen aus einer externen AssemblyAdd configuration from an external 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.An IHostingStartup implementation allows adding enhancements to an app at startup from an external assembly outside of the app's Startup class. Weitere Informationen finden Sie unter Verwenden von Hostingstartassemblys in ASP.NET Core.For more information, see Verwenden von Hostingstartassemblys in ASP.NET Core.

Zusätzliche RessourcenAdditional resources