ASP.NET Core 中的配置Configuration in ASP.NET Core

作者:Luke LathamBy Luke Latham

ASP.NET Core 中的应用配置基于配置提供程序建立的键值对。App configuration in ASP.NET Core is based on key-value pairs established by configuration providers. 配置提供程序将配置数据从各种配置源读取到键值对:Configuration providers read configuration data into key-value pairs from a variety of configuration sources:

  • Azure Key VaultAzure Key Vault
  • Azure 应用配置Azure App Configuration
  • 命令行参数Command-line arguments
  • (已安装或已创建的)自定义提供程序Custom providers (installed or created)
  • 目录文件Directory files
  • 环境变量Environment variables
  • 内存中的 .NET 对象In-memory .NET objects
  • 设置文件Settings files

框架隐式包含通用配置提供程序方案的配置包 (Microsoft Extensions.Configuration)。Configuration packages for common configuration provider scenarios (Microsoft.Extensions.Configuration) are included implicitly by the framework.

Microsoft.AspNetCore.App metapackage 中包含通用配置提供程序方案的配置包 (Microsoft Extensions.Configuration)。Configuration packages for common configuration provider scenarios (Microsoft.Extensions.Configuration) are included in the Microsoft.AspNetCore.App metapackage.

后面的代码示例和示例应用中的代码示例使用 Microsoft.Extensions.Configuration 命名空间:Code examples that follow and in the sample app use the Microsoft.Extensions.Configuration namespace:

using Microsoft.Extensions.Configuration;

选项模式是本主题中描述的配置概念的扩展。The options pattern is an extension of the configuration concepts described in this topic. 选项使用类来表示相关设置的组。Options use classes to represent groups of related settings. 有关详细信息,请参阅 ASP.NET Core 中的选项模式For more information, see ASP.NET Core 中的选项模式.

查看或下载示例代码如何下载View or download sample code (how to download)

主机与应用配置Host versus app configuration

在配置并启动应用之前,配置并启动主机。Before the app is configured and started, a host is configured and launched. 主机负责应用程序启动和生存期管理。The host is responsible for app startup and lifetime management. 应用和主机均使用本主题中所述的配置提供程序进行配置。Both the app and the host are configured using the configuration providers described in this topic. 应用的配置中也包含主机配置键值对。Host configuration key-value pairs are also included in the app's configuration. 有关在构建主机时如何使用配置提供程序以及配置源如何影响主机配置的详细信息,请参阅 ASP.NET Core 基础知识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 基础知识.

默认配置Default configuration

基于 ASP.NET Core dotnet new模板的 Web 应用在生成主机时会调用 CreateDefaultBuilderWeb apps based on the ASP.NET Core dotnet new templates call CreateDefaultBuilder when building a host. CreateDefaultBuilder 按照以下顺序为应用提供默认配置:CreateDefaultBuilder provides default configuration for the app in the following order:

以下内容适用于使用通用主机的应用。The following applies to apps using the Generic Host. 有关使用 Web 主机时默认配置的详细信息,请参阅本主题的 ASP.NET Core 2.2 版本For details on the default configuration when using the Web Host, see the ASP.NET Core 2.2 version of this topic.

  • 主机配置通过以下方式提供:Host configuration is provided from:
  • 已建立 Web 主机默认配置 (ConfigureWebHostDefaults):Web Host default configuration is established (ConfigureWebHostDefaults):
    • Kestrel 用作 Web 服务器,并使用应用的配置提供程序对其进行配置。Kestrel is used as the web server and configured using the app's configuration providers.
    • 添加主机筛选中间件。Add Host Filtering Middleware.
    • 如果 ASPNETCORE_FORWARDEDHEADERS_ENABLED 环境变量设置为 true,则添加转发的标头中间件。Add Forwarded Headers Middleware if the ASPNETCORE_FORWARDEDHEADERS_ENABLED environment variable is set to true.
    • 启用 IIS 集成。Enable IIS integration.
  • 应用配置通过以下方式提供:App configuration is provided from:

基于 ASP.NET Core dotnet new模板的 Web 应用在生成主机时会调用 CreateDefaultBuilderWeb apps based on the ASP.NET Core dotnet new templates call CreateDefaultBuilder when building a host. CreateDefaultBuilder 按照以下顺序为应用提供默认配置:CreateDefaultBuilder provides default configuration for the app in the following order:

以下内容适用于使用 Web 主机的应用。The following applies to apps using the Web Host. 有关使用通用主机时默认配置的详细信息,请参阅本主题的最新版本For details on the default configuration when using the Generic Host, see the latest version of this topic.

安全性Security

采用以下做法来保护敏感配置数据:Adopt the following practices to secure sensitive configuration data:

  • 请勿在配置提供程序代码或纯文本配置文件中存储密码或其他敏感数据。Never store passwords or other sensitive data in configuration provider code or in plain text configuration files.
  • 不要在开发或测试环境中使用生产机密。Don't use production secrets in development or test environments.
  • 请在项目外部指定机密,避免将其意外提交到源代码存储库。Specify secrets outside of the project so that they can't be accidentally committed to a source code repository.

有关详细信息,请参阅下列主题:For more information, see the following topics:

Azure Key Vault 安全存储 ASP.NET Core 应用的应用机密。Azure Key Vault safely stores app secrets for ASP.NET Core apps. 有关详细信息,请参阅 ASP.NET Core 中的 Azure Key Vault 配置提供程序For more information, see ASP.NET Core 中的 Azure Key Vault 配置提供程序.

分层配置数据Hierarchical configuration data

配置 API 能够通过在配置键中使用分隔符来展平分层数据以保持分层配置数据。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.

在以下 JSON 文件中,两个节的结构化层次结构中存在四个键: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"
  }
}

将文件读入配置时,将创建唯一键以保持配置源的原始分层数据结构。When the file is read into configuration, unique keys are created to maintain the original hierarchical data structure of the configuration source. 使用冒号 (:) 展平节和键以保持原始结构: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

GetSectionGetChildren 方法可用于隔离各个节和配置数据中某节的子节。GetSection and GetChildren methods are available to isolate sections and children of a section in the configuration data. 稍后将在 GetSection、GetChildren 和 Exists 中介绍这些方法。These methods are described later in GetSection, GetChildren, and Exists.

约定Conventions

源和提供程序Sources and providers

在应用启动时,将按照指定的配置提供程序的顺序读取配置源。At app startup, configuration sources are read in the order that their configuration providers are specified.

实现更改检测的配置提供程序能够在基础设置更改时重新加载配置。Configuration providers that implement change detection have the ability to reload configuration when an underlying setting is changed. 例如,文件配置提供程序(本主题后面将对此进行介绍)和 Azure Key Vault 配置提供程序实现更改检测。For example, the File Configuration Provider (described later in this topic) and the Azure Key Vault Configuration Provider implement change detection.

应用的依赖关系注入 (DI) 容器中提供了 IConfigurationIConfiguration is available in the app's dependency injection (DI) container. IConfiguration 可注入到 Razor Pages PageModel 以获取以下类的配置:IConfiguration can be injected into a Razor Pages PageModel to obtain configuration for the class:

public class IndexModel : PageModel
{
    private readonly IConfiguration _config;

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

    // The _config local variable is used to obtain configuration 
    // throughout the class.
}

配置提供程序不能使用 DI,因为主机在设置这些提供程序时 DI 不可用。Configuration providers can't utilize DI, as it's not available when they're set up by the host.

Keys

配置键采用以下约定:Configuration keys adopt the following conventions:

  • 键不区分大小写。Keys are case-insensitive. 例如,ConnectionStringconnectionstring 被视为等效键。For example, ConnectionString and connectionstring are treated as equivalent keys.
  • 如果由相同或不同的配置提供程序设置相同键的值,则键上设置的最后一个值就是所使用的值。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.
  • 分层键Hierarchical keys
    • 在配置 API 中,冒号分隔符 (:) 适用于所有平台。Within the Configuration API, a colon separator (:) works on all platforms.
    • 在环境变量中,冒号分隔符可能无法适用于所有平台。In environment variables, a colon separator may not work on all platforms. 所有平台均支持采用双下划线 (__),并可以将其自动转换为冒号。A double underscore (__) is supported by all platforms and is automatically converted into a colon.
    • 在 Azure Key Vault 中,分层键使用 --(两个破折号)作为分隔符。In Azure Key Vault, hierarchical keys use -- (two dashes) as a separator. 将机密加载到应用的配置中时,必须提供代码以用冒号替换破折号。You must provide code to replace the dashes with a colon when the secrets are loaded into the app's configuration.
  • ConfigurationBinder 支持使用配置键中的数组索引将数组绑定到对象。The ConfigurationBinder supports binding arrays to objects using array indices in configuration keys. 数组绑定将在将数组绑定到类部分中进行介绍。Array binding is described in the Bind an array to a class section.

Values

配置值采用以下约定:Configuration values adopt the following conventions:

  • 值是字符串。Values are strings.
  • NULL 值不能存储在配置中或绑定到对象。Null values can't be stored in configuration or bound to objects.

提供程序Providers

下表显示了 ASP.NET Core 应用可用的配置提供程序。The following table shows the configuration providers available to ASP.NET Core apps.

提供程序Provider 通过以下对象提供配置…Provides configuration from…
Azure Key Vault 配置提供程序(安全主题)Azure Key Vault Configuration Provider (Security topics) Azure Key VaultAzure Key Vault
Azure 应用程序配置提供程序(Azure 文档)Azure App Configuration Provider (Azure documentation) Azure 应用配置Azure App Configuration
命令行配置提供程序Command-line Configuration Provider 命令行参数Command-line parameters
自定义配置提供程序Custom configuration provider 自定义源Custom source
环境变量配置提供程序Environment Variables Configuration Provider 环境变量Environment variables
文件配置提供程序File Configuration Provider 文件(INI、JSON、XML)Files (INI, JSON, XML)
Key-per-file 配置提供程序Key-per-file Configuration Provider 目录文件Directory files
内存配置提供程序Memory Configuration Provider 内存中集合In-memory collections
用户机密 (Secret Manager)(安全主题)User secrets (Secret Manager) (Security topics) 用户配置文件目录中的文件File in the user profile directory

按照启动时指定的配置提供程序的顺序读取配置源。Configuration sources are read in the order that their configuration providers are specified at startup. 本主题中所述的配置提供程序按字母顺序进行介绍,而不是按代码排列顺序进行介绍。The configuration providers described in this topic are described in alphabetical order, not in the order that your code may arrange them. 代码中的配置提供程序应以特定顺序排列以符合基础配置源的优先级。Order configuration providers in your code to suit your priorities for the underlying configuration sources.

配置提供程序的典型顺序为:A typical sequence of configuration providers is:

  1. 文件(appsettings.json、appsettings.{Environment}.json,其中 {Environment} 是应用的当前托管环境)Files (appsettings.json, appsettings.{Environment}.json, where {Environment} is the app's current hosting environment)
  2. Azure 密钥保管库Azure Key Vault
  3. 用户机密 (Secret Manager)(仅限开发环境中)User secrets (Secret Manager) (Development environment only)
  4. 环境变量Environment variables
  5. 命令行参数Command-line arguments

通常的做法是将命令行配置提供程序置于一系列提供程序的末尾,以允许命令行参数替代由其他提供程序设置的配置。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.

使用 CreateDefaultBuilder 初始化新的主机生成器时,将使用上述提供程序序列。The preceding sequence of providers is used when you initialize a new host builder with CreateDefaultBuilder. 有关详细信息,请参阅默认配置部分。For more information, see the Default configuration section.

用 ConfigureHostConfiguration 配置主机生成器Configure the host builder with ConfigureHostConfiguration

若要配置主机生成器,请调用 ConfigureHostConfiguration 并提供配置。To configure the host builder, call ConfigureHostConfiguration and supply the configuration. ConfigureHostConfiguration 初始化 IHostEnvironment,以便稍后在生成过程中使用。ConfigureHostConfiguration is used to initialize the IHostEnvironment for use later in the build process. 可多次调用 ConfigureHostConfiguration,并得到累计结果。ConfigureHostConfiguration can be called multiple times with additive results.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureHostConfiguration(config =>
        {
            var dict = new Dictionary<string, string>
            {
                {"MemoryCollectionKey1", "value1"},
                {"MemoryCollectionKey2", "value2"}
            };

            config.AddInMemoryCollection(dict);
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

用 UseConfiguration 配置主机生成器Configure the host builder with UseConfiguration

若要配置主机生成器,请使用配置在主机生成器上调用 UseConfigurationTo 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

构建主机时调用 ConfigureAppConfiguration 以指定应用的配置提供程序以及 CreateDefaultBuilder 自动添加的配置提供程序: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)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                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);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}
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.SetBasePath(Directory.GetCurrentDirectory());
                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>();
}

用命令行参数替代以前的配置Override previous configuration with command-line arguments

若要提供命令行参数可替代的应用配置,最后请调用 AddCommandLineTo provide app configuration that can be overridden with command-line arguments, call AddCommandLine last:

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

在应用启动期间使用配置Consume configuration during app startup

在应用启动期间,可以使用 ConfigureAppConfiguration 中提供给应用的配置,包括 Startup.ConfigureServicesConfiguration supplied to the app in ConfigureAppConfiguration is available during the app's startup, including Startup.ConfigureServices. 有关详细信息,请参阅在启动期间访问配置部分。For more information, see the Access configuration during startup section.

命令行配置提供程序Command-line Configuration Provider

CommandLineConfigurationProvider 在运行时从命令行参数键值对加载配置。The CommandLineConfigurationProvider loads configuration from command-line argument key-value pairs at runtime.

要激活命令行配置,请在 ConfigurationBuilder 的实例上调用 AddCommandLine 扩展方法。To activate command-line configuration, the AddCommandLine extension method is called on an instance of ConfigurationBuilder.

调用 CreateDefaultBuilder(string []) 时会自动调用 AddCommandLineAddCommandLine is automatically called when CreateDefaultBuilder(string []) is called. 有关详细信息,请参阅默认配置部分。For more information, see the Default configuration section.

此外,CreateDefaultBuilder 也会加载:CreateDefaultBuilder also loads:

  • appsettings.json 和 appsettings.{Environment}.json 文件中的可选配置。Optional configuration from appsettings.json and appsettings.{Environment}.json files.
  • 用户机密 (Secret Manager)(在开发环境中)。User secrets (Secret Manager) in the Development environment.
  • 环境变量。Environment variables.

CreateDefaultBuilder 最后添加命令行配置提供程序。CreateDefaultBuilder adds the Command-line Configuration Provider last. 在运行时传递的命令行参数会替代由其他提供程序设置的配置。Command-line arguments passed at runtime override configuration set by the other providers.

CreateDefaultBuilder 在构造主机时起作用。CreateDefaultBuilder acts when the host is constructed. 因此,CreateDefaultBuilder 激活的命令行配置可能会影响主机的配置方式。Therefore, command-line configuration activated by CreateDefaultBuilder can affect how the host is configured.

对于基于 ASP.NET Core 模板的应用,CreateDefaultBuilder 已调用 AddCommandLineFor apps based on the ASP.NET Core templates, AddCommandLine has already been called by CreateDefaultBuilder. 若要添加其他配置提供程序并保持能够用命令行参数替代这些提供程序的配置,请在 ConfigureAppConfiguration 中调用应用的其他提供程序,并最后调用 AddCommandLineTo 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);
})

示例Example

示例应用利用静态便捷方法 CreateDefaultBuilder 来生成主机,其中包括一个对 AddCommandLine 的调用。The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes a call to AddCommandLine.

  1. 在项目的目录中打开命令提示符。Open a command prompt in the project's directory.
  2. dotnet run 命令提供命令行参数 dotnet run CommandLineKey=CommandLineValueSupply a command-line argument to the dotnet run command, dotnet run CommandLineKey=CommandLineValue.
  3. 应用运行后,在 http://localhost:5000 打开应用的浏览器。After the app is running, open a browser to the app at http://localhost:5000.
  4. 观察输出是否包含提供给 dotnet run 的配置命令行参数的键值对。Observe that the output contains the key-value pair for the configuration command-line argument provided to dotnet run.

自变量Arguments

该值必须后跟一个等号 (=),否则当值后跟一个空格时,键必须具有前缀(--/)。The value must follow an equals sign (=), or the key must have a prefix (-- or /) when the value follows a space. 如果使用等号(例如 CommandLineKey=),则不需要该值。The value isn't required if an equals sign is used (for example, CommandLineKey=).

键前缀Key prefix 示例Example
无前缀No prefix CommandLineKey1=value1
双划线 (--)Two dashes (--) --CommandLineKey2=value2--CommandLineKey2 value2--CommandLineKey2=value2, --CommandLineKey2 value2
正斜杠 (/)Forward slash (/) /CommandLineKey3=value3/CommandLineKey3 value3/CommandLineKey3=value3, /CommandLineKey3 value3

在同一命令中,不要将使用等号的命令行参数键值对与使用空格的键值对混合使用。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.

示例命令:Example commands:

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

交换映射Switch mappings

交换映射支持键名替换逻辑。Switch mappings allow key name replacement logic. 使用 ConfigurationBuilder 手动构建配置时,可以为 AddCommandLine 方法提供交换替换字典。When you manually build configuration with a ConfigurationBuilder, you can provide a dictionary of switch replacements to the AddCommandLine method.

当使用交换映射字典时,会检查字典中是否有与命令行参数提供的键匹配的键。When the switch mappings dictionary is used, the dictionary is checked for a key that matches the key provided by a command-line argument. 如果在字典中找到命令行键,则传回字典值(键替换)以将键值对设置为应用的配置。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. 对任何具有单划线 (-) 前缀的命令行键而言,交换映射都是必需的。A switch mapping is required for any command-line key prefixed with a single dash (-).

交换映射字典键规则:Switch mappings dictionary key rules:

  • 交换必须以单划线 (-) 或双划线 (--) 开头。Switches must start with a dash (-) or double-dash (--).
  • 交换映射字典不得包含重复键。The switch mappings dictionary must not contain duplicate keys.

创建交换映射字典。Create a switch mappings dictionary. 在以下示例中,创建了两个交换映射:In the following example, two switch mappings are created:

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

生成主机后,使用交换映射字典来调用 AddCommandLineWhen the host is built, call AddCommandLine with the switch mappings dictionary:

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

对于使用交换映射的应用,调用 CreateDefaultBuilder 不应传递参数。For apps that use switch mappings, the call to CreateDefaultBuilder shouldn't pass arguments. CreateDefaultBuilder 方法的 AddCommandLine 调用不包括映射的交换,并且无法将交换映射字典传递给 CreateDefaultBuilderThe CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and there's no way to pass the switch mapping dictionary to CreateDefaultBuilder. 解决方案不是将参数传递给 CreateDefaultBuilder,而是允许 ConfigurationBuilder 方法的 AddCommandLine 方法处理参数和交换映射字典。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.

创建交换映射字典后,它将包含下表所示的数据。After the switch mappings dictionary is created, it contains the data shown in the following table.

Key Value
-CLKey1 CommandLineKey1
-CLKey2 CommandLineKey2

如果在启动应用时使用了交换映射的键,则配置将接收字典提供的密钥上的配置值: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

运行上述命令后,配置包含下表中显示的值。After running the preceding command, configuration contains the values shown in the following table.

Key Value
CommandLineKey1 value1
CommandLineKey2 value2

环境变量配置提供程序Environment Variables Configuration Provider

EnvironmentVariablesConfigurationProvider 在运行时从环境变量键值对加载配置。The EnvironmentVariablesConfigurationProvider loads configuration from environment variable key-value pairs at runtime.

要激活环境变量配置,请在 ConfigurationBuilder 的实例上调用 AddEnvironmentVariables 扩展方法。To activate environment variables configuration, call the AddEnvironmentVariables extension method on an instance of ConfigurationBuilder.

在环境变量中使用分层键时,冒号分隔符 (:) 可能无法适用于所有平台(例如 Bash)。When working with hierarchical keys in environment variables, a colon separator (:) may not work on all platforms (for example, Bash). 所有平台均支持采用双下划线 (__),并可以用冒号自动替换。A double underscore (__) is supported by all platforms and is automatically replaced by a colon.

借助 Azure 应用服务,用户可以在 Azure 门户中设置使用环境变量配置提供程序替代应用配置的环境变量。Azure App Service permits you to set environment variables in the Azure Portal that can override app configuration using the Environment Variables Configuration Provider. 有关详细信息,请参阅 Azure 应用:使用 Azure 门户替代应用配置For more information, see Azure Apps: Override app configuration using the Azure Portal.

如果使用通用主机初始化新的主机生成器,且调用了 CreateDefaultBuilder,则使用 AddEnvironmentVariables主机配置加载前缀为 DOTNET_ 的环境变量。AddEnvironmentVariables is used to load environment variables prefixed with DOTNET_ for host configuration when a new host builder is initialized with the Generic Host and CreateDefaultBuilder is called. 有关详细信息,请参阅默认配置部分。For more information, see the Default configuration section.

如果使用 Web 主机初始化新的主机生成器,且调用 CreateDefaultBuilder,则使用 AddEnvironmentVariables主机配置加载前缀为 ASPNETCORE_ 的环境变量。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. 有关详细信息,请参阅默认配置部分。For more information, see the Default configuration section.

此外,CreateDefaultBuilder 也会加载:CreateDefaultBuilder also loads:

  • 来自没有前缀的环境变量的应用配置,方法是通过调用不带前缀的 AddEnvironmentVariablesApp configuration from unprefixed environment variables by calling AddEnvironmentVariables without a prefix.
  • appsettings.json 和 appsettings.{Environment}.json 文件中的可选配置。Optional configuration from appsettings.json and appsettings.{Environment}.json files.
  • 用户机密 (Secret Manager)(在开发环境中)。User secrets (Secret Manager) in the Development environment.
  • 命令行参数。Command-line arguments.

环境变量配置提供程序是在配置已根据用户机密和 appsettings 文件建立后调用。The Environment Variables Configuration Provider is called after configuration is established from user secrets and appsettings files. 在此位置调用提供程序允许在运行时读取的环境变量替代由用户机密和 appsettings 文件设置的配置。Calling the provider in this position allows the environment variables read at runtime to override configuration set by user secrets and appsettings files.

如果需要从其他环境变量提供应用配置,请在 ConfigureAppConfiguration 中调用应用的其他提供程序,并使用前缀调用 AddEnvironmentVariablesIf you need 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) =>
{
    // Call additional providers here as needed.
    // Call AddEnvironmentVariables last if you need to allow
    // environment variables to override values from other 
    // providers.
    config.AddEnvironmentVariables(prefix: "PREFIX_");
})
}

示例Example

示例应用利用静态便捷方法 CreateDefaultBuilder 来生成主机,其中包括一个对 AddEnvironmentVariables 的调用。The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes a call to AddEnvironmentVariables.

  1. 运行示例应用。Run the sample app. http://localhost:5000 打开应用的浏览器。Open a browser to the app at http://localhost:5000.
  2. 观察输出是否包含环境变量 ENVIRONMENT 的键值对。Observe that the output contains the key-value pair for the environment variable ENVIRONMENT. 该值反映了应用运行的环境,在本地运行时通常为 DevelopmentThe value reflects the environment in which the app is running, typically Development when running locally.

为了缩短应用呈现的环境变量列表,应用会筛选环境变量。To keep the list of environment variables rendered by the app short, the app filters environment variables. 请参阅示例应用的“Pages/Index.cshtml.cs”文件。See the sample app's Pages/Index.cshtml.cs file.

如果希望公开应用可用的所有环境变量,请将 Pages/Index.cshtml.cs 中的 FilteredConfiguration 更改为以下内容:If you wish 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();

前缀Prefixes

AddEnvironmentVariables 方法提供前缀时,将筛选加载到应用的配置中的环境变量。Environment variables loaded into the app's configuration are filtered when you supply a prefix to the AddEnvironmentVariables method. 例如,要筛选前缀 CUSTOM_ 上的环境变量,请将前缀提供给配置提供程序:For example, to filter environment variables on the prefix CUSTOM_, supply the prefix to the configuration provider:

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

创建配置键值对时,将去除前缀。The prefix is stripped off when the configuration key-value pairs are created.

若已创建主机生成器,则主机配置由环境变量提供。When the host builder is created, host configuration is provided by environment variables. 有关用于这些环境变量的前缀的详细信息,请参阅默认配置部分。For more information on the prefix used for these environment variables, see the Default configuration section.

连接字符串前缀Connection string prefixes

针对为应用环境配置 Azure 连接字符串所涉及的四个连接字符串环境变量,配置 API 具有特殊的处理规则。The Configuration API has special processing rules for four connection string environment variables involved in configuring Azure connection strings for the app environment. 如果没有向 AddEnvironmentVariables 提供前缀,则具有表中所示前缀的环境变量将加载到应用中。Environment variables with the prefixes shown in the table are loaded into the app if no prefix is supplied to AddEnvironmentVariables.

连接字符串前缀Connection string prefix 提供程序Provider
CUSTOMCONNSTR_ 自定义提供程序Custom provider
MYSQLCONNSTR_ MySQLMySQL
SQLAZURECONNSTR_ Azure SQL 数据库Azure SQL Database
SQLCONNSTR_ SQL ServerSQL Server

当发现环境变量并使用表中所示的四个前缀中的任何一个加载到配置中时:When an environment variable is discovered and loaded into configuration with any of the four prefixes shown in the table:

  • 通过删除环境变量前缀并添加配置键节 (ConnectionStrings) 来创建配置键。The configuration key is created by removing the environment variable prefix and adding a configuration key section (ConnectionStrings).
  • 创建一个新的配置键值对,表示数据库连接提供程序(CUSTOMCONNSTR_ 除外,它没有声明的提供程序)。A new configuration key-value pair is created that represents the database connection provider (except for CUSTOMCONNSTR_, which has no stated provider).
环境变量键Environment variable key 转换的配置键Converted configuration key 提供程序配置条目Provider configuration entry
CUSTOMCONNSTR_<KEY> ConnectionStrings:<KEY> 配置条目未创建。Configuration entry not created.
MYSQLCONNSTR_<KEY> ConnectionStrings:<KEY> 键:ConnectionStrings:<KEY>_ProviderNameKey: ConnectionStrings:<KEY>_ProviderName:
值:MySql.Data.MySqlClientValue: MySql.Data.MySqlClient
SQLAZURECONNSTR_<KEY> ConnectionStrings:<KEY> 键:ConnectionStrings:<KEY>_ProviderNameKey: ConnectionStrings:<KEY>_ProviderName:
值:System.Data.SqlClientValue: System.Data.SqlClient
SQLCONNSTR_<KEY> ConnectionStrings:<KEY> 键:ConnectionStrings:<KEY>_ProviderNameKey: ConnectionStrings:<KEY>_ProviderName:
值:System.Data.SqlClientValue: System.Data.SqlClient

文件配置提供程序File Configuration Provider

FileConfigurationProvider 是从文件系统加载配置的基类。FileConfigurationProvider is the base class for loading configuration from the file system. 以下配置提供程序专用于特定文件类型:The following configuration providers are dedicated to specific file types:

INI 配置提供程序INI Configuration Provider

IniConfigurationProvider 在运行时从 INI 文件键值对加载配置。The IniConfigurationProvider loads configuration from INI file key-value pairs at runtime.

若要激活 INI 文件配置,请在 ConfigurationBuilder 的实例上调用 AddIniFile 扩展方法。To activate INI file configuration, call the AddIniFile extension method on an instance of ConfigurationBuilder.

冒号可用作 INI 文件配置中的节分隔符。The colon can be used to as a section delimiter in INI file configuration.

重载允许指定:Overloads permit specifying:

  • 文件是否可选。Whether the file is optional.
  • 如果文件更改,是否重载配置。Whether the configuration is reloaded if the file changes.
  • IFileProvider 用于访问该文件。The IFileProvider used to access the file.

构建主机时调用 ConfigureAppConfiguration 以指定应用的配置:Call ConfigureAppConfiguration when building the host to specify the app's configuration:

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

基路径使用 SetBasePath 设置。The base path is set with SetBasePath.

INI 配置文件的通用示例: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

以前的配置文件使用 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 配置提供程序JSON Configuration Provider

JsonConfigurationProvider 在运行时期间从 JSON 文件键值对加载配置。The JsonConfigurationProvider loads configuration from JSON file key-value pairs during runtime.

若要激活 JSON 文件配置,请在 ConfigurationBuilder 的实例上调用 AddJsonFile 扩展方法。To activate JSON file configuration, call the AddJsonFile extension method on an instance of ConfigurationBuilder.

重载允许指定:Overloads permit specifying:

  • 文件是否可选。Whether the file is optional.
  • 如果文件更改,是否重载配置。Whether the configuration is reloaded if the file changes.
  • IFileProvider 用于访问该文件。The IFileProvider used to access the file.

若使用 CreateDefaultBuilder 初始化新的主机生成器,则自动调用两次 AddJsonFileAddJsonFile is automatically called twice when you initialize a new host builder with CreateDefaultBuilder. 调用该方法来从以下文件加载配置:The method is called to load configuration from:

  • appsettings.json – 首先读取此文件。appsettings.json – This file is read first. 该文件的环境版本可以替代 appsettings.json 文件提供的值。The environment version of the file can override the values provided by the appsettings.json file.
  • appsettings.{Environment}.json– 根据 IHostingEnvironment.EnvironmentName 加载文件的环境版本。appsettings.{Environment}.json – The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName.

有关详细信息,请参阅默认配置部分。For more information, see the Default configuration section.

此外,CreateDefaultBuilder 也会加载:CreateDefaultBuilder also loads:

首先建立 JSON 配置提供程序。The JSON Configuration Provider is established first. 因此,用户机密、环境变量和命令行参数会替代由 appsettings 文件设置的配置。Therefore, user secrets, environment variables, and command-line arguments override configuration set by the appsettings files.

构建主机时调用 ConfigureAppConfiguration 以指定除 appsettings.json 和 appsettings.{Environment}.json 以外的文件的应用配置: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.SetBasePath(Directory.GetCurrentDirectory());
    config.AddJsonFile(
        "config.json", optional: true, reloadOnChange: true);
})

基路径使用 SetBasePath 设置。The base path is set with SetBasePath.

示例Example

示例应用利用静态便捷方法 CreateDefaultBuilder 来生成主机,其中包括两个对 AddJsonFile 的调用。The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes two calls to AddJsonFile. 配置从 appsettings.json 和 appsettings.{Environment}.json 进行加载。Configuration is loaded from appsettings.json and appsettings.{Environment}.json.

  1. 运行示例应用。Run the sample app. http://localhost:5000 打开应用的浏览器。Open a browser to the app at http://localhost:5000.
  2. 观察输出是否包含表中所示的配置的键值对,具体取决于环境。Observe that the output contains key-value pairs for the configuration shown in the table depending on the environment. 记录配置键使用冒号 (:) 作为分层分隔符。Logging configuration keys use the colon (:) as a hierarchical separator.
Key 开发值Development Value 生产值Production Value
Logging:LogLevel:SystemLogging:LogLevel:System 信息Information 信息Information
Logging:LogLevel:MicrosoftLogging:LogLevel:Microsoft 信息Information 信息Information
Logging:LogLevel:DefaultLogging:LogLevel:Default 调试Debug 错误Error
AllowedHostsAllowedHosts * *

XML 配置提供程序XML Configuration Provider

XmlConfigurationProvider 在运行时从 XML 文件键值对加载配置。The XmlConfigurationProvider loads configuration from XML file key-value pairs at runtime.

若要激活 XML 文件配置,请在 ConfigurationBuilder 的实例上调用 AddXmlFile 扩展方法。To activate XML file configuration, call the AddXmlFile extension method on an instance of ConfigurationBuilder.

重载允许指定:Overloads permit specifying:

  • 文件是否可选。Whether the file is optional.
  • 如果文件更改,是否重载配置。Whether the configuration is reloaded if the file changes.
  • IFileProvider 用于访问该文件。The IFileProvider used to access the file.

创建配置键值对时,将忽略配置文件的根节点。The root node of the configuration file is ignored when the configuration key-value pairs are created. 不要在文件中指定文档类型定义 (DTD) 或命名空间。Don't specify a Document Type Definition (DTD) or namespace in the file.

构建主机时调用 ConfigureAppConfiguration 以指定应用的配置:Call ConfigureAppConfiguration when building the host to specify the app's configuration:

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

基路径使用 SetBasePath 设置。The base path is set with SetBasePath.

XML 配置文件可以为重复节使用不同的元素名称: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>

以前的配置文件使用 value 加载以下键:The previous configuration file loads the following keys with value:

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

如果使用 name 属性来区分元素,则使用相同元素名称的重复元素可以正常工作: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>

以前的配置文件使用 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

属性可用于提供值:Attributes can be used to supply values:

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

以前的配置文件使用 value 加载以下键:The previous configuration file loads the following keys with value:

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

Key-per-file 配置提供程序Key-per-file Configuration Provider

KeyPerFileConfigurationProvider 使用目录的文件作为配置键值对。The KeyPerFileConfigurationProvider uses a directory's files as configuration key-value pairs. 该键是文件名。The key is the file name. 该值包含文件的内容。The value contains the file's contents. Key-per-file 配置提供程序用于 Docker 托管方案。The Key-per-file Configuration Provider is used in Docker hosting scenarios.

若要激活 Key-per-file 配置,请在 ConfigurationBuilder 的实例上调用 AddKeyPerFile 扩展方法。To activate key-per-file configuration, call the AddKeyPerFile extension method on an instance of ConfigurationBuilder. 文件的 directoryPath 必须是绝对路径。The directoryPath to the files must be an absolute path.

重载允许指定:Overloads permit specifying:

  • 配置源的 Action<KeyPerFileConfigurationSource> 委托。An Action<KeyPerFileConfigurationSource> delegate that configures the source.
  • 目录是否可选以及目录的路径。Whether the directory is optional and the path to the directory.

双下划线字符 (__) 用作文件名中的配置键分隔符。The double-underscore (__) is used as a configuration key delimiter in file names. 例如,文件名 Logging__LogLevel__System 生成配置键 Logging:LogLevel:SystemFor example, the file name Logging__LogLevel__System produces the configuration key Logging:LogLevel:System.

构建主机时调用 ConfigureAppConfiguration 以指定应用的配置:Call ConfigureAppConfiguration when building the host to specify the app's configuration:

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

基路径使用 SetBasePath 设置。The base path is set with SetBasePath.

内存配置提供程序Memory Configuration Provider

MemoryConfigurationProvider 使用内存中集合作为配置键值对。The MemoryConfigurationProvider uses an in-memory collection as configuration key-value pairs.

若要激活内存中集合配置,请在 ConfigurationBuilder 的实例上调用 AddInMemoryCollection 扩展方法。To activate in-memory collection configuration, call the AddInMemoryCollection extension method on an instance of ConfigurationBuilder.

可以使用 IEnumerable<KeyValuePair<String,String>> 初始化配置提供程序。The configuration provider can be initialized with an IEnumerable<KeyValuePair<String,String>>.

构建主机时调用 ConfigureAppConfiguration 以指定应用的配置。Call ConfigureAppConfiguration when building the host to specify the app's configuration.

在下面的示例中,创建了配置字典:In the following example, a configuration dictionary is created:

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

通过 AddInMemoryCollection 的调用使用字典,以提供配置:The dictionary is used with a call to AddInMemoryCollection to provide the configuration:

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

GetValueGetValue

ConfigurationBinder.GetValue<T> 从配置中提取一个具有指定键的值,并将其转换为指定类型。ConfigurationBinder.GetValue<T> extracts a value from configuration with a specified key and converts it to the specified type. 如果未找到该键,则过载允许你提供默认值。An overload permits you to provide a default value if the key isn't found.

如下示例中:The following example:

  • 使用键 NumberKey 从配置中提取字符串值。Extracts the string value from configuration with the key NumberKey. 如果在配置键中找不到 NumberKey,则使用默认值 99If NumberKey isn't found in the configuration keys, the default value of 99 is used.
  • 键入值作为 intTypes the value as an int.
  • 存储 NumberConfig 属性中的值,以供页面使用。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 和 ExistsGetSection, GetChildren, and Exists

对于下面的示例,请考虑以下 JSON 文件。For the examples that follow, consider the following JSON file. 在两个节中找到四个键,其中一个包含一对子节: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"
    }
  }
}

将文件读入配置时,会创建以下唯一的分层键来保存配置值: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 使用指定的子节键提取配置子节。IConfiguration.GetSection extracts a configuration subsection with the specified subsection key.

若要返回仅包含 section1 中键值对的 IConfigurationSection,请调用 GetSection 并提供节名称:To return an IConfigurationSection containing only the key-value pairs in section1, call GetSection and supply the section name:

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

configSection 不具有值,只有密钥和路径。The configSection doesn't have a value, only a key and a path.

同样,若要获取 section2:subsection0 中键的值,请调用 GetSection 并提供节路径:Similarly, to obtain the values for keys in section2:subsection0, call GetSection and supply the section path:

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

GetSection 永远不会返回 nullGetSection never returns null. 如果找不到匹配的节,则返回空 IConfigurationSectionIf a matching section isn't found, an empty IConfigurationSection is returned.

GetSection 返回匹配的部分时,Value 未填充。When GetSection returns a matching section, Value isn't populated. 存在该部分时,返回一个 KeyPath 部分。A Key and Path are returned when the section exists.

GetChildrenGetChildren

section2 上调用 IConfiguration.GetChildren 会获得 IEnumerable<IConfigurationSection>,其中包括:A call to IConfiguration.GetChildren on section2 obtains an IEnumerable<IConfigurationSection> that includes:

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

var children = configSection.GetChildren();

存在Exists

使用 ConfigurationExtensions.Exists 确定配置节是否存在:Use ConfigurationExtensions.Exists to determine if a configuration section exists:

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

给定示例数据,sectionExistsfalse,因为配置数据中没有 section2:subsection2 节。Given the example data, sectionExists is false because there isn't a section2:subsection2 section in the configuration data.

绑定至类Bind to a class

可以使用选项模式将配置绑定到表示相关设置组的类。Configuration can be bound to classes that represent groups of related settings using the options pattern. 有关详细信息,请参阅 ASP.NET Core 中的选项模式For more information, see ASP.NET Core 中的选项模式.

配置值作为字符串返回,但调用 Bind 可以构造 POCO 对象。Configuration values are returned as strings, but calling Bind enables the construction of POCO objects.

示例应用包含 Starship 模型 (Models/Starship.cs):The sample app contains a Starship model (Models/Starship.cs):

public class Starship
{
    public string Name { get; set; }
    public string Registry { get; set; }
    public string Class { get; set; }
    public decimal Length { get; set; }
    public bool Commissioned { get; set; }
}
public class Starship
{
    public string Name { get; set; }
    public string Registry { get; set; }
    public string Class { get; set; }
    public decimal Length { get; set; }
    public bool Commissioned { get; set; }
}

当示例应用使用 JSON 配置提供程序加载配置时,starship.json 文件的 starship 节会创建配置:The starship section of the starship.json file creates the configuration when the sample app uses the JSON Configuration Provider to load the configuration:

{
  "starship": {
    "name": "USS Enterprise",
    "registry": "NCC-1701",
    "class": "Constitution",
    "length": 304.8,
    "commissioned": false
  },
  "trademark": "Paramount Pictures Corp. http://www.paramount.com"
}
{
  "starship": {
    "name": "USS Enterprise",
    "registry": "NCC-1701",
    "class": "Constitution",
    "length": 304.8,
    "commissioned": false
  },
  "trademark": "Paramount Pictures Corp. http://www.paramount.com"
}

创建以下配置键值对:The following configuration key-value pairs are created:

Key Value
starship:namestarship:name USS EnterpriseUSS Enterprise
starship:registrystarship:registry NCC-1701NCC-1701
starship:classstarship:class ConstitutionConstitution
starship:lengthstarship:length 304.8304.8
starship:commissionedstarship:commissioned FalseFalse
trademarktrademark Paramount Pictures Corp. https://www.paramount.comParamount Pictures Corp. https://www.paramount.com

示例应用使用 starship 键调用 GetSectionThe sample app calls GetSection with the starship key. starship 键值对是独立的。The starship key-value pairs are isolated. 在子节传入 Starship 类的实例时调用 Bind 方法。The Bind method is called on the subsection passing in an instance of the Starship class. 绑定实例值后,将实例分配给用于呈现的属性:After binding the instance values, the instance is assigned to a property for rendering:

var starship = new Starship();
_config.GetSection("starship").Bind(starship);
Starship = starship;
var starship = new Starship();
_config.GetSection("starship").Bind(starship);
Starship = starship;

绑定至对象图Bind to an object graph

Bind 能够绑定整个 POCO 对象图。Bind is capable of binding an entire POCO object graph.

该示例包含 TvShow 模型,其对象图包含 MetadataActors 类 (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; }
}
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; }
}

示例应用有一个包含配置数据的 tvshow.xml 文件: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>
<?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>

使用 Bind 方法将配置绑定到整个 TvShow 对象图。Configuration is bound to the entire TvShow object graph with the Bind method. 将绑定实例分配给用于呈现的属性:The bound instance is assigned to a property for rendering:

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

ConfigurationBinder.Get<T> 绑定并返回指定类型。ConfigurationBinder.Get<T> binds and returns the specified type. Get<T> 比使用 Bind 更方便。Get<T> is more convenient than using Bind. 以下代码显示如何将 Get<T> 与前面的示例一起使用,该示例允许将绑定实例直接分配给用于呈现的属性:The following code shows how to use Get<T> with the preceding example, which allows the bound instance to be directly assigned to the property used for rendering:

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

将数组绑定至类Bind an array to a class

示例应用演示了本部分中介绍的概念。The sample app demonstrates the concepts explained in this section.

Bind 支持使用配置键中的数组索引将数组绑定到对象。The Bind supports binding arrays to objects using array indices in configuration keys. 公开数字键段(:0::1:、… :{n}:)的任何数组格式都能够与 POCO 类数组进行数组绑定。Any array format that exposes a numeric key segment (:0:, :1:, … :{n}:) is capable of array binding to a POCO class array.

备注

绑定是按约定提供的。Binding is provided by convention. 不需要自定义配置提供程序实现数组绑定。Custom configuration providers aren't required to implement array binding.

内存中数组处理In-memory array processing

请考虑下表中所示的配置键和值。Consider the configuration keys and values shown in the following table.

Key Value
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

使用内存配置提供程序在示例应用中加载这些键和值: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)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                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);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}
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.SetBasePath(Directory.GetCurrentDirectory());
                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>();
}

该数组跳过索引 #3 的值。The array skips a value for index #3. 配置绑定程序无法绑定 null 值,也无法在绑定对象中创建 null 条目,这在演示将此数组绑定到对象的结果时变得清晰。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.

在示例应用中,POCO 类可用于保存绑定的配置数据:In the sample app, a POCO class is available to hold the bound configuration data:

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

将配置数据绑定至对象:The configuration data is bound to the object:

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

还可以使用 ConfigurationBinder.Get<T> 语法,这样会得到更精简的代码:ConfigurationBinder.Get<T> syntax can also be used, which results in more compact code:

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

绑定对象(ArrayExample 的实例)从配置接收数组数据。The bound object, an instance of ArrayExample, receives the array data from configuration.

ArrayExample.Entries 索引ArrayExample.Entries Index ArrayExample.EntriesArrayExample.Entries Value
00 value0value0
11 value1value1
22 value2value2
33 value4value4
44 value5value5

绑定对象中的索引 #3 保留 array:4 配置键的配置数据及其值 value4Index #3 in the bound object holds the configuration data for the array:4 configuration key and its value of value4. 当绑定包含数组的配置数据时,配置键中的数组索引仅用于在创建对象时迭代配置数据。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. 无法在配置数据中保留 null 值,并且当配置键中的数组跳过一个或多个索引时,不会在绑定对象中创建 null 值条目。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.

可以在由任何在配置中生成正确键值对的配置提供程序绑定到 ArrayExample 实例之前提供索引 #3 的缺失配置项。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. 如果示例包含具有缺失键值对的其他 JSON 配置提供程序,则 ArrayExample.Entries 与完整配置数组相匹配: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"
}

ConfigureAppConfiguration中:In ConfigureAppConfiguration:

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

将表中所示的键值对加载到配置中。The key-value pair shown in the table is loaded into configuration.

Key Value
array:entries:3array:entries:3 value3value3

如果在 JSON 配置提供程序包含索引 #3 的条目之后绑定 ArrayExample 类实例,则 ArrayExample.Entries 数组包含该值。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 索引ArrayExample.Entries Index ArrayExample.EntriesArrayExample.Entries Value
00 value0value0
11 value1value1
22 value2value2
33 value3value3
44 value4value4
55 value5value5

JSON 数组处理JSON array processing

如果 JSON 文件包含数组,则会为具有从零开始的节索引的数组元素创建配置键。If a JSON file contains an array, configuration keys are created for the array elements with a zero-based section index. 在以下配置文件中,subsection 是一个数组:In the following configuration file, subsection is an array:

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

JSON 配置提供程序将配置数据读入以下键值对:The JSON Configuration Provider reads the configuration data into the following key-value pairs:

Key Value
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

在示例应用中,以下 POCO 类可用于绑定配置键值对: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; }
}
public class JsonArrayExample
{
    public string Key { get; set; }
    public string[] Subsection { get; set; }
}

绑定后,JsonArrayExample.Key 保存值 valueAAfter binding, JsonArrayExample.Key holds the value valueA. 子节值存储在 POCO 数组属性 Subsection 中。The subsection values are stored in the POCO array property, Subsection.

JsonArrayExample.Subsection 索引JsonArrayExample.Subsection Index JsonArrayExample.SubsectionJsonArrayExample.Subsection Value
00 valueBvalueB
11 valueCvalueC
22 valueDvalueD

自定义配置提供程序Custom configuration provider

该示例应用演示了如何使用实体框架 (EF) 创建从数据库读取配置键值对的基本配置提供程序。The sample app demonstrates how to create a basic configuration provider that reads configuration key-value pairs from a database using Entity Framework (EF).

提供程序具有以下特征:The provider has the following characteristics:

  • EF 内存中数据库用于演示目的。The EF in-memory database is used for demonstration purposes. 若要使用需要连接字符串的数据库,请实现辅助 ConfigurationBuilder 以从另一个配置提供程序提供连接字符串。To use a database that requires a connection string, implement a secondary ConfigurationBuilder to supply the connection string from another configuration provider.
  • 提供程序在启动时将数据库表读入配置。The provider reads a database table into configuration at startup. 提供程序不会基于每个键查询数据库。The provider doesn't query the database on a per-key basis.
  • 未实现更改时重载,因此在应用启动后更新数据库对应用的配置没有任何影响。Reload-on-change isn't implemented, so updating the database after the app starts has no effect on the app's configuration.

定义用于在数据库中存储配置值的 EFConfigurationValue 实体。Define an EFConfigurationValue entity for storing configuration values in the database.

Models/EFConfigurationValue.csModels/EFConfigurationValue.cs:

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

添加 EFConfigurationContext 以存储和访问配置的值。Add an EFConfigurationContext to store and access the configured values.

EFConfigurationProvider/EFConfigurationContext.csEFConfigurationProvider/EFConfigurationContext.cs:

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

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

创建用于实现 IConfigurationSource 的类。Create a class that implements IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.csEFConfigurationProvider/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);
    }
}

通过从 ConfigurationProvider 继承来创建自定义配置提供程序。Create the custom configuration provider by inheriting from ConfigurationProvider. 当数据库为空时,配置提供程序将对其进行初始化。The configuration provider initializes the database when it's empty.

EFConfigurationProvider/EFConfigurationProvider.csEFConfigurationProvider/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>
            {
                { "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;
    }
}

可以使用 AddEFConfiguration 扩展方法将配置源添加到 ConfigurationBuilderAn 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));
    }
}

下面的代码演示如何在 Program.cs 中使用自定义的 EFConfigurationProviderThe 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)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                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);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Models/EFConfigurationValue.csModels/EFConfigurationValue.cs:

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

添加 EFConfigurationContext 以存储和访问配置的值。Add an EFConfigurationContext to store and access the configured values.

EFConfigurationProvider/EFConfigurationContext.csEFConfigurationProvider/EFConfigurationContext.cs:

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

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

创建用于实现 IConfigurationSource 的类。Create a class that implements IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.csEFConfigurationProvider/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);
    }
}

通过从 ConfigurationProvider 继承来创建自定义配置提供程序。Create the custom configuration provider by inheriting from ConfigurationProvider. 当数据库为空时,配置提供程序将对其进行初始化。The configuration provider initializes the database when it's empty.

EFConfigurationProvider/EFConfigurationProvider.csEFConfigurationProvider/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>
            {
                { "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;
    }
}

可以使用 AddEFConfiguration 扩展方法将配置源添加到 ConfigurationBuilderAn 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));
    }
}

下面的代码演示如何在 Program.cs 中使用自定义的 EFConfigurationProviderThe 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.SetBasePath(Directory.GetCurrentDirectory());
                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>();
}

在启动期间访问配置Access configuration during startup

IConfiguration 注入 Startup 构造函数以访问 Startup.ConfigureServices 中的配置值。Inject IConfiguration into the Startup constructor to access configuration values in Startup.ConfigureServices. 若要访问 Startup.Configure 中的配置,请将 IConfiguration 直接注入方法或使用构造函数中的实例: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"];
    }
}

有关使用启动便捷方法访问配置的示例,请参阅应用启动:便捷方法For an example of accessing configuration using startup convenience methods, see App startup: Convenience methods.

在 Razor Pages 页或 MVC 视图中访问配置Access configuration in a Razor Pages page or MVC view

若要访问 Razor Pages 页或 MVC 视图中的配置设置,请为 Microsoft.Extensions.Configuration 命名空间添加 using 指令C# 参考:using 指令)并将 IConfiguration 注入页面或视图。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.

在 Razor 页面页中: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>

在 MVC 视图中: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>

从外部程序集添加配置Add configuration from an external assembly

通过 IHostingStartup 实现,可在启动时从应用 Startup 类之外的外部程序集向应用添加增强功能。An IHostingStartup implementation allows adding enhancements to an app at startup from an external assembly outside of the app's Startup class. 有关详细信息,请参阅 在 ASP.NET Core 中使用承载启动程序集For more information, see 在 ASP.NET Core 中使用承载启动程序集.

其他资源Additional resources