asp.net core 系列 10 配置configuration (上)

一.  ASP.NET Core 中的配置概述

　　ASP.NET Core 中的应用配置是基于键值对，由configuration 程序提供。 configuration  将从各种配置源提供程序操作键值对，这些配置源可以是：

　　　　(1) Azure Key Vault(是基于云的服务的安全存储应用机密)

　　　　(2) 命令行参数

　　　　(3)（已安装或已创建的）自定义提供程序(自定义实现IConfigurationSource)

　　　　(4) 目录文件(Key-per-file)

　　　　(5) 环境变量(EnvironmentVariables)

　　　　(6) 内存中的 .NET 对象

　　　　(7) 设置文件(从文件系统加载配置)

　　configuration 程序提供配置依赖于以下内容，本章后面都会介绍具体使用：

　　　　(1) 使用 SetBasePath 设置应用程序的基本路径。 通过引用 Microsoft.Extensions.Configuration.FileExtensions 包，可以向应用提供 SetBasePath。

　　　　(2) 使用 GetSection 解析配置文件的各个部分。 通过引用 Microsoft.Extensions.Configuration 包向应用提供 GetSection。

　　　　(3) 使用 Bind 和 Get<T> 将配置绑定到 .NET 类。 通过引用 Microsoft.Extensions.Configuration.Binder 包向应用提供 Bind 和 Get<T>。 ASP.NET Core 1.1 或更高版本中提供了 Get<T>。

　　1.1 文件分层结构数据

通过configuration  api 能够通过在配置键中使用分隔符来保持分层配置数据。说明白点就是约定的数据结构。通过configuration  api的GetSection 和 GetChildren 方法可用于读取配置数据中某节点的值，下面简单先演示下效果。示例在 appsettings.json文件中添加section 节点的结构化键值对。如下所示：

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*",
  "mykey": "d",

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

    public class Page1Model : PageModel
    {
        //using Microsoft.Extensions.Configuration;
        public Page1Model(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void OnGet()
        {
            string val = Configuration.GetSection("section0").GetSection("key0").Value;
           //val 值为： value
        }
    }

　　在OtherPages/page1中读取上面文件中的节点。上面通过服务的实现的IConfiguration并没有在程序中显示读取appsettings.json文件，那为什么能读出到该文件的键值对呢？ 本章带着这个问题在继续了解。

　　1.2 配置约定

　　　　应用的依赖关系注入 (DI) 容器中提供了 IConfiguration。在程序应用启动时，IConfiguration将按照指定的配置文件顺序读取配置源。

　　　　1) 配置来源中的键有以下约定：

　　　　　　(1) 键不区分大小写。比如能过GetSection读取时，可以不管大小写。

　　　　　　(2) 配置来源中设置相同键的值，则取配置来源中键上设置的最后一个值。比如appsettings.json与appsettings.{Environment}.json多个配置来源文件。

　　　　　　(3) 分层键。如在json文件中多个节点，冒号分隔符 (:) 适用于所有平台。而在环境变量的来源配置中，所有平台均支持采用双下划线 (__)。

　　　　　　(4) ConfigurationBinder 支持使用配置键中的数组索引将数组绑定到类对象。

　　　　2) 配置值采用以下约定：

　　　　　　(1) 值是字符串。

　　　　　　(2) NULL 值不能存储在配置中或绑定到对象。

　　1.3 配置来源提供程序的顺序

　　　　对于上面的7种配置来源提供程序，IConfiguration操作的顺序是按照启动时指定的配置顺序操作配置源。在ConfigureAppConfiguration代码中设置的配置源提供程序，应以特定顺序排列以符合基础配置源的优先级。典型顺序为：

　　　　(1) 文件（appsettings.json、appsettings.{Environment}.json，其中 {Environment} 是应用的当前托管环境）。

　　　　(2) Azure 密钥保管库。

　　　　(3) 用户机密 (Secret Manager)（仅限开发环境中）。

　　　　(4) 环境变量。

　　　　(5) 命令行参数。

　　　　通常的做法是将命令行配置提供程序置于一系列提供程序的末尾，以允许命令行参数替代由其他提供程序设置的配置。在使用 CreateDefaultBuilder 初始化新的 WebHostBuilder 时，将使用此提供程序序列。

　　　　上面讲到为什么会自动读取appsettings.json文件瞒下的伏笔。在这里有了答案。Configuration提供程序默认会读取appsettings.json、appsettings.{Environment}.json。

　　　　

　　1.4 ConfigureAppConfiguration 添加配置提供程序

　　　　 构建 Web 主机时调用 ConfigureAppConfiguration 以指定应用的配置提供程序以及 CreateDefaultBuilder 自动添加的配置提供程序：

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

        /// <summary>
        /// Configuration Providers示例
        /// </summary>
        /// <param name="args"></param>
        /// <returns></returns>
        public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                        //显示设置当前程序运行目录
                        config.SetBasePath(Directory.GetCurrentDirectory());
                        //设置内存中的 .NET 对象
                        config.AddInMemoryCollection(arrayDict);
                        //设置文件, optional选择项为false时 必需存在该文件
                        config.AddJsonFile("json_array.json", optional: false, reloadOnChange: false);
                        config.AddJsonFile("starship.json", optional: true, reloadOnChange: false);
                        config.AddXmlFile("tvshow.xml", optional: true, reloadOnChange: false);
                        //EF以后在讲 自定义提供程序
                        // config.AddEFConfiguration(options => options.UseInMemoryDatabase("InMemoryDb"));
                        //最后设置命令行参数
                        config.AddCommandLine(args);
                })
                .UseStartup<Startup>();

二. 命令行配置提供程序 AddCommandLine

　　CommandLineConfigurationProvider 在运行时从命令行参数键值对加载配置,要激活命令行配置，请在 ConfigurationBuilder 的实例上调用 AddCommandLine 扩展方法。 如果需要使用命令行参数覆盖其它配置，请在 ConfigureAppConfiguration 中调用应用的其他提供程序并最后调用 AddCommandLine。

　　下面示例，使用控制台作为启动程序。打开cmd  输入dotnet命令,在后面输入命令行配置参数CommandLineKey1=value1， 在浏览器page2中显示该命令行配置value值。

        public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                    // Call other providers here and call AddCommandLine last.
                    config.AddCommandLine(args);
                })
                .UseStartup<Startup>();

    -- page2页面获取命令行
    @using Microsoft.Extensions.Configuration;
    @inject IConfiguration Configuration;
    <p>Configuration CommandLine value for     'key':@Configuration["CommandLineKey1"] </p>

　　　　2.1 命令行配置自变量示例　

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

　　　　

　　　　2.2 交换映射

　　　　交换映射字典键规则：(1)交换必须以单划线 (-) 或双划线 (--) 开头 。(2) 交换映射字典不得包含重复键。下面是一个示例：

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

      config.AddCommandLine(args, _switchMappings);

　　　　创建交换映射字典后，它将包含下表所示的数据。

键	值
-CLKey1	CommandLineKey1
-CLKey2	CommandLineKey2

　　　　

三. 环境变量配置提供程序 AddEnvironmentVariables

　　EnvironmentVariablesConfigurationProvider 在运行时从环境变量键值对加载配置。要激活环境变量配置，请在 ConfigurationBuilder 的实例上调用 AddEnvironmentVariables 扩展方法。

　　环境变量配置提供程序是在用户机密 (Secret Manager)和 appsettings.json 文件建立后调用。 调用AddEnvironmentVariables方法具有重载， 如果调用没有给前缀参数，则具有表中所示前缀的环境变量将加载到应用中。 如果有向 AddEnvironmentVariables 提供前缀，将筛选加载到应用的配置中的环境变量。

　　下面示例为 AddEnvironmentVariables 方法提供前缀，添加要筛选前缀 ASPNETCORE_上的环境变量。将筛选加载到应用的配置中的环境变量。

    //添加具有指定前缀的环境变量的配置值。
    config.AddEnvironmentVariables(prefix: "ASPNETCORE_");

　　下面显示的是ASPNETCORE_为前缀的主机的配置信息。主机配置格式 ASPNETCORE_{configurationKey} 的环境变量。 例如 ASPNETCORE_ENVIRONMENT。关于ASPNETCORE_前缀的环境信息可参考“主机配置值”。下面是Configuration从查看ASPNETCORE_为前缀的主机的配置信息。

参考文献

官方资料:asp.net core 配置