zoukankan html css js c++ java

ASP.NET Core 中的配置【上】

此为系列文章，对MSDN ASP.NET Core 的官方文档进行系统学习与翻译。其中或许会添加本人对 ASP.NET Core 的浅显理解。

ASP.NET Core中的应用程序配置是基于配置提供器建立的键值对的。配置提供器从各种配置源中读取配置数据到键值对中。配置源包含如下：

Azure密钥库
Azure应用程序配置
命令行参数
自定义提供器（装载的或者新建的）
字典文件
环境变量
内存中.NET对象
设置文件

通用配置提供器场景的配置Pakages隐式的包含在框架中。

接下来以及在示例中的代码使用了Microsoft.Extensions.Configuration 命名空间。

using Microsoft.Extensions.Configuration;

选项模式是本章描述的配置概念的一个扩展。选项模式使用类来代表一组相关的配置。更多信息，请参考Options pattern in ASP.NET Core。

View or download sample code (how to download)

宿主与App 配置

在app被配置以及启动之前，一个宿主会被配置和加载。宿主负责app的启动以及生命周期管理。app以及宿主都会使用本章描述的配置提供器进行配置。宿主配置键值对会包含在app配置中。关于在宿主被建立时，配置提供器如何使用以及配置源如何影响宿主配置的更多信息，请参考ASP.NET Core fundamentals。

其他配置

本章主题仅仅适用于app.configration。运行以及寄宿ASP.NET Core apps的其他方面将使用其他配置文件进行配置，其不包含在本章主题之中。

launch.json/launchSettings.json 是用于开发环境的工具配置文件，其在如下主题中会有所描述：
- 在Use multiple environments in ASP.NET Core中。
- 在被用来配置开发环境的ASP.NET Core文档集合中。
web.config是一个服务器配置文件，其在如下主题中会有所描述：
- Host ASP.NET Core on Windows with IIS
- ASP.NET Core Module

关于从早期版本的ASP.NET 中迁移配置文件的更多信息，请参考：Migrate from ASP.NET to ASP.NET Core。

默认配置

基于ASP.NET Core dotnet new 模板创建的web app在建立一个宿主的时候会调用CreateDefaultBuilder。CreateDefaultBuilder 按照如下顺序为app 提供默认的配置：

以下内容适用于使用了Generic Host 的app。当使用Web Host时，关于默认配置的更多信息，请参考ASP.NET Core 2.2 version of this topic。

宿主配置从如下位置被提供：
- 带有DOTNET_前缀的环境变量（比如DOTNET_ENVIRONMENT），其使用Environment Variables Configuration Provider。当配置键值对被加载的时候，前缀DOTNET_会被移除。
- 命令行参数，其使用Command-line Configuration Provider。
Web宿主默认配置会被键立（ConfigureWebHostDefaults）：
- Kestrel 被用作web 服务器并使用app的配置提供器进行配置。
- 添加宿主过滤中间件。
- 如果ASPNETCORE_FORWARDEDHEADERS_ENABLED 环境变量被设置为true，那么会添加Forwarded Headers中间件。
- 启用IIS整合。
从如下位置提供app配置：
- appsettings.json，其使用 File Configuration Provider。
- appsettings.{Environment}.json，其使用File Configuration Provider。
- Secret Manager，当app运行在开发环境中时，其使用入口点程序集。
- 环境变量，其使用Environment Variables Configuration Provider。
- 命令行参数，其使用the Command-line Configuration Provider。

安全

对于安全敏感的配置数据采取以下实践：

绝对不要将密码以及其他敏感数据存储在配置提供器代码中，或者在纯文本配置文件中。
在开发环境以及测试环境中，不要使用生产环境的密钥。
将密钥在项目工程之外指定，这样它们便不会被自动提交给源码库。

更多信息，请参考如下主题：

在ASP.NET Core使用多个环境。
ASP.NET Core开发环境中密钥的安全存储 —— 包括使用环境变量来存储敏感数据的建议。密钥管理器（Secret Manager）使用文件配置提供器来将用户密钥存储在本地系统的Json文件中。文件配置提供器在本章后续会进行描述。

Azure密钥库为ASP.NET Core app安全的存储app密钥。更多信息，请参考Azure Key Vault Configuration Provider in ASP.NET Core。

层次化的配置数据

配置API可用维护层次化的配置数据，器通过使用配置键中的分号（；）来将层次化的数据扁平化。

在如下的Json文件中，四个键值存在于两部分组成的结构化的等级制度中。

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

当文件被读入到配置中，会创建唯一的键值来维护原始的来自于配置源的层次化数据结构。我们使用一个冒号来将部分以及键值进行扁平化处理，以维护原始的数据结构：

section0:key0
section0:key1
section1:key0
section1:key1

GetSection 以及 GetChildren 方法可用来分离开各个部分以及它们的子节点。这些方法在GetSection, GetChildren, and Exists 中会有描述。

惯例

源以及提供器

在app启动时，配置源被按照器配置提供器被指定的顺序被读取。

实现了更新检测的提供器当底层的设置被更新时可以重加载配置。举个例子，文件配置提供器（本章后续会有描述）以及Azure Key Vault Configuration Provider 都实现了更改探测。

IConfiguration 在app 的DI容器中是可用的。IConfiguration 可以被注入到一个Razor页面的 PageModel 中或者是 MVC的Controller 中，从而为这个类获取配置数据。

在如下的示例中，_config 字段被用来访问配置值：

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;
    }
}

配置提供器不能使用DI，因为当它们被宿主建立的时候DI还是不可用的。

键

配置键值采取了如下约定：

键是大小写不敏感的。举个例子，ConnectionString和connectionstring 被当作相等的键。
如果一个相同键的值被相同或者不同的配置提供器所设置，那么最后一个设置的值将会被使用。
层次化的键值
- 在配置API之内，冒号分隔符在所有的平台都能工作。
- 在环境变量中，冒号分隔符可能不能在所有的平台下都能工作。但双下划线（__）会被所有的平台支持，并自动转换为一个冒号。
- 在Azure密钥库中，层次化的键值使用（--）作为一个分隔符。当密钥被加载到app的配置中的时候，需要些代码来使用冒号将（-）替换掉。
ConfigurationBinder 支持将数组绑定到对象，数组绑定在Bind an array to a class 章节会有相应的介绍。

值

配置值采取如下的约定：

值都是字符串。
空值不能被存储在配置中或者绑定给对象。

提供器

下列表格展示了ASP.NET Core app中可用的配置提供器：

Provider	Provides configuration from…
Azure Key Vault Configuration Provider (Security topics)	Azure Key Vault
Azure App Configuration Provider (Azure documentation)	Azure App Configuration
Command-line Configuration Provider	Command-line parameters
Custom configuration provider	Custom source
Environment Variables Configuration Provider	Environment variables
File Configuration Provider	Files (INI, JSON, XML)
Key-per-file Configuration Provider	Directory files
Memory Configuration Provider	In-memory collections
User secrets (Secret Manager) (Security topics)	File in the user profile directory

在app启动时，配置源按照其配置提供器指定的顺序被读取。本章描述的配置提供器是按照字符顺序，而不是代码安排它们的顺序来描述的。在代码中对配置提供器进行排序以匹配app所需要的底层配置源的优先级。

一个典型的配置提供器序列是：

文件（appsettings.json, appsettings.{Environment}.json, 其中{Environment} 是应用程序的当前寄宿环境）
Azure密钥库
用户密钥（Secret Manager）（仅针对开发环境）
环境变量
命令行参数

一个通用的实践是将命令行配置提供器放置在一系列提供器的最后，以允许命令行参数重载被其他提供器设置的配置。

当一个新的宿主被使用CreateDefaultBuilder来初始化的时候，上面的提供器序列会被使用。更多信息，请参考Default configuration 章节。

使用ConfigureHostConfiguration来配置宿主构造器

为了配置宿主构造器，可以调用ConfigureHostConfiguration 并提供配置数据。ConfigureHostConfiguration 用来初始化IHostEnvironment 以供后续构造进程使用。ConfigureHostConfiguration 可以被调用多次以产生额外的结果。

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>();
        });

ConfigureAppConfiguration

当构造宿主时候可以调用ConfigureAppConfiguration 以指定除了被CreateDefaultBuilder自动添加的之外其他的app的配置提供器。

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.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>();
            });
}

使用命令行参数重载之前的配置

为了提供可被命令行参数重载的配置，可以在最后调用AddCommandLine：

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

移除被CreateDefaultBuilder 添加的提供器

为了移除被CreateDefaultBuilder 添加的提供器，可以首先在IConfigurationBuilder.Sources 上调用Clear。

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

在app启动时消费配置

在ConfigureAppConfiguration中提供给app的配置在app的启动阶段是可用的，包括Startup.ConfigureServices方法。更多信息，请参考Access configuration during startup 章节。

命令行配置提供器

CommandLineConfigurationProvider 在运行时从命令行参数键值对加载配置数据。

为了激活命令行配置，可以在ConfigurationBuilder的实例上调用AddCommandLine 扩展方法。

当调用CreateDefaultBuilder 方法时，AddCommandLine 方法会被自动调用。更多信息，请参考Default configuration 章节。

CreateDefaultBuilder 也会加载：

appsettings.json and appsettings.{Environment}.json 文件中可选的配置。
在开发环境中的User secrets (Secret Manager）。
环境变量。

CreateDefaultBuilder 最后会添加命令行配置提供器。运行时传递的命令行参数会重载被其他提供器设置的配置。

当宿主被构造时，CreateDefaultBuilder便会行动起来。因此，被CreateDefaultBuilder激活的命令行配置可以影响宿主如何被配置。

对于基于ASP.NET Core模板的app来说，AddCommandLine 已经被CreateDefaultBuilder 所调用。为了添加额外的配置提供器，并且维护使用命令行参数重载配置的能力，可以在ConfigureAppConfiguration中调用额外的提供器并最后调用AddCommandLine。

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

示例

示例app使用静态约定方法CreateDefaultBuilder来构建宿主，其包含了一个对AddCommandLine的调用。

在工程目录中打开一个命令提示符。
为dotnet run命令提供命令行参数：dotnet run CommandLineKey=CommandLineValue。
app运行之后，打开浏览器：http://localhost:5000。
可以观察到，输出包含了提供给dotnet run命令的键值对。

参数

参数值必须跟着一个=，或者当值跟随一个空格时，键值必须有一个前缀（-- 或 /），如果使用一个=号时，那么值不是必须的（比如 CommandLineKey=）。

Key prefix	Example
No prefix	`CommandLineKey1=value1`
Two dashes (`--`)	`--CommandLineKey2=value2`, `--CommandLineKey2 value2`
Forward slash (`/`)	`/CommandLineKey3=value3`, `/CommandLineKey3 value3`

但是在一个命令行内，最好不要混合使用两种形式的参数。示例命令：

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

交换映射

交换映射运行键名称替换逻辑。当使用ConfigurationBuilder 手动构建一个配置时，为AddCommandLine 方法提供一个交互替换的字典。

当交互映射字典被使用时，字典便会检查以寻找与命令行参数提供的键匹配的键。如果命令行键在字典中被找到，那么字典的值便会回传给app配置以设置键值对。对于任何具有前缀（-）的命令行键，都会需要一个交互映射。

交互映射字典键的规则：

必须以一个 - 或者两个 -- 开始。
交互映射字典不能包含重复的键。

创建一个交互映射字典。在下列示例中，两个交互映射被创建：

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

当宿主被构造时，使用交互映射字典为参数来调用AddCommandLine：

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

对于使用交互映射的app来说，对CreateDefaultBuilder 的调用不应该传递参数。CreateDefaultBuilder方法的AddCommandLine 调用不包含映射的交互。并且没有方法来给CreateDefaultBuilder传递交互映射字典。我们的解决方案并不是给CreateDefaultBuilder 传递参数，而是允许ConfigurationBuilder方法的AddCommandLine 方法来处理参数以及交互映射字典。

在交互映射字典被创建之后，其包含了下表所示的数据：

Key	Value
`-CLKey1`	`CommandLineKey1`
`-CLKey2`	`CommandLineKey2`

在app启动时，如果使用了交互映射字典，配置便会在字典提供的键值上接受配置值：

dotnet run -CLKey1=value1 -CLKey2=value2

运行上面的命令后，配置会包含下表所示的配置值：

Key     Value
CommandLineKey1     value1
CommandLineKey2     value2

查看全文

相关阅读:
牛客网暑期ACM多校训练营（第九场）D
有向图欧拉回路个数 BEST定理
 BZOJ 4894 有向图外向生成树个数
 HDU 3364 高斯消元
 HDU 6437 最(大) 小费用最大流
 高斯消元模板
 无向图生成树计数基尔霍夫矩阵 SPOJ Highways
HDU 6397 组合数学+容斥母函数
 第三章数据表示法
 第二章二进制数值和记数系统

原文地址：https://www.cnblogs.com/qianxingmu/p/12504285.html

ASP.NET Core 中的配置 【上】

ASP.NET Core 中的配置【上】