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

一.  asp.net core 中的配置概述

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

　　　　(1) azure key vault

　　　　(2) 命令行参数

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

　　　　(4) 目录文件

　　　　(5) 环境变量

　　　　(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_为前缀的主机的配置信息。

 

参考文献

官方资料: