十五、配置管理

可动态配置功能是一个可持续拓展的系统应用必备技能。

什么是配置

简单来说，配置就是将系统应用可动态调配的选项放在统一地方管理。

如何配置

在 asp.net core 应用程序中，通常配置都是存放在 .json 文件中，在Hoa Framework 中，建议存放在 Hoa.Web.Host.appsetting.json 中，当然也是 asp.net core 建议方式。

在 .json 文件配置中的所有 键 必须采用双引号包裹。如：

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

读取配置的方式

直接通过 IConfiguration 读取
通过选项方式载入配置文件，实现热更新（推荐）
框架内置快捷读取

直接读取

直接读取 appsetting.json 配置信息主要是通过 IConfiguration 实例对象来读取，可通过构造函数注入：

假设 appsetting.json 中有一个 Person 配置节点：

{
  "Person": {
    "Name": "MonkSoul",
    "Age": 27,
    "Gender": "男"
  }
}

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.Extensions.Configuration;

namespace Hoa.Application.Test
{
    [HoaServiceController]
    public class TestAppService : ITestAppService, IAppServiceDependency
    {
        private readonly IConfiguration _configuration;
        public TestAppService(IConfiguration configuration)
        {
             _configuration = configuration;
        }
        
        public void ConsolePerson()
        {
            var name = _configuration["Person:Name"];
            var age = _configuration["Age"];
            var gender = _configuration["Person:Gender"];
        }
    }
}

读取具体的键值只需要通过 : 语法即可，如：{键名称}:{下一级键名称}:{下下一级键名称}...

更多直接读取配置信息方式可查看官方文档。

选项模式

选项模式是 asp.net core 推荐的动态读取配置的方式，这种方式将配置文件数据用一个强类型来托管，能够实现默认值设置，动态热加载等等功能。

针对上述的 Person 配置，我们需要创建一个一一对应的强类型 PersonOptions ：

public class PersonOptions
{
    public string Name { get; set;}
    public int Age { get; set;}
    public string Gender { get; set;}
}

接下来，我们只需要 Hoa.Web.Core.ServiceExtensions.HoaConfigurationInitiateExtension.cs配置即可，如：

var personOptions = Configuration.GetSection(nameof(Person));
services.Configure<PersonOptions>(personOptions, options => { });

这样我们便可以在构造函数中注入使用了

using Hoa.AppConfigure;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;

namespace Hoa.Web.Host.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class HoaController : ControllerBase
    {
        private readonly PersonOptions personOptions;
        public HoaController(IOptionsMonitor<PersonOptions> optionsMonitor)
        {
            personOptions = optionsMonitor.CurrentValue;
            
            // personOptions.Name
            // personOptions.Age
        }
    }
}

关于选项模式可查看官方文档。

内置便捷选项读取

为了快速开发，Hoa Framework 内置了一些预设的选项读取属性，如：

AppGlobal.AppConfigOptions ：获取全局配置信息，对应 appsetting.json 中的 AppConfingOptions 节点。
AppGlobal.CorsConfigOptions ：获取跨域配置信息，对应 appsetting.json 中的 CorsConfigOptions 节点。
AppGlobal.SwaggerOptions ：获取Swagger配置信息，对应 appsetting.json 中的 HoaSwaggerOptions 节点。
AppGlobal.JwtOptions ：获取JWT配置信息，对应 appsetting.json 中的 HoaJwtOptions 节点。

除此之外，框架还提供了 AppGlobal.Configuration 属性，可以免构造函数注入方式获取配置信息，如：

AppGlobal.Configuration["Person:Name"]

内置配置说明

Hoa Framework 框架默认提供一些应用配置需求，相关配置在 Hoa.Web.Host 项目下的 appsetting.json 中：

{
  "ConnectionStrings": {
    "HoaDatabase": "Server=localhost;Database=Hoa;User=sa;Password=******;"
  },
  "AppConfigOptions": {
    "EnableGlobalAuthorizationFilter": false,
    "EnableGlobalUnifiedResultFilter": true,
    "EnableCorsSupport": false,
    "EnableGlobalPerformanceAnalysis": true,
    "EnableTenantMode": false
  },
  "CorsConfigOptions": {
    "PolicyName": "HoaAllowSpecificOrigins",
    "Origins": [
      "http://example.com",
      "http://www.contoso.com"
    ]
  },
  "HoaJwtOptions": {
    "HeaderKey": "Authorization",
    "SecurityKey": "wBPSILd@bHMxV1H!Pvc9eYMYdsyttpGl",
    "Audience": "Hoa.Client",
    "Issuer": "Hoa.Server",
    "AuthorizationClassify": "classify",
    "ClockSkewSeconds": 30,
    "ExpiredTime": 20
  },
  "HoaSwaggerOptions": {
    "DocumentTitle": "Hoa RESTFul API",
    "SecurityDefinitionName": "Bearer",
    "UnClassifiedName": "Default",
    "IsShowMSTestSummary": true,
    "Groups": {
      "Default": {
        "Title": "Default RESTFul API",
        "Description": "This is default restful api description.",
        "TermsOfService": "",
        "Contact": {
          "Name": "Monk",
          "Email": "monksoul@outlook.com",
          "Url": ""
        },
        "License": {
          "Name": "",
          "Url": ""
        }
      }
    }
  }
}

节点配置说明

ConnectionStrings：数据库连接字符串配置选项，支持多个连接字符串配置
- HoaDatabase：框架默认数据库连接字符串名称
AppConfigOptions：应用全局配置选项
- EnableGlobalAuthorizationFilter：是否启用全局授权过滤器，默认 false，设置为 true 后，所有的WebApi都需授权才能访问
- EnableGlobalUnifiedResultFilter：是否启用全局规范化返回接口，默认 true，设置为 false 后，直接返回不统一的结果，建议设置为 true
- EnableCorsSupport：是否启用跨域支持，默认 false，设置为 true 后，需配置 CorsConfigOptions 选项
- EnableGlobalPerformanceAnalysis：是否启用全局性能分析器，默认 true，设置为 false 后，不再显示详细的性能分析，建议部署上线后设置为 false
- EnableTenantMode：是否启用Saas多租户模式，默认为false
CorsConfigOptions：跨域配置选项
- PolicyName：策略名称
- Origins：允许来源配置，string[]类型
HoaJwtOptions：Jwt授权配置选项
- HeaderKey：授权检查请求报文头 Headers 名称，默认为 Authorization
- SecurityKey：Jwt Token 校验所需密钥，建议长度在 16 位以上
- Audience：Jwt 接受授权的一方，通常为客户端信息
- Issuer：Jwt 签发方
- AuthorizationClassify：实现多系统权限控制 Jwt Claim 标识
- ClockSkewSeconds：Jwt 有效生命周期的容错值，单位为秒，默认30s
- ExpiredTime：Jwt Token过期时间，单位分钟，默认20分钟
HoaSwaggerOptions：Swagger 文档配置选项
- DocumentTitle：文档标题
- SecurityDefinitionName：授权 Schema，系统基于Jwt授权，所以是 Bearer
- UnclassifiedName：默认文档名称
- IsShowMSTestSummary：是否启用汇总单元测试类
- Groups：多个版本API配置信息，支持多个动态配置，Key 为版本名称
  - Default：版本名称
    Title：API标题
    Description：描述
    TermsOfService合约地址
    Contact：联系信息
    Name：联系人名称
    Email：联系人邮箱
    Url：联系人主页
    License：协议
    Name：协议名称
    Url：协议地址

最后更新于4年前