【Hi.Ltd 专题】第9期：Interop 配置互操作（JSON/INI/XML/YAML/注册表/扫码）

Hi.Ltd 专题第 9 期｜模块：Interop（Hi.Ltd.Interop.* + Hi.Ltd.Interface.I*）｜NuGet：Hi.Ltd 2026.7.11.1437 目标框架：net462 / net481 / net6.0 / net8.0 场景：设备 INI、配方 JSON/YAML、XML 点表、CSV 班报、注册表授权项、扫码枪 Hook。

第8期：Managements 插件、单例与服务定位

本期目标

适用范围

不该用 / 慎用

安装引用

using Hi.Ltd.Interop;
using Hi.Ltd.Interface;
using Hi.Ltd.Enumerations; // HKey
using Hi.Ltd.Attributes; // JsonProperty / YamlMember

互操作性（DLL）

JSON（JsonHelper）

XML：支持类/结构体/列表/字典；JsonIgnore/JsonProperty/CamelCase；与 Newtonsoft 常用用法对齐。

public sealed class DeviceConfig
{
[Hi.Ltd.Attributes.JsonProperty("ip")]
public string Ip { get; set; }
public int Port { get; set; }
}

var cfg = new DeviceConfig { Ip = "192.168.1.10", Port = 502 };

// 序列化为字符串（可显式传 camelCase / 输出 null 策略）
string json = JsonHelper.Create.SerializeToJsonString(cfg, useCamelCase: true, ignoreNull: true);

DeviceConfig back = JsonHelper.Create.DeserializeFromString<DeviceConfig>(json);

// 落盘
JsonHelper.Create.Serialize(@"D:\\cfg\\device.json", cfg);
var fromFile = JsonHelper.Create.Deserialize<DeviceConfig>(@"D:\\cfg\\device.json");

// 带路径单例
var helper = JsonHelper.Instance(@"D:\\cfg\\device.json");
string raw = JsonHelper.Create.ReadToJson(@"D:\\cfg\\device.json");

注1：此实现只是为了避免引入第三方库，保持基础库的纯净，有特殊需求建议使用 Newtonsoft 类库

INI（IniHelper / IniBase）

// 对象 ↔ INI 文件
IniHelper.Create.Serialize(@"D:\\cfg\\device.ini", cfg);
var cfg2 = IniHelper.Create.Deserialize<DeviceConfig>(@"D:\\cfg\\device.ini");

// 扁平加速（不支持嵌套）
IniHelper.Create.FastSerialize(@"D:\\cfg\\flat.ini", cfg, sectionName: "Device");
var flat = IniHelper.Create.FastDeserialize<DeviceConfig>(@"D:\\cfg\\flat.ini", "Device");

注:此序列化操作只针对简单的数据类型，复杂的，比如列表，数组，字典等请改用其它的文件类型

段键级（IniBase / IIni）：

IIni ini = IniHelper.Instance(@"D:\\cfg\\comm.ini");
ini.WriteValue("PLC", "Ip", "192.168.1.10");
string ip = ini.GetStringValue("PLC", "Ip", defaultValue: "127.0.0.1");
string[] sections = ini.GetAllSectionNames();
var items = ini.GetAllItems("PLC");
ini.DeleteKey("PLC", "Unused");
ini.EmptySection("Temp");

YAML（YamlHelper）

string yaml = YamlHelper.Create.SerializeToYamlString(cfg);
var rYaml = YamlHelper.Create.SerializeToYamlStringResult(cfg); // Result 版

YamlHelper.Create.Serialize(@"D:\\cfg\\device.yaml", cfg);
var cfg3 = YamlHelper.Create.Deserialize<DeviceConfig>(@"D:\\cfg\\device.yaml");

if (YamlHelper.Create.TryDeserialize<DeviceConfig>(@"D:\\cfg\\device.yaml", out var cfg4))
{ /* ok */ }

var dict = YamlHelper.Create.ReadToDictionary(@"D:\\cfg\\device.yaml");
int port = YamlHelper.GetValueByPath(dict, "server.port", defaultValue: 502);
var portR = YamlHelper.GetValueByPathResult<int>(dict, "server.port");

// 多文档 —
var docs = YamlHelper.ParseDocuments(yamlText);
var docsR = YamlHelper.ParseDocumentsResult(yamlText);

键名：YamlMember.Alias 或 camelCase（GetYamlKeyForProperty）。

XML 点表（XmlBase / XmlUtils）

对象序列化：

XmlUtils.Instance.Serialize(@"D:\\points\\axis.xml", cfg);
var x = XmlUtils.Instance.Deserialize<DeviceConfig>(@"D:\\points\\axis.xml");
var named = XmlUtils.GetInstance(@"D:\\points\\axis.xml", root: "Root");

层级点表（XmlBase/IXml）：CreateFile、Add/AddSingle、AddThreeLayer*、Alter*、Write*、Read*/ReadSingle/ReadThreeLayer*、Delete*。

// 示意：两层/三层读写 —— 具体参数顺序以 IntelliSense/XML 为准
// CreateFile(path, rootName)
// WriteThreeLayerSingle(path, root, child, grand, key, value)
// ReadThreeLayerSingle(…, out value)

CSV / TOML / XLIFF

// CSV：列表往返，可指定 hasHeader / separator
string csv = CsvUtils.Create.SerializeToCsvString(rows, hasHeader: true, separator: ',');
CsvUtils.Create.Serialize(@"D:\\report\\shift.csv", rows, true, ',');
var list = CsvUtils.Create.Deserialize<RowDto>(@"D:\\report\\shift.csv", true, ',');

// TOML
string toml = TomlUtils.Create.SerializeToTomlString(cfg);
TomlUtils.Create.Serialize(@"D:\\cfg\\app.toml", cfg);
var t = TomlUtils.Create.DeserializeFromString<DeviceConfig>(toml);
var dictT = TomlUtils.Create.ParseToDictionary(toml);

XLIFF：本地化交换，见 XliffUtils/IXliff（与 LocateFactory 场景相邻）。

注册表（RegistryFacade）

命名刻意避开 Microsoft.Win32.Registry。

using Hi.Ltd.Enumerations;

RegistryFacade.Serialize(
HKey.CURRENT_USER,
@"Software\\HiLtd\\Line1",
cfg,
name: null);

var back = RegistryFacade.Deserialize<DeviceConfig>(
HKey.CURRENT_USER,
@"Software\\HiLtd\\Line1",
name: null);

// 扁平
RegistryFacade.FastSerialize(HKey.LOCAL_MACHINE, @"Software\\HiLtd\\License", license, null);

注：同样基于跨平台的需求，此部分后续会移植到Hi.Ltd.Win32类库。

扫码枪（ScannerBase）

using Hi.Ltd.Interop;
using Hi.Ltd.Interface;

public sealed class LineScanner : ScannerBase
{
}

var scanner = new LineScanner();
scanner.OnScannerCode += code =>
{
$"扫码入站: {code}".Info();
// 工单号入队
};
scanner.Start();
// scanner.StartInActive(heartbeatMs);
// scanner.Stop(); scanner.Dispose();

ScannerHookToUnicode.ToUnicode 等处理钩子键码与修饰键。

完整示例：启动加载 INI，失败回退 JSON

using System.IO;
using Hi.Ltd.Interop;

public static class ConfigLoader
{
public static DeviceConfig Load(string iniPath, string jsonFallback)
{
try
{
if (File.Exists(iniPath))
return IniHelper.Create.Deserialize<DeviceConfig>(iniPath);
}
catch (System.Exception ex)
{
$"INI 加载失败，回退 JSON: {ex.Message}".Warn();
}

string json = File.ReadAllText(jsonFallback);
return JsonHelper.Create.DeserializeFromString<DeviceConfig>(json);
}

public static void SaveBoth(DeviceConfig cfg, string iniPath, string jsonPath)
{
IniHelper.Create.Serialize(iniPath, cfg);
JsonHelper.Create.Serialize(jsonPath, cfg);
}
}

若某 API 返回 Result，改为看 Successed，勿盲目 catch。

可能出现的问题（现场坑）

异常点与应对

常见问题

Q: Https 泛型 JSON 用哪套？ A: IHttpJsonSerializer，默认即 JsonHelper 实现。

下篇预告

第10期：Data（ASCII / Dongle / PagedList / Native / 拼音档）