VassasCo.Utility.ConfigHelper 1.2.0

ConfigHelper

零代码实体类与 JSON/XML 配置文件双向映射工具。支持特性标注和非侵入式 Fluent API 两种方式。

文件说明

快速开始

方式 1：特性标注（侵入式，适合配置类自己定义）

[JsonConfig("config/app.json")]
public class AppConfig : ConfigBase<AppConfig>
{
    [Config(Desc = "应用名称", Default = "MyApp", Required = true)]
    public string AppName { get; set; } = "";

    [Config(Desc = "端口号", Default = 8080)]
    public int Port { get; set; }

    [Config(Desc = "服务器列表")]
    public List<ServerInfo> Servers { get; set; } = new();
}

public class ServerInfo
{
    [Config(Desc = "服务器IP")]
    public string Ip { get; set; } = "";
    public int Port { get; set; }
}

方式 2：ConfigProfile（非侵入式，实体类零特性）

适用于不想让实体类引用配置库的场景（如共享 DTO、第三方 Model）：

// 实体类 — 零特性，干净
public class OrderModel
{
    public string OrderType { get; set; } = "";
    public string ChannelNo { get; set; } = "";
    public string ProductCode { get; set; } = "";
    public string ProductName { get; set; } = "";
    public int Quantity { get; set; }
}

// 映射配置 — 写在外部
var profile = new ConfigProfile<OrderModel>("config/order.json")
    .Map(o => o.OrderType,   key: "订货类型", desc: "订货类型", required: true)
    .Map(o => o.ChannelNo,   key: "渠道编号", desc: "渠道唯一编号")
    .Map(o => o.ProductCode, key: "货号",     desc: "商品编码")
    .Map(o => o.ProductName, key: "货品名称")
    .Map(o => o.Quantity,    key: "数量",     defaultValue: 0);

// 构建 ConfigHelper，后续使用完全一致
var helper = profile.Build();
var order = helper.Value;
helper.Save();
helper.EnableHotReload();

全局注册（Profile 模式也可用）

// 启动时注册一次
var helper = profile.Build();
ConfigManager.Register(helper);

// 任意线程、任意类中获取
var helper = ConfigManager.GetHelper<OrderModel>();
var order = helper.Value;
helper.Update(cfg => cfg.Quantity = 100);
helper.Save();

注意：[Description] 特性不会被自动导入为注释。如需注释，请使用 [Config(Desc="xxx")] 或 ConfigProfile.Map(desc: "xxx")。

加载与保存

// ConfigFactory 入口
var cfg = ConfigFactory.Load<AppConfig>();
ConfigFactory.Save(cfg);

// ConfigBase<T> 基类
var cfg = AppConfig.Current;

// 手动创建 ConfigHelper
var helper = new ConfigHelper<MyConfig>("config/my.json", ConfigFormat.Json);
var cfg = helper.Value;
helper.Save();
// 跨类获取（需先 Register）
var helper = ConfigManager.GetHelper<MyConfig>();

热重载

var helper = ConfigFactory.GetHelper<AppConfig>();
helper.EnableHotReload();  // 配置文件外部修改后自动重载

Update 原子修改

helper.Update(cfg =>
{
    cfg.AppName = "新名称";
    cfg.Servers.Add(new ServerInfo { Ip = "10.0.0.1" });
});
helper.Save();

事件监听

helper.ConfigChanged += (s, e) =>
{
    Console.WriteLine($"配置变更: {e.ChangeType}");
};
helper.ConfigSaving += (s, e) =>
{
    if (!Validate(e.Config)) e.Cancel = true; // 可取消保存
};

嵌套类型映射（ConfigProfile）

var profile = new ConfigProfile<AppConfig>("config/app.json")
    .Map(o => o.AppName, desc: "应用名")
    // 单个嵌套类
    .Nested<DatabaseConfig>(db => db
        .Map(d => d.Host, desc: "主机")
        .Map(d => d.Port, desc: "端口"))
    .Map(o => o.Database, desc: "数据库配置")
    // List<嵌套类>
    .Nested<ServerInfo>(si => si
        .Map(s => s.Ip, desc: "IP地址")
        .Map(s => s.Name, desc: "名称"))
    .Map(o => o.Servers, desc: "服务器列表");

var helper = profile.Build();

特性说明

类级特性

属性特性 [Config]

ConfigProfile.Map() 参数对照

内置转换器

• HexIntConverter - 十六进制
• TimeSpanStringConverter - 时间跨度
• DateTimeStringConverter - 日期时间
• BoolFormatConverter("是","否") - 布尔格式化
• NumberFormatConverter("F2") - 数字格式化
• VersionConverter - 版本号
• TypeNameConverter - 类型名
• EnumIntConverter - 枚举存数字

XML 配置

[XmlConfig("config/settings.xml", RootName = "Settings")]
public class XmlSettings : ConfigBase<XmlSettings>
{
    [Config(Desc = "服务名", Key = "ServiceName")]
    public string Name { get; set; } = "";
}

ConfigRawReader — 无需实体类直接读值

var ip = ConfigRawReader.GetJsonValue("config.json", "device.ip");
var name = ConfigRawReader.GetXmlValue("config.xml", "/AppSettings/ServiceName");

路径支持："servers[0].name"、"nested.deep.key"

兼容性

• .NET Standard 2.0
• .NET 6 / .NET 8 / .NET 9 / .NET 10