ASP.NET Core - 配置系统之配置提供程序

3. 配置提供程序

上面提到,通过 IConfigurationBuilder 的实现类对象,我们可以自由地往配置系统中添加不同的配置提供程序,从而获取不同来源的配置信息。.NET Core 中,微软提供了以下这些内置的配置提供程序:

  • 文件配置提供程序
  • 环境变量配置提供程序
  • 命令行配置提供程序
  • Azure应用配置提供程序
  • Azure Key Vault 配置提供程序
  • Key-per-file配置提供程序
  • 内存配置提供程序
  • 应用机密(机密管理器)
  • 自定义配置提供程序

这里稍微介绍一下常用的几个。

3.1 文件配置提供程序

顾名思义,这个就是我们熟悉的配置加载方式,从配置文件中加载配置信息。配置文件多种多样,.NET Core框架内置支持Json、xml、ini三种格式的文件提供程序:

  • JSON配置提供程序(JsonConfigurationProvider)
  • XML配置提供程序(XmlConfigurationProvider)
  • INI配置提供程序(IniConfigurationProvider)

以上这些配置提供程序,均继承于抽象基类 FileConfigurationProvider,当一个提供程序中发现重复的键时,提供程序会引发 FormatException,所有类型的文件提供程序都是这样的机制。

另外,所有文件配置提供程序都支持提供两个配置参数:

  • optional:bool类型,指示该文件是否是可选的。如果该参数为false,但是指定的文件又不存在,则会报错。
  • reloadOnChange:bool类型,指示该文件发生更改时,是否要重新加载配置。

3.1.1 JSON配置提供程序

JSON配置提供程序被封装在 Microsoft.Extensions.Configuration.Json Nuget包中,若通过 ConfigurationBuilder 自行构建配置系统需要先安装该依赖包。它通过 JsonConfigurationProvider 在运行时从 Json 文件中加载配置。

使用方式非常简单,通过 IConfigurationBuilder 的实现类对象调用 AddJsonFile 扩展方法指定Json配置文件的路径即可。以下代码可用于控制台程序中创建主机并设置配置系统:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

using var host = Host.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration((context, config) =>
    {
        // 清除原有的配置提供程序
        config.Sources.Clear();

        var env = context.HostingEnvironment;
        // 添加 json 配置文件
        config.AddJsonFile("appsettings.json",true, true)
            .AddJsonFile($"appsetting.{env.EnvironmentName}.json", true, true);
    })
    .Build();

var configuration = host.Services.GetService<IConfiguration>();

Console.WriteLine($"Settings:Provider: {configuration.GetValue<string>("Settings:Provider")}");

host.Run();

appsetting.json 配置文件中的内容如下:

{
  "Settings": {
    "Provider": "JsonProvider",
    "version": {
      "subKey1": "value",
      "subKey2": 1
    },
    "items": [ "item1", "item2", "item3" ]
  }
}

控制台程序运行之后输出如下:

image

这样有一点要注意的是,对于我们手动添加的配置文件需要设置一下文件属性,让其在项目生成的时候能够正常生成到运行目录,确保应用可以正常获取到该文件:

image

3.1.2 XML配置提供程序

XML配置提供程序被封装在 Microsoft.Extensions.Configuration.Xml Nuget包中,通过 XmlConfigurationProvider 类在运行时从 XML 文件加载配置。

使用方式也很简单,与 JSON 配置提供程序类似,通过 AddXmlFile 扩展方法指定配置文件路径。

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

using var host = Host.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration((context, config) =>
    {
        // 清除原有的配置提供程序
        config.Sources.Clear();

        var env = context.HostingEnvironment;
        //// 添加 json 配置文件
        //config.AddJsonFile("appsettings.json",true, true)
        //    .AddJsonFile($"appsetting.{env.EnvironmentName}.json", true, true);

        config.AddXmlFile("appsettings.xml", true, true);
    })
    .Build();

var configuration = host.Services.GetService<IConfiguration>();

Console.WriteLine($"Settings:Provider: {configuration.GetValue<string>("Settings:Provider")}");
Console.WriteLine($"Settings:items[1]: {configuration.GetValue<string>("Settings:items:1")}");

host.Run();

xml配置文件内容如下:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
	<Settings>
		<Provider>XmlProvider</Provider>
		<version>
			<subKey1>value</subKey1>
			<subKey2>1</subKey2>
		</version>
		<items>item1</items>
		<items>item2</items>
		<items>item3</items>
	</Settings>
</configuration>

运行程序控制台输出如下:

image

这里有一个和版本有关的点,对Xml文件中使用同一元素名称的重复元素,一般也就是数组,.NET 6及之后的xml配置提供程序会自动为其编制索引,不再需要显式指定name属性。如果是 .NET 6 以下的版本则需要这样了:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
	<Settings>
		<Provider>XmlProvider</Provider>
		<version>
			<subKey1>value</subKey1>
			<subKey2>1</subKey2>
		</version>
		<items name="itemkey1">item1</items>
		<items name="itemkey2">item2</items>
		<items name="itemkey3">item3</items>
	</Settings>
</configuration>
Console.WriteLine($"Settings:items[1]: {configuration.GetValue<string>("Settings:items:itemkey2")}");

另外xml文件中的属性也可用于提供值:

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

获取属性的值可用以下配置键:

key:attribute
section:key:attribute

3.1.3 INI配置提供程序

INI 配置提供程序被封装在 Microsoft.Extensions.Configuration.Ini Nuget包,通过 IniConfigurationProvider 类在运行时从 INI 文件加载配置。使用方式如下:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

using var host = Host.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration((context, config) =>
    {
        // 清除原有的配置提供程序
        config.Sources.Clear();

        var env = context.HostingEnvironment;
        //// 添加 json 配置文件
        //config.AddJsonFile("appsettings.json",true, true)
        //    .AddJsonFile($"appsetting.{env.EnvironmentName}.json", true, true);

        //config.AddXmlFile("appsettings.xml", true, true);

        config.AddIniFile("appsettings.ini", true, true);
    })
    .Build();

var configuration = host.Services.GetService<IConfiguration>();

Console.WriteLine($"Settings:Provider: {configuration.GetValue<string>("Settings:Provider")}");
Console.WriteLine($"Settings:items[1]: {configuration.GetValue<string>("Settings:items:1")}");

host.Run();

ini配置文件内容如下:

[Settings]
Provider="IniProvider"
version:subKey1="value"
version:subKey2=1
items:0="item1"
items:1="item2"
items:3="item3"

运行应用,控制台输出如下:
image

3.2 环境变量配置提供程序

环境变量配置提供程序被封装在 Microsoft.Extensions.Configuration.EnvironmentVariables, 通过 EnvironmentVariablesConfigurationProvider 在运行时从环境变量中以键值对的方式加载配置。

环境变量一般情况下是配置在机器上的,而不同的操作系统对环境变量的设置要求有所不同,当环境变量存在多层的时候,层级之间的分隔有些支持通过 : 号进行分隔,有些不支持,双下划线()是全平台支持的,所以设置环境变量的时候要使用双下划线()来代替冒号(:)。

各种不同的平台下怎么去添加环境变量这里就不细说了,Windows 下大家最起码都应该知道可以通过 我的电脑 -> 属性 -> 高级系统设置 去可视化的添加,命令行的方式可阅读下官方文章: ASP.NET Core 中的配置 | Microsoft Learn,Linux 平台下可以通过 export 命令临时添加,或者修改相应的配置文件 ~/.bashrc 或 /etc/profile,大家仔细查一下资料就行了。

处理在机器上直接设置环境变量外,我们开发测试的过程中也可以通过 ASP.NET Core框架下的 launchSettings.json 配置文件设置用于调试的临时环境变量。在应用启动调试时,该文件中的环境变量会替代系统的中的环境变量。

{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "ConfigurationSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "swagger",
      "applicationUrl": "http://localhost:5004",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "Custom_settings__Provider": "EnvironmentVariablesProvider",
        "Custom_settings__version__subKey1": "value",
        "Custom_settings__items__0": "item1",
        "Custom_settings__items__1": "item2",
        "Custom_settings__items__2": "item3"
      }
    }
  }
}

环境变量配置提供程序使用也很简单,注意以下示例为了使用 launchSettings.json 中的环境变量是在 ASP.NET Core项目中测试的。

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration(builder =>
{
    builder.Sources.Clear();
    // 筛选前置为 Custom_ 的环境变量,将其加载为应用配置,其他的不加载
    builder.AddEnvironmentVariables("Custom_");
});

var app = builder.Build();

Console.WriteLine($"Settings:Provider: {app.Configuration.GetValue<string>("Settings:Provider")}");
Console.WriteLine($"Settings:items[1]: {app.Configuration.GetValue<string>("Settings:items:1")}");

app.Run();

在添加环境变量时,通过指定参数 prefix,只读取限定前缀的环境变量。不过在读取环境变量时,会将前缀删除。如果不指定参数 prefix,那么会读取所有环境变量。

当创建默认通用主机(Host)时,默认就已经添加了前缀为 DOTNET_ 的环境变量,如果是在 ASP.NET Core 中,配置了 Web主机时,默认添加了前缀为 ASPNETCORE_ 的环境变量,而后主机加载应用配置时,再根据策略添加了其他的环境变量,如果没有传递 prefix 参数则是所有环境变量。这一块的加载机制,下面再细讲。

运行应用,控制台输出如下:
image

除此之外,环境变量提供程序还有一些隐藏的功能点,当没有向 AddEnvironmentVariables 传入前缀时,默认也会针对含有以下前缀的环境变量进行特殊处理:

image

这个功能点比较少用到,但是大家看到这个大概都会有点疑惑,具体的形式是怎么样的,下面稍微测试一下

首先在 launchSettings.json 文件中添加多一个环境变量:

"MYSQLCONNSTR_Default": "Server=myServerAddress;Database=myDataBase;Uid=myUsername;Pwd=myPassword;"

之后在应用中打印如下两个配置:

Console.WriteLine($"ConnectionStrings:Default: { app.Configuration.GetValue<string>("ConnectionStrings:Default") }");
Console.WriteLine($"ConnectionStrings:Default_Provider: { app.Configuration.GetValue<string>("ConnectionStrings:Default_ProviderName") }");

输出结果如下:
image

也就是说,这种形式的环境变量会被自动转换为两个。

3.3 命令行配置提供程序

命令行配置提供程序被封装在 Microsoft.Extensions.Configuration.CommandLine 包中,通过CommandLineConfigurationProvider在运行时从命令行参数键值对中加载配置。

当我们通过 dotnet 命令启动一个 .NET Core 应用时,我们可以在命令后面追加一些参数,这些参数将在入口文件中被 args 变量接收到。命令行配置提供程序使用如下:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

using var host = Host.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration((context, config) =>
    {
        // 清除原有的配置提供程序
        config.Sources.Clear();
        config.AddCommandLine(args);
    })
    .Build();

var configuration = host.Services.GetService<IConfiguration>();

Console.WriteLine($"Settings:Provider: {configuration.GetValue<string>("Settings:Provider")}");
Console.WriteLine($"Settings:items[1]: {configuration.GetValue<string>("Settings:items:1")}");

host.Run();

之后通过命令行程序启动应用,并传入相应的参数:

dotnet ConfigurationSampleConsole.dll Settings:Provider=CommandLineProvider Settings:items:1=item1

image

命令行参数的设置有三种方式:

(1) 使用 = 号连接键值:

dotnet ConfigurationSampleConsole.dll Settings:Provider=CommandLineProvider Settings:items:0=item1 Settings:items:1=item2

(2) 使用 / 号表示键,值跟在键后面,键值以空格分隔

dotnet ConfigurationSampleConsole.dll /Settings:Provider CommandLineProvider /Settings:items:0 item1 /Settings:items:1 item2

(3) 使用 -- 符号表示键,值跟在键后面,键值以空格分隔

dotnet ConfigurationSampleConsole.dll --Settings:Provider CommandLineProvider --Settings:items:0 item1 --Settings:items:1 item2

如果值之中本来就有空格的,可以使用 "" 号包括。

dotnet ConfigurationSampleConsole.dll --Settings:Provider CommandLineProvider --Settings:items:0 item1 --Settings:items:1 "test item2"

AddCommandLine 扩展方法提供了重载,允许额外传入一个参数,该参数提供一个交换映射字典,针对命令行配置参数进行key映射。例如命令行传入键是 name01 ,映射后的的键为 project:name。这里有一些要注意的点:

  • 交换映射key必须以-或--开头。当使用-开头时,命令行参数书写时也要以-开头,当使用--开头时,命令行参数书写时可以以--或/开头。
  • 交换映射字典中的key不区分大小写,不能包含重复 key。如不能同时出现-n和-N,但可以同时出现 -n 和 --n 。
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

using var host = Host.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration((context, config) =>
    {
        // 清除原有的配置提供程序
        config.Sources.Clear();

        var switchMappings = new Dictionary<string, string>
        {
            ["--b1"] = "Settings:Provider",
            ["-b2"] = "Settings:items"
        };

        config.AddCommandLine(args, switchMappings);
    })
    .Build();

var configuration = host.Services.GetService<IConfiguration>();

Console.WriteLine($"Settings:Provider: {configuration.GetValue<string>("Settings:Provider")}");
Console.WriteLine($"Settings:items[1]: {configuration.GetValue<string>("Settings:items:1")}");

host.Run();

image

3.4 内存配置提供程序

内存配置提供程序就比较简单了,它直接被包含在 Microsoft.Extensions.Configuration,通过MemoryConfigurationProvider在运行时从内存中的集合中加载配置。使用方式如下:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

using var host = Host.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration((context, config) =>
    {
        // 清除原有的配置提供程序
        config.Sources.Clear();

        config.AddInMemoryCollection(new Dictionary<string, string> {
            { "Settings:Provider", "InMemoryProvider" },
            { "Settings:items:1", "MemoryItem" }
        });
    })
    .Build();

var configuration = host.Services.GetService<IConfiguration>();

Console.WriteLine($"Settings:Provider: {configuration.GetValue<string>("Settings:Provider")}");
Console.WriteLine($"Settings:items[1]: {configuration.GetValue<string>("Settings:items:1")}");

host.Run();![image]

image

3.5 配置加载顺序

上面介绍了一些常用的配置提供程序,这些配置提供程序都是通过扩展方法添加到 ConfigurationBuilder 对象中的,而从上面 ConfigurationBuilder 的源码可以看出,添加一个配置提供程序的时候其实应该是添加了一个对应的 IConfigurationSource 对象,而后在 ConfigurationBuilder 中被保存到集合中。

这就可以看出,配置系统是允许同时添加多种配置提供程序,支持多来源的配置信息同时存在的。那么当多个配置处理程序都被添加到配置系统之中,那我们从配置系统中通过配置键获取配置值的时候是怎么进行的呢,当多个配置提供程序存在相同的配置键时,我们获取到的配置值是哪个呢?

从 ConfigurationRoot 的源码中可以可以看到,当我们用索引器 API 读取配置值时,是调用了 GetConfiguration 方法

image

而 GetConfiguration 方法中的逻辑也很简单,只是遍历提供程序集合尝试从提供程序去获取值,需要关注的是遍历的顺序。

image

这里的逻辑是这样子的,倒叙进行遍历,后添加的配置处理程序先被遍历,一旦通过key从提供程序中获取到值就返回结果,不再继续遍历。所以添加配置提供程序的顺序决定相同配置键最终的值, 当多个配置处理程序存在相同键时,越后添加的配置提供程序优先级越高,从最后的一个提供程序获取到值之后就不再从其他处理程序获取。

3.6 默认配置来源

上面也有提到通过主机运行和管理应用,在通过主机运行的项目中,主机在启动的时候就已经默认添加了一些配置提供程序,所以我们创建了一个 ASP.NET Core 模板项目之后就可以获取到 appsettings.json 等配置文件中的配置信息。下面介绍一下默认添加的配置提供程序。

Host.CreateDefaultBuilder(String[]) 方法或者 WebApplication.CreateBuilder(args) 方法执行的时候,会按照以下顺序添加应用的配置提供程序:

(1) 内存配置提供程序
(2) Chained 配置提供程序(添加现有的主机配置)
(3) JSON 配置提供程序 (添加 appsettings.json 配置文件)
(4) JSON 配置提供程序 (添加 appsettings.{Environment}.json 配置文件)
(5) 机密管理器(仅Windows)
(6) 环境变量配置提供程序 (未限定前缀)
(7) 命令行配置提供程序

配置分主机配置和应用配置,主机启动时应用仍未启动,主机启动过程中的配置就是主机配置。上面第一个Chained 配置提供程序就是承接过来的主机配置。而主机配置是按照以下顺序加载的:

(1) 环境变量配置提供程序(以 DOTNET_ 为前缀的环境变量)
(2) 命令行配置提供程序 (命令行参数)
(3) 环境变量配置提供程序(以 ASPNETCORE_ 为前缀的环境变量,如果是Web主机的话)

所以最终的应用配置加载顺序应该是下面这样:

(1) 内存配置提供程序
(2) 环境变量配置提供程序(以 DOTNET_ 为前缀的环境变量)
(3) 命令行配置提供程序 (命令行参数)
(4) 环境变量配置提供程序(以 ASPNETCORE_ 为前缀的环境变量,如果是Web主机的话)
(5) JSON 配置提供程序 (添加 appsettings.json 配置文件)
(6) JSON 配置提供程序 (添加 appsettings.{Environment}.json 配置文件)
(7) 机密管理器(仅Windows)
(8) 环境变量配置提供程序 (未限定前缀)
(9) 命令行配置提供程序 (命令行参数)

按照越后面添加的提供程序优先的方式,最终应用配置会覆盖主机配置,并且最优先是最后添加的命令行配置提供程序,我们可以通过以下方式打印配置系统中所有的配置提供程序,进行验证:

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

var configurationRoot = (IConfigurationRoot)app.Configuration;
foreach (var provider in configurationRoot.Providers.AsEnumerable())
{
    Console.WriteLine(provider.ToString());
}

app.Run();

最终控制台打印出来的结果如下:

最终控制台打印出来的结果如下:image

虽然应用配置优先,会覆盖前面的主机配置,但是有一些变量会在初始化主机生成器的时候就提前进行锁定,并且之后不会受应用配置的影响:

这里提到环境名称,其实也就是软件运行的环境,最最基本的也会分为开发环境、生产环境两种。软件运行环境通过环境变量来设置,普通的.NET Core 应用环境变量key为NETCORE_ENVIRONMENT,Web应用环境变量key为ASPNETCORE_ENVIRONMENT,Web应用下如果两者同时存在,后者会覆盖前者。软件应用根据不同的环境会有不同的行为逻辑,例如上面讲到的 appsettings.{environment}.json 根据环境而不同的配置文件,例如之前的 入口文件 文章中讲到的 Startup 文件根据不同环境的分离配置方式,而我们在代码中有时也会根据环境处理不同的逻辑,这时候我们可以注入 IHostEnvironment 服务,通过它获取当前应用的运行环境,入口文件中无论是 WebApplicationBuilder 对象还是 WebApplication 对象都包含该类型的属性。

通过环境变量设置当前运行环境,其实环境变量的值只是一个字符串,我们可以设置成任意值,这是运行的,.NET Core 框架下 IHostEnvironment 也能够正常加载到相应的环境名称,但是.NET Core 默认只提供了对 Development、Production 和 Staging 三种环境的判别,以及相应的处理逻辑和扩展方法,如果是其他的自定义环境则需要开发人员自行进行相应的处理了。和 .NET Core 应用环境相关的知识点大家可以看一下官方文档: 在 ASP.NET Core 中使用多个环境 | Microsoft Learn

除了上面讲到的主机配置,其他还有一些主机配置,例如URLS,但这个是可以通过应用配置设置的,读取相应的配置值时也应用从应用配置读取。

URLS 配置Web应用启动后的访问地址,这个配置可以多个地方设置,其中命令行参数最优先,其他地方设置的应该被命令行参数覆盖。但是如果通过Kestrel 终结点方式设置了Web应用的访问地址,那Kestrel 终结点的配置将覆盖其他所有的访问地址的配置。

如在 appsettings.json 中添加以下配置:

"Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://localhost:9999"
      }
    }
  }

那么以下几种方式设置的 URLS 都会失效:

  • UseUrls
  • 命令行上的 --urls
  • 环境变量 ASPNETCORE__URLS

也就是说,就算我们用以下命令启动应用,应用最终的访问地址还是以Kestrel终结点配置的为准:

dotnet run --urls="https://localhost:7777"

Kestrel 配置与 URLS 配置不是一个参数,我们可以通过在命令行或者环境变量中设置 kestrel 中间点配置来覆盖 appsettings.json 中的,这又回到配置提供程序的优先级问题了。

set Kestrel__Endpoints__Https__Url=https://localhost:8888

dotnet run Kestrel__Endpoints__Https__Url=https://localhost:8888

在主机启动的逻辑中Kestrel具备更高的最终优先级,但是其实主机内部是先根据URLS创建了一个终结点,之后又替换为 Kestrel 配置的终结点的。通过应用启动时的控制台输出可以看出。

image

这种情况对于单机应用没有什么影响,但是对于使用自动服务发现的微服务架构而言就可能有问题了,可能导致注册服务注册中心的终结点是第一个,而后应用终结点又被改变,导致注册中心记录的服务终结点和实际的不一致。

这一篇的内容比较多,但是不大好拆分,整个知识点是一个整体,通过这一章的内容相信大家能够对 .NET Core 框架配置系统内部的工作原理有一个详细的了解。



参考文章:

ASP.NET Core 中的配置 | Microsoft Learn
配置 - .NET | Microsoft Learn
理解ASP.NET Core - 配置(Configuration)



ASP.NET Core 系列:
目录:ASP.NET Core 系列总结
上一篇:ASP.NET Core - 配置系统之配置添加
下一篇:ASP.NET Core - 配置系统之自定义配置提供程序

posted @ 2023-03-10 15:36  啊晚  阅读(610)  评论(0编辑  收藏  举报