【ASP.NET Core】自定义的配置源
本文的主题是简单说说如何实现 IConfigurationSource、IConfigurationProvider 接口来自定义一个配置信息的来源，后面老周给的示例是实现用 CSV 文件进行应用配置。
在切入主题之前，老周忽然酒兴大发，打算扯一些跟主题有关系的题外话。
关于 ASP.NET Core 的应用程序配置，以下是老周总结出来的无废话内容：
- 配置信息可以有多种来源。比如，用JSON文件来配置，在内存中直接构建配置，用XML文件来配置，用 .ini 文件来配置等。
- ASP.NET Core 或 .NET 应用程序会将这些信息来源合并到一起，主要负责人是 IConfigurationBuilder 君。
- 配置信息是字典格式的，即 Key=Value，如果key相同，不管它来自哪，后添加的会替换先添加的配置。
- 配置数据可以认为是树形的，它由key/value组成，但可以有小节。
- IConfiguration 接口表示配置信息中的通用模型，你可以像字典对象那样访问配置，如 config["key"]。这些配置信息都是字符串类型，不管是key还是value。
- IConfigurationRoot 接口比 IConfiguration 更具体一些。它表示整个应用程序配置树的根。它多了个 Providers 集合，你可以从集合里找出你想单独读取的配置源，比如，你只想要环境变量；它还有个 Reload 方法，用来重新加载配置信息。
- IConfigurationSource 接口表示配置信息的来源。
- IConfigurationProvider 接口根据其来源为应用程序提供 Key / Value 形式的配置信息。
- 上面两位好基友的关系：IConfigurationSource 负责创建 IConfigurationProvider。读取配置信息靠的是 IConfigurationProvider。
- Microsoft.Extensions.Configuration 并不是只用于 ASP.NET Core 项目，其他 .NET 项目也能用，不过要引用 Nuget 库。
- 这些家伙的日常运作是这样的：
-
- IConfigurationBuilder 管理生产车间（家庭小作坊），它有个 Source 集合，你可以根据需要放各种 IConfigurationSource。这就等于放各种原材料了。
- 放完材料后，builder 君会检查所有的 source，逐个调用它们的 Build 方法，产生各种 IConfigurationProvider。这样，初步加工完毕，接下来是进一步处理。
- 逐个调用所有 IConfigurationProvider 的 Load 方法，让它们从各自的 source 中加载配置信息。
- 把所有的配置信息合并起来统一放到 IConfigurationRoot 中，然后应用程序就可以用各种姿势来访问配置。
好了，下面看看这些接口的默认实现类。
IConfigurationBuilder ----> ConfigurationBuilder
IConfigurationSource ----> FileConfigurationSource（抽象）、StreamConfigurationSource（抽象）、CommandLineConfigurationSource ……
IConfigurationProvider ----> ConfigurationProvider（抽象）----> MemoryConfigurationProvider ……
IConfigurationRoot、IConfiguration ----> ConfigurationRoot
我没有全部列出来，列一部分，主要是大伙伴能明这些线路就行了。各种实现类，你看名字也能猜到干吗的，比如 CommandLineConfigurationSource，自然是提供命令行参数来做配置源的。
这里不得不提一个有意思的类—— ConfigurationManager，它相当于一个复合体，同时实现 IConfigurationBuilder、IConfigurationRoot 接口。这就相当于它既能用来添加 source，加载配置，又可以直接用来访问配置。所以使用该类，直接 Add 配置源就可以访问了，不需要调用 Build 方法。
ASP.NET Core 应用程序在初始化时默认在服务容器中注册的就是 ConfigurationManager 类，不过，在依赖注入时，你要用 IConfiguration 接口去提取。
---------------------------------------------------------------
好了，以上内容仅仅是知识准备，接下来咱们要动手干大事了。
有大伙伴可能会问：我们直接实现这些个接口吗？不，这显然工作量太大了，完全没必要。咱们要做的是根据实际需要选择抽象类，然后实现这些抽象类就好了。咱们分别来说说 Source 和 Provider。
对于配置的 source，因为它的主要作用是产生 Provider 实例，所以，如果你不需要其他的参数和属性，只想实现 Build 方法返回一个 Provider 实例，那么可以直接实现 IConfigurationSource 接口。另外，有两个抽象类我们是可以考虑的：
1、FileConfigurationSource：如果你要的配置源于文件，就果断实现这个抽象类，它已经包含如 Path（文件路径）、FileProvider 等通用属性。咱们直接重写 Build 方法就完事了，不用去管怎么处理文件路径的事。
在重写 Build 方法时，创建 Configuration Provider 之前最好调用一下 EnsureDefaults 方法。这个方法的作用是当用户没有提供 IFileProvider 时能获得一个默认值。其源代码如下：
public void EnsureDefaults(IConfigurationBuilder builder) { FileProvider ??= builder.GetFileProvider(); OnLoadException ??= builder.GetFileLoadExceptionHandler(); }
还一个方法是 ResolveFileProvider，它的作用是当找不到 IFileProvider 时，将根据 Path 属性指定的文件路径创建一个 PhysicalFileProvider 对象。在向 IConfigurationBuilder 添加 source 时可以调用这个方法。
2、StreamConfigurationSource：如果你要的配置源是流对象，不管是内存流还是文件流，或是网络流，可考虑实现此抽象类。这个类公开 Stream 属性，用来设置要读取的流对象。当然，Build 方法一定要重写，因为它是抽象方法，用来返回你自定义的 Provider。
------------------------------------------------------------------------------------------------------
接着看 IConfigurationProvider，它的实现类中有个通用抽象类—— ConfigurationProvider。这个类有个 Data 属性，类型是 IDictionary<string, string>，看到吧，是字典类型。不过这个属性只允许派生类访问。
比较重要的是 Load 方法，这是个虚方法，派生类中我们重写它，然后在方法里面从配置源读取数据，并把处理好的配置数据放进 Data 属性中。这就是加载配置的核心步骤。
为了便于我们自定义，ConfigurationProvider 类又派生出两个抽象类：
1、FileConfigurationProvider ：它封装了打开文件、读文件等细节，然后直给你一个抽象的 Load 方法，把已加载的流对象传递进去，然后你实现这个方法，在里面读取配置。意思就是：舞台都帮你搭好了（灯光、音响等都不用你管），请开始你的表演。
public abstract void Load(Stream stream);
2、StreamConfigurationProvider ：跟 FileConfigurationProvider 一个鸟样，只不过它针对的源是流对象。该类同样有个抽象方法 Load，用途和签名一样。在这个方法里面实现读取配置。
public abstract void Load(Stream stream);
分析完之后，你会发现个规律：FileConfigurationSource 和 FileConfigurationProvider 是一对的，StreamConfigurationSource 和 StreamConfigurationProvider 是一对。如果配置源于文件，选择实现第一对；若源是流对象就实现第二对。
这些类型的关系不算复杂，为了节约脑细胞，老周就不画它们的关系图，老周相信大伙伴们的理解能力的。
-----------------------------------------------------------------------------------------
现在开始本期节目的最后一环节——写代码。开场白中老周说过，这一次咱们的示例会实现从 CSV 文件中读配置信息。CSV 就是一种简单的数据文件，嗯，文本文件。它的结构是每一行就是一条数据记录，字段用逗号分隔（一般用逗号，也可以用其他符号，主要看你的代码怎么实现了）。这里老周不打算搞太复杂，所以假设字段只用逗号分隔。
规则是这样的：第一行表示配置信息的 Key 列表，第二行是 Key 列表对应的值。比如
appTitle, appID, root 贪食蛇, TS-333, /usr/bin
把上面的内容解析成配置信息就是：
appTitle = 贪食蛇 appID = TS-333 root = /usr/bin
【注】这些配置在读取时是不区分大小写的，即 appTitle 和 apptitle 相同。
不过，老周也考虑有多套配置的情况，假设以下配置用来设置HTML页面的皮肤样式的。
headerColor, tableLine, fontSize black, 2, 15 red, 1.5, 16
按照规则，第一行是 Key 表列，那么二、三行就是 Value。所以这个应用程序就可以用两套 UI 皮肤了。
headerColor = black tableLine = 2 fontSize = 15 ----------------------------- headerColor = red tableLine = 1.5 fontSize = 16
那么，要是把两套配置都加载了，那怎么表示呢。不怕，因为它可以分层（或者说分节点），每个节点之间用冒号隔开。我们假设第一套皮肤配置的索引为 0， 第二套皮肤配置的索引为 1。这样就可以区分它们了。
headerColor:0 = black tableLine:0 = 2 fontSize:0 = 15 -------------------------------- headerColor:1 = red tableLine:1 = 1.5 fontSize:1 = 16
要使用第二套皮肤的字体大小，就访问 config["fontSize:1"]。
现在开工，想一下，咱们这个配置是来自 csv 文件，所以要实现自定义，应当选 FileConfigurationSource 和 FileConfigurationProvider 这两个类来实现。
动手，先写 CSVConfigurationSource 类，很简单，直接实现 Build 方法就完事。
public sealed class CSVConfigurationSource : FileConfigurationSource { public override IConfigurationProvider Build(IConfigurationBuilder builder) { EnsureDefaults(builder); //调用一下这个 return new CSVConfigurationProvider(this); } }
EnsureDefaults 方法记得调用一下，防止代码调用方没提供 FileProvider。重点是直接返回 CSVConfigurationProvider 实例，它接收当前 CSVConfigurationSource 对象作为构造函数参数。
接下来写 CSVConfigurationProvider 类，这个主要是实现 Load 方法。
public sealed class CSVConfigurationProvider : FileConfigurationProvider { public CSVConfigurationProvider(CSVConfigurationSource source) : base(source) { } public override void Load(Stream stream) { using StreamReader reader = new(stream); try { // 先读第一行，确定一下字段名（Key） string? strLine = reader.ReadLine(); if (string.IsNullOrEmpty(strLine)) { throw new FormatException("文件是空的？"); } string[] keys = GetParts(strLine).ToArray(); // 字段数量 // 这个很重要，后面读取值的时候要看看数量是否匹配 int keyLen = keys.Length; // 循环取值 int index = 0; // 临时存放 Dictionary<string, string> tempData = new Dictionary<string, string>(); for(strLine = reader.ReadLine(); !string.IsNullOrEmpty(strLine); strLine = reader.ReadLine()) { // 分割 var valparts = GetParts(strLine).ToArray(); // 分割出来的值个数是否等于字段数 if(valparts.Length != keyLen) { throw new FormatException("值与字段的数量不一致"); } // key - value 按顺序来 // key:<index> = value for(int n = 0; n < keyLen; n++) { string key = keys[n]; // 加上索引 key = ConfigurationPath.Combine(key, index.ToString()); tempData[key] = valparts[n]; } index++; // 索引要++ } // 读完数据后还要整理一下 // 如果 index-1 为0，表示代表配置值的只有一行 // 这种情况下没必要加索引 if(index - 1 == 0) { foreach(string ik in tempData.Keys) { string value = tempData[ik]; // 去掉索引 string key = ConfigurationPath.GetParentPath(ik); // 正式存储 Data[key] = value; } } else { foreach(string key in tempData.Keys) { // 这种情况下直接copy Data[key] = tempData[key]; } } // 临时存放的字典不需要了，清一下 tempData.Clear(); } catch { throw; } } #region 私有成员 private IEnumerable<string> GetParts(string line) { // 拆分并去掉空格 var parts = from seg in line.Split(',') select seg.Trim(); // 提取 foreach(string x in parts) { if(x is null or { Length: 0 } ) { throw new FormatException("咦，怎么有个值是空的？"); } yield return x; //这样返回比较方便 } } #endregion }
GetParts 是私有方法，功能是把一行文本按照逗号分隔出一组值来。
Load 方法的实现线路：
1、先读第一行，确定配置的 Key 列表。
2、从第二行开始读，每读一行就增加一次索引。因为允许一组 Key 对应一组 Value。
3、如果 Value 组只有一行，就不要加索引了，直接 key1、key2、key3就行了；如果有多组 Value，就要用索引，变成 key1:0、key2:0、key3:0；key1:1、key2:1、key3:1；key1:2、key2:2、key3:2。
4、加载的配置都存放到 Data 属性中。
代码中老周用了个临时的 Dictionary。
Dictionary<string, string> tempData = new Dictionary<string, string>();
因为在一行一行地读时，你不能事先知道这文件里面有多少行。如果只有两行，那表明 Value 只有一组，它的索引是0。可实际上，只有一组值的话，索引是多余的，没必要。只有大于一组值的时候才需要。
因为读的时候我们不会去算出文件中有多少行，所以我就假设它有很多行，第二行的索引为 0，第三行为 1，第四行为 2……。不管值是一行还是多行，我都给它加上索引，存放到临时的字典中。
等到整个文件读完了，我再看 index 变量，如果它的值是 1 （每读一行++，如果是 1 ，说明只读了一行），说明只读了第二行，这时候值只有一组，再把索引删去；要是读到的值有N行，那就保留索引。
if(index - 1 == 0) { foreach(string ik in tempData.Keys) { string value = tempData[ik]; // 去掉索引 string key = ConfigurationPath.GetParentPath(ik); // 正式存储 Data[key] = value; } } else { // 保留索引 foreach(string key in tempData.Keys) { // 这种情况下直接copy Data[key] = tempData[key]; } }
ConfigurationPath 有一组静态方法，很好用的，用来合并、剪裁用“:”分隔的路径。我们要充分利用它，可以省很多事，不用自己去合并拆分字符串。这个类还定义了一个只读的字段 KeyDelimiter，它的值就是一个冒号。可见，在.NET 的Configuration API 中，配置树的路径分隔符是在代码中写死的，你只能这样用：root : section1 : key1 = abcdefg。
到了这儿是基本完成，不过不好用，我们得写一组扩展方法，就像运行库默认给我们公开的那样，调用个 AddJsonFile，AddCommandLine，AddEnvironmentVariables 那样，多方便。
public static class CSVConfigurationExtensions { public static IConfigurationBuilder AddCsvFile(this IConfigurationBuilder builder, IFileProvider? provider, string path, bool optional, bool reloadOnChange) { return builder.Add<CSVConfigurationSource>(s => { s.FileProvider = provider; s.Path = path; s.Optional = optional; s.ReloadOnChange = reloadOnChange; s.ResolveFileProvider(); //这一行可选 }); } public static IConfigurationBuilder AddCsvFile(this IConfigurationBuilder builder, string path) => builder.AddCsvFile(null, path, false, false); public static IConfigurationBuilder AddCsvFile(this IConfigurationBuilder builder, string path, bool optional) => builder.AddCsvFile(null, path, optional, false); public static IConfigurationBuilder AddCsvFile(this IConfigurationBuilder builder, string path, bool optional, bool reloadOnChange) => builder.AddCsvFile(null, path, optional, reloadOnChange); }
基本上就是模仿 AddJsonFile、AddXmlFile 写的。
接下来是实验阶段。在项目中加一个 csv 文件，可以新建个文本文件，然后改名为 test.csv。
把这个文件的“生成操作”改为“内容”，复制行为是“如果较新则复制”。这样在运行测试时就不用自己手动复制文件。
hashName,keyBits,version MD5,8,1.2.0 SHA1,12,2.0 SHA256,16,0.3.5
这个配置的 Key 有：hashName，keyBits，version。值有三组（二、三、四行）。
打开 Program.cs 文件，在初始化代码中添加 test.csv 文件。
var builder = WebApplication.CreateBuilder(args); // 添加配置 builder.Configuration.AddCsvFile("test.csv", optional: true, reloadOnChange: true); var app = builder.Build();
optional 表示这个文件是可选的，如果找不到就不加载配置了；reloadOnChange 表示监控这个文件，如果它被修改了，就重新加载配置。
在 app.MapGet 方法中，我们用一个调试专用的扩展方法，直接打印所有配置。
app.MapGet("/", () => { IConfigurationRoot rootconfg = (IConfigurationRoot)app.Configuration; return rootconfg.GetDebugView(); });
GetDebugView 扩展方法很好使，运行程序后就能看到所有配置了，包括咱们自定义的 CSV 文件中的配置。
如果我们要明确地读取这些配置，可以这样。
IConfigurationRoot rootconfg = (IConfigurationRoot)app.Configuration; // 第一组配置 string hash1 = rootconfg["hashName:0"]; string bits1 = rootconfg["keyBits:0"]; string version1 = rootconfg["version:0"]; // 第二组 string hash2 = rootconfg["hashName:1"]; string bits2 = rootconfg["keyBits:1"]; string version2 = rootconfg["version:1"]; // 拼接字符串并返回 return $"hashName: {hash1}, keyBits: {bits1}, version: {version1}\n" + $"hashName: {hash2}, keyBits: {bits2}, version: {version2}";
运行后得到的结果：
至此，咱们这个自定义的配置源总算是实现了。
好了，今天就水到这里了，改天老周和各位继续水文章。
