.NET Core为我们提供了一套用于配置的API,它为程序提供了运行时从文件、命令行参数、环境变量等读取配置的方法。配置都是键值对的形式,并且支持嵌套,.NET Core还内建了从配置反序列化为POCO对象的支持。
目前支持以下配置Provider:
- 文件(INI,JSON,XML)
- 命令行参数
- 环境变量
- 内存中的.NET对象
- User Secrets
- Azure Key Vault
如果现有Provider不能满足你的使用场景,还允许自定义Provider,比如从数据库中读取。
配置相关的包
包管理器中搜索“Microsoft.Extensions.Configuration",所有与配置相关的包都会列举出来配置相关的包
从包的名称基本就可以看出它的用途,比如Microsoft.Extensions.Configuration.Json
是Json配置的Provider,Microsoft.Extensions.Configuration.CommandLine
是命令行参数配置的Provider,还有.NET Core程序中使用User Secrets存储敏感数据这篇文章中使用的Microsoft.Extensions.Configuration.UserSecrets
。
文件配置(以Json为例)
Json配置,需要安装Microsoft.Extensions.Configuration.Json包。
命令行下安装执行以下命令
dotnet add package Microsoft.Extensions.Configuration.Json -v 1.1.2
调用AddJsonFile把Json配置的Provider添加到ConfigurationBuilder中。
class Program { public static IConfigurationRoot Configuration { get; set; } static void Main(string[] args) { var builder = new ConfigurationBuilder() .SetBasePath(Directory.GetCurrentDirectory()) .AddJsonFile("appsettings.json"); Configuration = builder.Build(); } }
如果使用Xml或Ini,只需安装相应的包,然后调用相应的扩展方法AddXmlFile("appsettings.xml)
或AddIniFile("appsettings.ini")
。
SetBasePath是指定从哪个目录开始查找appsettings.json。如果appsettings.json在configs目录中,那么调用AddJsonFile应该指定的路径为"configs/appsettings.json"。
下面是演示用的Json配置,后面会讲解所有读取它的方法
{ "AppId": "12345", "Logging": { "IncludeScopes": false, "LogLevel": { "Default": "Debug", "System": "Information", "Microsoft": "Information" } }, "GrantTypes": [ { "Name": "authorization_code" }, { "Name": "password" }, { "Name": "client_credentials" } ] }
读取JSON配置
使用Key读取
Configuration["AppId"]; // 结果 12345 Configuration["Logging:IncludeScopes"]; // 结果 false Configuration["Logging:LogLevel:Default"]; // 结果 Debug Configuration["GrantTypes:0:Name"]; // 结果 authorization_code
读取嵌套的配置,使用冒号隔开;读取数组形式的配置,使用数组的下标索引,0表示第一个。
如在其他地方用到Configuration的时候,可以通过构造函数注入IConfiguration。
首先配置IConfiguration的依赖
services.AddSingleton(Configuration);
然后在通过构造函数注入
private readonly IConfiguration _configuration; public GetConfig(IConfiguration configuration) { _configuration = configuration; }
使用GetValue
这是一个扩展方法,使用它需要安装Microsoft.Extensions.Configuration.Binder
包。
Configuration.GetValue("AppId", 12345); // 结果 12345 Configuration.GetValue("Logging:IncludeScopes", false); // 结果 false Configuration.GetValue("Logging:LogLevel:Default", "Debug"); // 结果 Debug Configuration.GetValue("GrantTypes:0:Name", "authorize_code"); // 结果 authorization_code
GetValue方法的泛型形式有两个重载,一个是GetValue("key"),另一个可以指定默认值,GetValue("key",defaultValue)。如果key的配置不存在,第一种的结果为default(T),第二种的结果则为指定的默认值。
使用Options
这种方式需要安装Microsoft.Extensions.Options.ConfigurationExtensions包。
调用AddOptions()
添加使用Options需要的服务。
services.AddOptions();
定义与配置对应的POCO类
public class MyOptions { public int AppId { get; set; } public LoggingOptions Logging { get; set; } public List<GrantType> GrantTypes { get; set; } public class GrantType { public string Name { get; set; } } } public class LoggingOptions { public bool IncludeScopes { get; set; } public LogLevelOptions LogLevel { get; set; } } public class LogLevelOptions { public string Default { get; set; } public string System { get; set; } public string Microsoft { get; set; } }
绑定整个配置到POCO对象上
services.Configure(Configuration);
也可以绑定特定节点的配置
services.Configure(Configuration.GetSection("Logging"));
或
services.Configure(Configuration.GetSection("Logging:LogLevel"));
在需要用到配置的地方,通过构造函数注入,或者直接使用ServiceProvider获取。
private readonly MyOptions _myOptions; public GetConfig(IOptions<MyOptions> myOptionsAccessor) { _myOptions = myOptionsAccessor.Value; }
或
var myOptionsAccessor = serviceProvider.GetService<IOptions<MyOptions>>(); var myOptions = myOptionsAccessor.Value;
使用Get<T>
Get是.NET Core 1.1才引入的。
var myOptions = Configuration.Get();
或
var loggingOptions = Configuration.GetSection("Logging").Get();
使用Bind
和Get<T>类似,建议使用Get<T>。
var myOptions = new MyOptions(); Configuration.Bind(myOptions);
或
var loggingOptions = new LoggingOptions(); Configuration.GetSection("Logging").Bind(loggingOptions);
文件变化自动重新加载配置
IOptionsSnapshot
支持配置文件变化自动重新加载配置。使用IOptionsSnapshot也很简单,AddJsonFile有个重载,指定reloadOnChange:true即可。
var builder = new ConfigurationBuilder() .SetBasePath(Directory.GetCurrentDirectory()) .AddJsonFile("configs/appsettings.json", optional: false, reloadOnChange: true);
内存中配置
内存中配置调用AddInMemoryCollection()
,其余和Json配置一样。
var dict = new Dictionary<string, string> { {"AppId","12345"}, {"Logging:IncludeScopes","false"}, {"Logging:LogLevel:Default","Debug"}, {"Logging:LogLevel:System","Information"}, {"Logging:LogLevel:Microsoft","Information"}, {"GrantTypes:0:Name","authorization_code"}, {"GrantTypes:1:Name","password"}, {"GrantTypes:2:Name","client_credentials"} }; var builder = new ConfigurationBuilder() .AddInMemoryCollection(dict);
或
var builder = new ConfigurationBuilder() .AddInMemoryCollection(); Configuration["AppId"] = "12345";
命令行参数配置
命令行参数配置需要安装Microsoft.Extensions.Configuration.CommandLine
包。
调用AddCommandLine()
扩展方法将命令行配置Provider添加到ConfigurationBuilder中。
var builder = new ConfigurationBuilder() .AddCommandLine(args);
传递参数有两种形式
dotnet run /AppId=12345
或
dotnet run --AppId 12345
如果为--AppId提供一个缩写的参数-a,那么执行dotnet run -a 12345会报在switch mappings中没有-a定义的错误。
幸好AddCommandLine还有一个重载,可以传一个switch mapping。
var builder = new ConfigurationBuilder() .AddCommandLine(args, new Dictionary<string, string> { {"-a","AppId"} });
这样再运行下面的命令就不会报错了。
dotnet run -a 12345
环境变量配置
环境变量配置需要安装Microsoft.Extensions.Configuration.EnvironmentVariables
包。
调用AddEnvironmentVariables()
扩展方法将环境变量配置Provider添加到ConfigurationBuilder中。
var builder = new ConfigurationBuilder() .AddEnvironmentVariables();
获取所有的环境变量
Environment.GetEnvironmentVariables();
根据名称获取环境变量
Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT");
自定义配置Provider
自定义配置Provider需要继承IConfigurationSource实现自己的配置源,以及继承ConfigurationProvider,重写Load方法。
关于自定义配置Provider,我写了两个开源包,Cxlt.Extensions.Configuration.EF
和Cxlt.Extensions.Configuration.Yaml
,通过这两个项目,我会详细讲解如何实现自己的配置Provider。文章《实现自己的.NET Core配置Provider之EF》和《实现自己的.NET Core配置Provider之Yaml》过几天也会发布。
配置Provider顺序
.NET Core的配置API允许同时使用多个配置Provider。
var builder = new ConfigurationBuilder() .SetBasePath(Directory.GetCurrentDirectory()) .AddJsonFile("configs/appsettings.json") .AddXmlFile("configs/appsettings.xml") .AddCommandLine(args) .AddEnvironmentVariables();
如果两个Provider都有相同的配置,那么添加Provider的顺序就非常重要了,因为后加入的会覆盖前面的。
另外建议环境变量的配置Provider放到最后。
最后
.NET Core的配置是很基础的内容,学起来自然不难,基本上动手实践一遍就能掌握。越是简单的东西,在日后的开发中可能帮你节约很多时间。
全部评论:1条