🔧 工具库
Snet.Utility 提供 150+ 扩展方法与工具类，涵盖工业数据操作、字节处理、网络操作、JSON/XML 序列化及深度对象比较。
包名： Snet.Utility
目标框架： .NET 8.0 / .NET 10.0
依赖项： Newtonsoft.Json 13.0.4, protobuf-net 3.2.56
▶️ 快速开始
dotnet add package Snet.Utility
常用扩展方法，对所有对象可用：
using Snet.Utility;
// JSON 序列化
var json = myObject.ToJson(true); // 格式化输出
var obj = json.ToJsonEntity<MyType>(); // 反序列化
// 深度对象比较
var result = expected.Comparer(actual);
Console.WriteLine($"相等: {result.result}, 差异: {result.message}");
// DateTime 格式化
string dateStr = DateTime.Now.ToDateTimeString();
⚙️ 安装
Snet.Utility 是 Snet.Core 的传递依赖。若已安装 Snet.Core，则无需额外安装。
🧠 核心概念
扩展方法
通过 using Snet.Utility 使用：
| 方法 | 描述 |
|---|---|
ToJson(bool indented) |
序列化为 JSON 字符串（Newtonsoft.Json） |
ToJsonEntity<T>() |
反序列化 JSON 字符串为类型对象 |
ToXml() |
序列化为 XML 字符串 |
ToXmlEntity<T>() |
反序列化 XML 字符串为类型对象 |
ToBytes() |
字符串转字节数组（默认 UTF-8） |
ToBytes(Encoding) |
指定编码转字节数组 |
ToDateTimeString() |
DateTime 格式化为 "yyyy-MM-dd HH:mm:ss" |
Comparer<T>(T other) |
深度比较，返回 (bool result, string message) |
处理器类
| 处理器 | 用途 |
|---|---|
ByteHandler |
字节数组操作、十六进制转换、字节序 |
NetHandler |
Ping、DNS 解析、端口连通性检查 |
FileHandler |
文件读写/追加/复制/删除 |
FtpHandler |
FTP 上传/下载 |
TimeHandler |
DateTime 转换、秒表计时、时区 |
XmlHandler |
XML 序列化辅助 |
SvgHandler |
SVG 渲染工具 |
RMAHandler |
资源管理自动化 |
对象比较框架
位于 Snet.Utility.comparer 的递归深度比较引擎：
- 可配置深度的
ComparisonConfig - 单属性自定义验证
- 文本与 HTML 差异报告
- 类型专属比较器
- 忽略模式与排除规则
var config = new ComparisonConfig { MaxDifferences = 100, MaxDepth = 5 };
var result = expected.CompareTo(actual, config);
if (!result.AreEqual)
foreach (var diff in result.Differences)
Console.WriteLine($"{diff.PropertyName}: {diff.Object1Value} != {diff.Object2Value}");
📚 API 参考
ByteHandler
| 方法 | 描述 |
|---|---|
ByteToHexString(byte[]) |
字节数组转十六进制字符串 |
HexStringToByte(string) |
十六进制字符串转字节数组 |
ByteReverse(byte[]) |
反转字节数组（大小端转换） |
BoolArrayToByte(bool[]) |
8位布尔数组转字节 |
ByteToBoolArray(byte) |
字节转8位布尔数组 |
NetHandler
| 方法 | 描述 |
|---|---|
Ping(string, int) |
Ping 主机，返回延迟 ms |
DnsResolve(string) |
DNS 解析，返回 IP 地址 |
IsPortOpen(string, int, int) |
检查 TCP 端口是否开放 |
GetLocalIP() |
获取本机 IP 地址 |
FileHandler
| 方法 | 描述 |
|---|---|
ReadAllText(string) |
读取文件内容 |
WriteAllText(string, string) |
写入字符串到文件 |
AppendAllText(string, string) |
追加内容到文件 |
CopyFile(string, string, bool) |
带覆盖选项的复制 |
TimeHandler
| 方法 | 描述 |
|---|---|
StartRecord() |
启动秒表计时 |
StopRecord() |
停止并返回耗时 ms |
ToDateTimeString(DateTime) |
格式化 "yyyy-MM-dd HH:mm:ss" |
UnixTimestampToDateTime(long) |
Unix 时间戳转 DateTime |
💻 代码示例
JSON 序列化往返
using Snet.Utility;
var device = new { Name = "PLC-001", Ip = "192.168.1.100", Port = 502 };
string json = device.ToJson(true);
var restored = json.ToJsonEntity<DeviceConfig>();
深度比较
var diff = oldConfig.Comparer(newConfig);
Console.WriteLine($"相等: {diff.result}\n变化: {diff.message}");
字节操作
byte[] data = { 0x01, 0x02, 0x03, 0x04 };
string hex = ByteHandler.ByteToHexString(data); // "01020304"
byte[] rev = ByteHandler.ByteReverse(data); // { 0x04, 0x03, 0x02, 0x01 }
网络检查
long latency = NetHandler.Ping("192.168.1.100", 3000);
bool isOpen = NetHandler.IsPortOpen("192.168.1.100", 502, 2000);
❓ FAQ
1. ToJson 与 System.Text.Json 如何选择？
ToJson() 使用 Newtonsoft.Json 提供便捷调用。对于性能敏感场景，可直接使用 System.Text.Json 配合源生成器。
2. Comparer 是否线程安全？
并发读取安全。若被比较对象可变且在比较期间被修改，结果可能不一致——建议使用不可变快照。
3. ByteHandler 是否支持所有字节序？
ByteReverse 处理字节级反转。字级字节交换（PLC 常用）请使用 Snet.Core 的 BytesTransformHandler（ABCD/BADC/CDAB/DCBA）。
📅 版本历史
| 日期 | 版本 | 变更 |
|---|---|---|
| 2026-07-23 | — | .NET 8/10。Newtonsoft.Json 13.0.4, protobuf-net 3.2.56。150+ 扩展方法，8 个处理器类，完整对象比较框架。 |