ASP.NET Core的配置(3): 将配置绑定为对象[上篇]

简介:

出于编程上的便利,我们通常不会直接利用ConfigurationBuilder创建的Configuration对象读取某个单一配置项的值,而是倾向于将一组相关的配置绑定为一个对象,我们将后者称为Options对象。我们在本章第一节通过简单的实例演示了如何利用Options模型实现了配置数据向Options对象的绑定,现在我们对Options模型背后的实现原理进行详细介绍。

目录
一、ConfigurationBinder
二、绑定简单对象
三、绑定复杂对象
四、绑定集合对象
五、绑定字典对象

一、ConfigurationBinder

配置在逻辑上体现为一个具有层次化的配置树,对于一个Options对象来说,如果我们将其数据成员视为其子节点,那么Options对象同样具有一个层次化属性结构,所以Options对象和配置在数据结构层面并没有本质的差异。如果Options类型的数据成员定义与配置的结构具有一一匹配关系,那么将后者绑定为一个对应类型的Options对象是一件很容易的事情,我们本节重点介绍的ConfigurationBinder就是利用这样的原理实现了结构化配置向数据对象的自动绑定。

ConfigurationBinder是一个定义在程序集“Microsoft.Extensions.Configuration.Binder” 中的静态类型,程序集的名称同样也是所在NuGet包的名称,它提供的针对配置的绑定功能体现在它所定义的Bind和一系列Get方法中。如下面的代码片段所示,这些都是针对IConfiguration接口的扩展方法。

   1: public static class ConfigurationBinder
   2: {
   3:     public static void Bind(this IConfiguration configuration, object instance);
   4:  
   5:     public static object Get(this IConfiguration configuration, Type type);
   6:     public static object Get(this IConfiguration configuration, Type type, string key);
   7:     public static T Get<T>(this IConfiguration configuration);
   8:     public static T Get<T>(this IConfiguration configuration, T defaultValue);
   9:     public static T Get<T>(this IConfiguration configuration, string key);
  10:     public static T Get<T>(this IConfiguration configuration, string key, T defaultValue);
  11: }

我们可以调用Bind方法将一个Configuration对象绑定为一个预先创建的对象,而Get方法则直接根据指定类型(通过参数type或者方法的泛型参数类型决定)的对应数据对象并将Configuration对象承载的配置数据绑定在该对象上。如果调用具有参数key的Get方法,绑定的配置来源于由这个Key代表的子配置节。

ConfigurationBinder绑定的目标类型可以是一个简单的基元类型,也可以是一个复杂的自定义数据类型,还可以是一个集合或者字典类型。通过上面的介绍我们知道配置的物理结构体现为一个二维数据字典,那么对于绑定生成的不同类型的数据对象,这些原始的数据如何通过一组字符串类型的键值对来表现呢?

二、绑定简单数据类型

由于一个原子配置项总是体现为一个KeyValuePair <string,string >对象,所以配置绑定的原始数据类型是字符串。这里所谓的简单数据类型和复杂数据类型只有一个界定标准,那就是是否支持源自字符串类型的数据转换。简单类型对象可以直接通过一个字符串转换而来,复杂类型对象则不能。

如果绑定的目标类型为简单类型,在进行配置绑定的时候自需要将配置项的值(体现为ConfigurationSection的Value属性)转换成对应的数据类型就可以了。由于所有基元类型(比如Int32、Double等)都是简单类型,所以我们可以直接按照如下的方式绑定它们的值。

   1: IConfiguration configuration = new ConfigurationBuilder()
   2:     .Add(new MemoryConfigurationProvider(new Dictionary<string, string>
   3:     {
   4:         ["foo"] = "abc",
   5:         ["bar"] = "123",
   6:         ["baz"] = "3.14"
   7:     })).Build();
   8:  
   9: Debug.Assert(configuration.GetSection("foo").Get<string>() == "abc");
  10: Debug.Assert(configuration.Get<int>("bar") == 123);
  11: Debug.Assert(configuration.Get<double>("bar") == 3.14);

我们自定义的数据类型在默认情况下不属于简单类型,但是我们可以为它指定一个TypeConverter,如果后者支持源自字符串的类型转换,那么该类型自然也就成为了一个简单类型。如下面的代码片段所示,我们定义了一个表示二维坐标点的Point类型,并通过标注TypeConverterAttribute特性应用了一个之处源自字符串类型转换的TypeConverter(PointTypeConverter)。在进行配置绑定的时候,如果原始配置项具有匹配的格式,则可以直接将其绑定为一个Point对象。

   1: [TypeConverter(typeof(PointTypeConverter))]
   2: public class Point
   3: {
   4:     public double X { get; set; }
   5:     public double Y { get; set; }
   6: }
   7:  
   8: public class PointTypeConverter : TypeConverter
   9: {
  10:     public override object ConvertFrom(ITypeDescriptorContext context, CultureInfo culture, object value)
  11:     {
  12:         string[] split = value.ToString().Split(',');
  13:         return new Point
  14:         {
  15:             X = double.Parse(split[0].TrimStart('(')),
  16:             Y = double.Parse(split[1].TrimStart(')'))
  17:         };
  18:     }
  19: }
  20:  
  21: IConfiguration configuration = new ConfigurationBuilder().Add(new MemoryConfigurationProvider(new Dictionary<string, string>
  22:     {
  23:         ["point"] = "(1.2,3.4)"
  24:     })).Build();
  25: Debug.Assert(configuration.Get<Point>("point").X == 1.2);
  26: Debug.Assert(configuration.Get<Point>("point").Y == 3.4);


三、绑定复杂数据类型

如果通过一颗树来表示一个复杂对象,那么真正的数据是通过叶子节点来承载的,并且叶子节点对应的数据类型均为简单类型。如果通过一个二维数据字典来提供一个复杂对象所有的原始数据,那么这个字典中只需要包含叶子节点对应的值即可。至于如何通过一个字典对象体现复杂对象的结构,我们只需要将叶子节点所在的路径作为字典元素的Key就可以了。

   1: public class Profile
   2: {
   3:     public Gender         Gender { get; set; }
   4:     public int            Age { get; set; }
   5:     public ContactInfo    ContactInfo { get; set; }
   6: }
   7:  
   8: public class ContactInfo
   9: {
  10:     public string Email { get; set; }
  11:     public string PhoneNo { get; set; }
  12: }
  13:  
  14: public enum Gender
  15: {
  16:     Male,
  17:     Female
  18: }

5如上面的代码片段所示,我们定义了一个表示个人基本信息的Profile类,定义其中的三个属性(Gender、Age和ContactInfo)分别表示性别、年龄和联系方式。表示联系信息的ContactInfo对象具有两个属性(Email和PhoneNo)分别表示电子邮箱地址和电话号码。一个完整的Profile对象可以通过如右图所示的树来体现。

xxx如果需要通过配置的形式来表示一个完整的Profile对象,我们只需要将四个叶子节点(性别、年龄、电子邮箱地址和电话号码)对应的数据定义在配置之中即可。对于承载配置数据的数据字典中,我们需要按照如左边表格所示的方式将这四个叶子节点的路径作为字典元素的Key。

我们通过一个简单示例来演示针对复杂对象的配置绑定。我们创建一个ASP .NET Core控制台应用中,并在project.json文件中添加针对NuGet包“Microsoft.Extensions.Configuration.Binder”的依赖。我们在作为程序入口的Main方法中定义了如下所示的程序。

   1: public class Program
   2: {
   3:     public static void Main(string[] args)
   4:     {
   5:         IConfiguration configuration = new ConfigurationBuilder().Add(new MemoryConfigurationProvider(new Dictionary<string, string>
   6:             {
   7:                 ["Profile:Gender"]             = "Male",
   8:                 ["Profile:Age"]                = "18",
   9:                 ["Profile:ContactInfo:Email"]  = "foobar@outlook.com",
  10:                 ["Profile:ContactInfo:PhoneNo"]= "123456789",
  11:             })).Build();
  12:  
  13:         Profile profile = configuration.Get<Profile>("Profile");
  14:         Console.WriteLine("{0,-10}:{1}", "Gender", profile.Gender);
  15:         Console.WriteLine("{0,-10}:{1}", "Age", profile.Age);
  16:         Console.WriteLine("{0,-10}:{1}", "Email", profile.ContactInfo.Email);
  17:         Console.WriteLine("{0,-10}:{1}", "PhoneNo", profile.ContactInfo.PhoneNo);
  18:     }
  19: }

如上面的代码片段所示,我们创建了一个ConfigurationBuilder对象并为之添加了一个MemoryConfigurationProvider,后者按照如表2所示的结构提供了原始的配置数据。我们利用这个ConfigurationBuilder对象创建的Configuration对象并调用这个ConfigurationSection的Get方法将Key为“Profile”的配置节绑定为一个Profile对象。为了验证配置绑定是否成功,我们最终将这个绑定的Profile对象的相关信息打印出来。该程序执行之后会在控制台上产生如下所示的输出结果。

   1: Gender    :Male
   2: Age       :18
   3: Email     :foobar@outlook.com
   4: PhoneNo   :123456789


四、绑定集合对象

配置绑定从本质上讲就是承载相同信息的数据在不同结构之间的转换,说得更加具体一点就是数据从基于数据字典的物理结构转换成基于树的逻辑结构。要理解针对集合的配置绑定,需要首先了解一个集合对象在逻辑上体现怎样一棵树。对于一个集合对象来说,组成它的元素自然视为集合的子节点,所以一个包含三个Profile对象的集合可以由左图所示的树来体现。

6

但是如8所示的这棵树并不是一个合法的配置树。对于这棵树来说,表示集合元素的配置节都采用“Profile”作为Key,这导致了所有叶子节点的路径并不是唯一的。由于路径不唯一,我们自然不能将它作为一个字典对象的Key,那么构成这个集合的原子数据将无法通过一个数据字典来承载。为了解决这个问题,我们将集合元素的索引(0、1、2、 …)对应的配置节的Key,所以右图所示的才是真正配置树的结构。

7

既然我们能够正确将集合对象通过一个合法的配置树体现出来,那么我们就可以直接利用一个字典对象来提供构成这个集合对象的所有原子数据。数据字典中的每一个元素对应着配置树中的某个叶子结点,后者的路径直接作为字典元素的Key, 下面的表格清晰地体现了这个数据字典的结构。

image

我们依然通过一个简单的实例来演示针对集合的配置绑定。如下面的代码片段所示,我们创建了一个ConfigurationBuilder对象并为之添加了一个MemoryConfigurationProvider,后者按照如表3所示的结构提供了原始的配置数据。我们利用这个ConfigurationBuilder对象创建的Configuration对象并调用这个ConfigurationSection的Get方法将Key为“Profiles”的配置节绑定为一个List<Profile>对象。

   1: public class Program
   2: {
   3:     public static void Main(string[] args)
   4:     {
   5:         IConfiguration configuration = new ConfigurationBuilder().Add(new MemoryConfigurationProvider(new Dictionary<string, string>
   6:             {
   7:                 ["Profiles:0:Gender"]       = "Male",
   8:                 ["Profiles:0:Age"]      = "18",
   9:                 ["Profiles:0:ContactInfo:Email"]   = "foo@gmail.com",
  10:                 ["Profiles:0:ContactInfo:PhoneNo"]     = "123",
  11:  
  12:                 ["Profiles:1:Gender"]       = "Male",
  13:                 ["Profiles:1:Age"]      = "25",
  14:                 ["Profiles:1:ContactInfo:Email"]       = "bar@gmail.com",
  15:                 ["Profiles:1:ContactInfo:PhoneNo"]     = "456",
  16:  
  17:                 ["Profiles:2:Gender"]       = "Female",
  18:                 ["Profiles:2:Age"]      = "40",
  19:                 ["Profiles:2:ContactInfo:Email"]       = "baz@gmail.com",
  20:                 ["Profiles:2:ContactInfo:PhoneNo"]     = "789",
  21:             })).Build();
  22:  
  23:         IEnumerable<Profile> profiles = configuration.Get<List<Profile>>("Profiles");
  24:         foreach (Profile profile in profiles)
  25:         {
  26:  
  27:             Console.WriteLine("{0,-10}:{1}", "Gender", profile.Gender);
  28:             Console.WriteLine("{0,-10}:{1}", "Age", profile.Age);
  29:             Console.WriteLine("{0,-10}:{1}", "Email", profile.ContactInfo.Email);
  30:             Console.WriteLine("{0,-10}:{1}\n", "PhoneNo", profile.ContactInfo.PhoneNo);
  31:         }
  32:     }
  33: }

为了验证配置绑定是否成功,我们最终将这个绑定的List<Profile>对象的每个元素的相关信息打印出来,该程序执行之后会在控制台上产生如下所示的输出结果。

   1: Gender    :Male
   2: Age       :18
   3: Email     :foo@gmail.com
   4: PhoneNo   :123
   5:  
   6: Gender    :Male
   7: Age       :25
   8: Email     :bar@gmail.com
   9: PhoneNo   :456
  10:  
  11: Gender    :Female
  12: Age       :40
  13: Email     :baz@gmail.com
  14: PhoneNo   :789


五、绑定字典

8image字典可以视为元素类型为键值对的集合,两者在配置树上的表示非常相似,它们之间的唯一不同之处在于前者采用索引作为集合元素所在配置节的Key,后者直接将键值对的Key直接作为配置节的Key。举个简单的例子,我们通过一个Dictionary<string, Profile >对象来表示多个用户的个人信息,并且将用户名作为这个字典的Key,那么这个字典对象的配置树将具有如右图所示的结构(“Foo”、“Bar”和“Baz”表示用户名的Key)。

表示集合与字典的配置树在结构上基本类似,所以反映在基于数据字典的物理结构上也大同小异。对于右图表示的Dictionary<string, Profile>对象,构造该对象的所有原子配置数据可以通过包含如下元素的数据字典来提供。

我们依然通过一个简单的实例来演示针对字典的配置绑定。如下面的代码片段所示,我们创建了一个ConfigurationBuilder对象并为之添加了一个MemoryConfigurationProvider,后者按照如左边表格所示的结构提供了原始的配置数据。我们利用这个ConfigurationBuilder对象创建的Configuration对象并调用这个ConfigurationSection的Get方法将Key为“Profiles”的配置节绑定为一个Dictionary<string, Profile>对象。

   1: public class Program
   2: {
   3:     public static void Main(string[] args)
   4:     {
   5:         IConfiguration configuration = new ConfigurationBuilder().Add(new MemoryConfigurationProvider(new Dictionary<string, string>
   6:             {
   7:                 ["Profile:Foo:Gender"]               = "Male",
   8:                 ["Profile:Foo:Age"]                  = "18",
   9:                 ["Profile:Foo:ContactInfo:Email"]    = "foo@gmail.com",
  10:                 ["Profile:Foo:ContactInfo:PhoneNo"]  = "123",
  11:  
  12:                 ["Profile:Bar:Gender"]               = "Male",
  13:                 ["Profile:Bar:Age"]                  = "25",
  14:                 ["Profile:Bar:ContactInfo:Email"]    = "bar@gmail.com",
  15:                 ["Profile:Bar:ContactInfo:PhoneNo"]  = "456",
  16:                     
  17:                 ["Profile:Baz:Gender"]               = "Female",
  18:                 ["Profile:Baz:Age"]                  = "40",
  19:                 ["Profile:Baz:ContactInfo:Email"]    = "baz@gmail.com",
  20:                 ["Profile:Baz:ContactInfo:PhoneNo"]  = "789",
  21:             })).Build();
  22:  
  23:         Dictionary<string, Profile> profiles = configuration.Get<Dictionary<string, Profile>>("Profile");
  24:         foreach (var item in profiles)
  25:         {
  26:  
  27:             Console.WriteLine("{0,-10}:{1}", "Name", item.Key );
  28:             Console.WriteLine("{0,-10}:{1}", "Gender", item.Value.Gender);
  29:             Console.WriteLine("{0,-10}:{1}", "Age", item.Value.Age);
  30:             Console.WriteLine("{0,-10}:{1}", "Email", item.Value.ContactInfo.Email);
  31:             Console.WriteLine("{0,-10}:{1}\n", "PhoneNo", item.Value.ContactInfo.PhoneNo);
  32:         }
  33:     }
  34: }

为了验证配置绑定是否成功,我们最终将这个绑定的Dictionary<string, Profile>对象的每个元素的相关信息打印出来,该程序执行之后会在控制台上产生如下所示的输出结果。

   1: Name      :Foo
   2: Gender    :Male
   3: Age       :18
   4: Email     :foo@gmail.com
   5: PhoneNo   :123
   6:  
   7: Name      :Bar
   8: Gender    :Male
   9: Age       :25
  10: Email     :bar@gmail.com
  11: PhoneNo   :456
  12:  
  13: Name      :Baz
  14: Gender    :Female
  15: Age       :40
  16: Email     :baz@gmail.com
  17: PhoneNo   :789

 

ASP.NET Core的配置(1):读取配置信息
ASP.NET Core的配置(2):配置模型详解
ASP.NET Core的配置(3): 将配置绑定为对象[上篇]
ASP.NET Core的配置(3): 将配置绑定为对象[下篇]
ASP.NET Core的配置(4):多样性的配置源[上篇]
ASP.NET Core的配置(4):多样性的配置源[中篇]
ASP.NET Core的配置(4):多样性的配置源[下篇]
ASP.NET Core的配置(5):配置的同步[上篇]
ASP.NET Core的配置(5):配置的同步[下篇]


作者:蒋金楠
微信公众账号:大内老A
微博: www.weibo.com/artech
如果你想及时得到个人撰写文章以及著作的消息推送,或者想看看个人推荐的技术资料,可以扫描左边二维码(或者长按识别二维码)关注个人公众号(原来公众帐号 蒋金楠的自媒体将会停用)。
本文版权归作者和博客园共有,欢迎转载,但未经作者同意必须保留此段声明,且在文章页面明显位置给出原文连接,否则保留追究法律责任的权利。
相关文章
|
2月前
|
存储 开发框架 JSON
ASP.NET Core OData 9 正式发布
【10月更文挑战第8天】Microsoft 在 2024 年 8 月 30 日宣布推出 ASP.NET Core OData 9,此版本与 .NET 8 的 OData 库保持一致,改进了数据编码以符合 OData 规范,并放弃了对旧版 .NET Framework 的支持,仅支持 .NET 8 及更高版本。新版本引入了更快的 JSON 编写器 `System.Text.UTF8JsonWriter`,优化了内存使用和序列化速度。
|
3月前
|
开发框架 监控 前端开发
在 ASP.NET Core Web API 中使用操作筛选器统一处理通用操作
【9月更文挑战第27天】操作筛选器是ASP.NET Core MVC和Web API中的一种过滤器,可在操作方法执行前后运行代码,适用于日志记录、性能监控和验证等场景。通过实现`IActionFilter`接口的`OnActionExecuting`和`OnActionExecuted`方法,可以统一处理日志、验证及异常。创建并注册自定义筛选器类,能提升代码的可维护性和复用性。
|
3月前
|
开发框架 .NET 中间件
ASP.NET Core Web 开发浅谈
本文介绍ASP.NET Core,一个轻量级、开源的跨平台框架,专为构建高性能Web应用设计。通过简单步骤,你将学会创建首个Web应用。文章还深入探讨了路由配置、依赖注入及安全性配置等常见问题,并提供了实用示例代码以助于理解与避免错误,帮助开发者更好地掌握ASP.NET Core的核心概念。
104 3
|
2月前
|
开发框架 JavaScript 前端开发
一个适用于 ASP.NET Core 的轻量级插件框架
一个适用于 ASP.NET Core 的轻量级插件框架
|
3月前
|
开发框架 NoSQL .NET
利用分布式锁在ASP.NET Core中实现防抖
【9月更文挑战第5天】在 ASP.NET Core 中,可通过分布式锁实现防抖功能,仅处理连续相同请求中的首个请求,其余请求返回 204 No Content,直至锁释放。具体步骤包括:安装分布式锁库如 `StackExchange.Redis`;创建分布式锁服务接口及其实现;构建防抖中间件;并在 `Startup.cs` 中注册相关服务和中间件。这一机制有效避免了短时间内重复操作的问题。
|
4月前
|
开发框架 监控 .NET
开发者的革新利器:ASP.NET Core实战指南,构建未来Web应用的高效之道
【8月更文挑战第28天】本文探讨了如何利用ASP.NET Core构建高效、可扩展的Web应用。ASP.NET Core是一个开源、跨平台的框架,具有依赖注入、配置管理等特性。文章详细介绍了项目结构规划、依赖注入配置、中间件使用及性能优化方法,并讨论了安全性、可扩展性以及容器化的重要性。通过这些技术要点,开发者能够快速构建出符合现代Web应用需求的应用程序。
61 0
|
4月前
|
开发框架 监控 .NET
【Azure 应用程序见解】在Docker中运行的ASP.NET Core应用如何开启Application Insights的Profiler Trace呢?
【Azure 应用程序见解】在Docker中运行的ASP.NET Core应用如何开启Application Insights的Profiler Trace呢?
|
4月前
|
Linux C# C++
【Azure App Service For Container】创建ASP.NET Core Blazor项目并打包为Linux镜像发布到Azure应用服务
【Azure App Service For Container】创建ASP.NET Core Blazor项目并打包为Linux镜像发布到Azure应用服务
|
4月前
|
开发框架 .NET API
如何在 ASP.NET Core Web Api 项目中应用 NLog 写日志?
如何在 ASP.NET Core Web Api 项目中应用 NLog 写日志?
196 0
|
4月前
|
开发框架 中间件 .NET
分享 ASP.NET Core Web Api 中间件获取 Request Body 两个方法
分享 ASP.NET Core Web Api 中间件获取 Request Body 两个方法
139 0

相关实验场景

更多