Xbgit.Tools 1.4.0-Alpha3

Xbgit.Tools - 综合工具包

概述

Xbgit.Tools 是一个综合性的工具包，提供了多种实用功能，包括网络通信、日志记录、数据处理、文件操作、设备控制、安全加密、系统管理等。适用于 .NET 9.0 开发环境，旨在简化开发流程并提高效率。

功能模块

1. Core - 核心工具

提供基础的通用工具类：

• StringUtils.cs：字符串操作工具（比较、替换、正则、随机生成、全角检测等）。
• DateTimeUtils.cs：日期时间处理工具（格式化、运算、比较、NTP 网络时间）。
• EnumUtils.cs：枚举扩展工具。
• RetryUtils.cs：重试/弹性机制，支持指数退避、自定义重试条件、CancellationToken。
• CacheUtils.cs：线程安全内存缓存，支持 TTL 过期、LRU 淘汰、后台自动清理。
• EncodingUtils.cs：编码转换工具（Base64、URL、Hex、Unicode、HTML、HexDump）。
• ReflectionUtils.cs：反射工具（属性读写、方法调用、对象映射、特性扫描、枚举描述）。
• CronUtils.cs：Cron 表达式解析与调度计算（下次/上次执行时间、匹配检测、中文描述）。
• CommandLineUtils.cs：命令行参数解析器（长短选项、标志、引号感知、命令构建）。
• I18nUtils.cs：国际化资源管理（多语言、JSON 加载、点路径键、回退语言、格式化参数，支持 LocaleRoot / KeyRoot 两种 JSON 结构）。
• Configuration/GenericConfigManager.cs：基于 JSON 的线程安全单例配置管理器。
• StatusStyleUtils.cs：状态样式解析（OperationStatus 枚举→StatusLevel 语义级别→StatusStyle 结构体，含颜色/文本/符号，UI 无关）。
• OperationHandlerUtils.cs：通用操作处理（同步/异步安全执行、异常捕获、计时、回调、防重入、取消支持、IOperationFeedback 反馈接口）。
• IdUtils.cs：ID 生成工具（GUID 变体、短 ID/nanoid、有序 GUID、Snowflake 雪花 ID）。
• RateLimitUtils.cs：限流器工具（令牌桶、漏桶、固定窗口、滑动窗口四种算法，线程安全）。
• EventBusUtils.cs：进程内事件总线（按类型发布/订阅、同步/异步、守卫与回调、全局默认实例）。
• ObjectPoolUtils.cs：通用对象池（预创建、最大容量、自动重置与销毁回调、IDisposable 支持）。
• StateMachineUtils.cs：轻量级有限状态机（状态转换规则、进入/离开回调、转换守卫、线程安全触发）。
• TemplateUtils.cs：轻量模板引擎（{{key}} 占位符替换、条件渲染 #if/#else、循环渲染 #each）。
• CircuitBreakerUtils.cs：熔断器工具（三态模型 Closed/Open/Half-Open，保护不稳定外部调用）。
• AsyncUtils.cs：异步工具（Task 超时控制、批量并行执行带并发限制、异常聚合、轮询）。

2. Data - 数据处理工具

提供数据相关的工具类：

• JsonUtils.cs：JSON 格式化、验证、合并、序列化/反序列化。
• SqliteHelper.cs：基于 Dapper 的 SQLite 全功能封装（连接池、CRUD、批量插入、跨库合并、分页、备份）。
• XmlUtils.cs：XML 节点/属性增删改查（XPath）。
• VersionUtils.cs：日期版本号体系（YYYY.MM.DD.N），支持解析、比较、自增。
• CsvUtils.cs：CSV/TSV 读写，支持 RFC 4180（引号字段、嵌入换行、分隔符转换）。
• IniUtils.cs：INI 配置文件读写（Section/Key/Value、注释保留）。
• ValidationUtils.cs：数据校验（邮箱、手机号、身份证、银行卡、统一社会信用代码、ISBN、车牌号等）。
• Mock/GenDataUtils.cs：测试数据生成器（中文姓名、身份证、银行卡、地址、公司名等）。
• YamlUtils.cs：YAML 读写工具（对象与 YAML 字符串/文件互转，支持多种命名约定，动态解析）。
• BinaryUtils.cs：二进制数据工具（Hex 转换、位操作、字节序转换、结构体与字节互转、字节数组操作）。

3. Device - 设备相关工具

提供设备相关的工具类：

• Android/AndroidUtils.cs：Android ADB/scrcpy 封装（应用管理、文件传输、屏幕投射、触摸模拟）。
• Android/AndroidSqliteTool.cs：通过 ADB 在 Android 设备上执行 SQLite 查询。
• SerialPortUtils.cs：串口通信封装（打开/关闭、读写、后台监听、多格式支持）。
• WakeOnLan.cs：网络唤醒（WOL），支持多种 MAC 格式、重复发送提高可靠性。

4. Files - 文件操作工具

提供文件操作相关的工具类：

• FileUtils.cs：文件读写、复制、移动、重命名、MD5 校验、变更检测。
• FolderUtils.cs：文件夹大小、批量 MD5、条件创建、递归复制（CopyFolder）。
• Compression/GzipUtils.cs：GZip 压缩解压，支持 AES 加密压缩。
• Compression/ZipUtils.cs：ZIP 压缩解压，支持 AES 加密压缩。
• FileWatcherUtils.cs：增强型文件监控（防抖、包含/排除模式过滤、事件聚合）。
• ImageUtils.cs：图片处理（缩放、裁剪、旋转、翻转、文字/图片水印、压缩、格式转换、缩略图、Base64）。
• PdfUtils.cs：PDF 操作（合并、拆分、文本提取、水印、删除页、旋转、图片转 PDF、信息读取）。
• VersionControl/SvnUtils.cs：SVN CLI 封装（update/commit/status/远程检查）。
• VersionControl/GitUtils.cs：Git CLI 封装（clone/pull/push/commit/branch/tag/stash/log）。
• BackupUtils.cs：文件/文件夹备份还原（原样复制/ZIP 压缩、按数量/天数保留、备份查询、自动清理、全局/临时备份根目录）。
• FileHashUtils.cs：文件哈希工具（MD5/SHA256/SHA384/SHA512 流式计算、批量校验、字符串/字节哈希）。
• PathUtils.cs：路径操作工具（规范化、安全拼接、相对路径计算、通配符展开、路径比较）。
• GlobUtils.cs：文件模式匹配工具（glob 通配符搜索、** 递归目录、模式转正则、包含/排除过滤）。

5. Net - 网络通信工具

提供网络通信相关的工具类：

• MqttUtils.cs：MQTT 协议工具，支持多 Broker 管理、消息发布/订阅、自动重连控制等。
• HttpUtils.cs：HTTP 请求工具（GET/POST，支持代理）。
• FtpUtils.cs：FTP 文件传输工具（上传/下载/列目录/删除）。
• WebSocketUtils.cs：WebSocket 客户端，支持自动重连、持续监听、事件驱动。
• SocketUtils.cs：TCP/UDP Socket 封装（服务端/客户端、端口检测）。
• EmailUtils.cs：SMTP 邮件发送（附件、抄送、密送、HTML 正文）。
• Pop3Client.cs：POP3 邮件接收（SSL/TLS、mTLS、USER/PASS 认证、STAT/LIST/RETR/DELE）。
• EmailParser.cs：POP3 邮件正文解析（RFC 2047 编码字解码、MIME 多部分递归拆分、base64/quoted-printable 解码、多字符集解码、附件提取）。
• EmailMessage.cs：已解析邮件模型（头字段、纯文本/HTML 正文、附件）。
• SshUtils.cs：SSH/SFTP 远程操作（命令执行、文件上传下载、目录管理）。
• RestApiUtils.cs：Fluent REST API 客户端构建器（链式配置、Bearer/Basic 认证、重试、文件上传下载）。
• Communication/：传输无关的节点间通信框架（心跳、P2P/广播、版本约束匹配），可注入任意 ITransportChannel。
• Transport/：传输通道抽象与工厂（ITransportChannel/TransportFactory、MQTT 与 Socket 通道、TLV 帧编解码）。
• Discovery/：临时服务器 UDP 发现与宿主（星型拓扑下的动态发现、公告广播、当前服务器设置）。
• Messaging/：端到端加密即时消息能力层（MessagingClient 门面、在线状态/联系人/群组/阅后即焚管理、SQLite 本地历史、大消息分片重组）。
• NetworkUtils.cs：网络诊断工具（本机 IP 查询、Ping 检测、端口占用检查、互联网连通性探测、DNS 解析）。

MqttUtils 功能说明

6. Security - 安全加密工具

提供安全加密相关的工具类：

• SafeUtils.cs：RSA/AES/AES-GCM 加解密、MD5/SHA256 哈希、PBKDF2/HKDF 密钥派生、ECDH 密钥协商、RSA-PSS 数字签名、TOTP 动态口令、字符串混淆。
• MultiDataEncryptor.cs：多公钥分块加密/多私钥解密。
• CertificateUtils.cs：X.509 证书管理（自签生成、PFX/CER 导入导出、有效期/指纹校验、TLS 流封装）。
• SecureChannel.cs：端到端安全通道（临时 ECDH 握手、HKDF 会话密钥、AES-GCM 加密 + RSA-PSS 签名、密钥自动轮换）。
• SecureChannelConfig.cs：安全通道配置（本节点/受信任证书、加密开关、密钥轮换策略、握手超时）。
• JwtUtils.cs：自包含 JWT 工具（HS256/384/512 签名、Token 生成/验证/解析，无需外部 JWT 库）。
• PasswordUtils.cs：密码工具（随机密码生成、强度评估、PBKDF2 哈希与验证）。
• AuthManager.cs：通用权限管理器（泛型框架，等级枚举/数量/判断逻辑由调用方注入，提供缓存、等级比较、多配置）。
• AuthManagerConfig.cs：权限管理器调用侧配置（登录名提供者、等级解析委托、等级排序、缓存失效文件）。
• PermissionMenuItem.cs：权限菜单项模型（泛型，带所需等级与子项）。

7. Log - 日志记录工具

提供日志记录相关的工具类：

• RasUtils.cs：基于 MQTT 的远程日志发送工具（RSA 加密传输、离线队列、自动重试）。
• MqttConfig.cs：MQTT 日志配置模型。

8. System - 系统工具

提供 Windows 系统相关的工具类：

• WinUtils.cs：系统信息、开机自启、管理员权限检测、UAC 提权、系统代理管理。
• ServiceUtils.cs：Windows 服务管理（查询/启动/停止/重启/安装/卸载）。
• TaskSchedulerUtils.cs：Windows 计划任务管理（创建/删除/运行/启用/禁用）。
• ClipboardUtils.cs：剪贴板操作（文本/图片，P/Invoke 实现，线程安全）。
• ScreenCaptureUtils.cs：屏幕截图（全屏/区域/窗口，多显示器支持，PNG 输出）。
• HardwareInfoUtils.cs：硬件信息查询（CPU/内存/磁盘/GPU/主板/网卡，WMI 实现）。
• EventLogUtils.cs：Windows 事件日志读写（写入/读取/清除/源管理/日志信息）。
• ProcessUtils.cs：进程管理工具（启动外部程序、捕获标准输出/错误、按名称/PID 查找与终止、超时控制）。
• EnvironmentUtils.cs：环境变量工具（读取/设置/删除，支持进程/用户/机器三作用域、路径展开、运行环境检测）。
• PerformanceUtils.cs：性能监控工具（进程内存/线程/句柄采样、GC 信息、定时采样、操作计时）。

9. Exceptions - 自定义异常

提供统一异常体系：

• XbgitException：基础异常类。
• NetworkException：网络相关异常。
• DeviceException：设备通信异常。
• ConfigurationException：配置异常。
• FileOperationException：文件操作异常。
• SecurityException：加密/安全异常。
• ValidationException：数据校验异常。
• RetryExhaustedException：重试耗尽异常。
• ExceptionHelper：异常辅助工具（完整消息提取、网络异常判断、异常包装）。

安装

使用 NuGet 包管理器

dotnet add package Xbgit.Tools --version 1.4.0-Alpha2

使用 PackageReference

在你的 .csproj 文件中添加以下行：

<PackageReference Include="Xbgit.Tools" Version="1.4.0-Alpha2" />

依赖项

版本历史

1.4.0-Alpha3

• feat(security): 新增通用权限管理器 AuthManager<TLevel>（泛型框架）。框架不定义具体权限等级，等级枚举/数量/判断逻辑由调用方通过 AuthManagerConfig<TLevel> 注入；提供当前等级缓存（TTL + 文件戳失效）、等级比较（HasLevel/IsLevel）、多配置支持；配套泛型菜单项模型 PermissionMenuItem<TLevel>。

1.4.0-Alpha2

• feat(email): EmailUtils 的 Send / SendAsync / SendWithAttachment / SendToMultiple 新增 authUser 参数（SMTP 认证用户名，默认为 from 地址），支持发件人地址与认证用户名不同的服务器；新增单元测试（FakeSmtpServer 本地回环）和真实 SMTP 环境测试。
• feat(pop3): 新增 EmailParser / EmailMessage 邮件正文解析（RFC 2047 编码字解码、MIME 多部分递归拆分、base64 / quoted-printable 解码、UTF-8 / GB2312 / ISO-8859-1 等多字符集解码、附件提取）；Pop3Client 新增 RetrieveParsedMessage / RetrieveParsedMessageAsync。
• feat: 22 个工具类 API 易用性优化（全部向后兼容）
  • Core: StringUtils 增加 StringComparison/CultureInfo/RegexOptions；EncodingUtils 增加 Encoding；DateTimeUtils.GetNetworkTime 增加 timeoutMs；AsyncUtils 增加 CancellationToken；RetryUtils 增加 maxDelayMs；TemplateUtils 增加 prefix/suffix/Encoding；CircuitBreakerUtils/EventBusUtils 增加 CancellationToken
  • Data: JsonUtils 增加 Formatting/Encoding/MergeArrayHandling；IniUtils 增加 Encoding；YamlUtils 增加 Encoding/NamingStyle；BinaryUtils 增加 upperCase/offset
  • Files: FileUtils 增加 Encoding/overwrite；PathUtils 增加 StringComparison；FolderUtils 增加 searchPattern/recursive
  • Net: HttpUtils 增加 timeoutMs/CancellationToken/contentType；NetworkUtils 增加 host/port/CancellationToken/networkInterfaceName；RestApiUtils 全部请求方法增加 CancellationToken
  • Security: SafeUtils 增加 keySizeInBits/upperCase/Encoding；JwtUtils 增加 issuer/audience
  • System: ProcessUtils 增加 CancellationToken/environmentVariables；PerformanceUtils 增加 forceFullCollection/warmupIterations

1.4.0-Alpha1

• feat(tests): 新增 19 个工具类及单元测试（~150+ 测试用例），覆盖 Core/Data/Files/Security/System/Net 六个命名空间
• fix(async): 修复 AsyncUtils.ForEachAsync 空输入时 SemaphoreSlim 构造崩溃

1.3.0-Alpha5

• fix(mqtt): 修复 MQTT 内联重连后订阅丢失及后台重连定时器耗尽后无人重试

1.3.0-Alpha4

• feat: 升级 SSH.NET 依赖到 2026.0.0

1.3.0-Alpha3

• fix(security): 修复 SecureChannel 并发双向握手时 ephemeral 密钥未复用导致密钥不匹配

1.3.0-Alpha2

• feat(security): 增强 SecureChannel 启动/停止时自动管理安全数据主题订阅

1.3.0-Alpha1

• feat: 新增端到端加密即时消息系统（IM）。传输层抽象（Socket/MQTT 双底座）、临时服务器与自动发现、X.509 证书与 ECDH/AES-GCM 安全通道、MessagingClient 门面（私聊/群聊/阅后即焚、大消息分片、SQLite 本地历史）

1.2.0-Alpha3

• fix: 修复 PdfUtils 歧义引用与 PdfSharp 6.x 过时 API；增强 EventLogUtils；ImageUtils 平台标记；PdfPig 包名修正

1.2.0-Alpha2

• feat: 第二批功能扩展
  • 新增 Core/ReflectionUtils: 反射工具（属性读写、方法调用、对象映射、特性扫描）
  • 新增 Core/CronUtils: Cron 表达式解析与调度计算
  • 新增 Core/CommandLineUtils: 命令行参数解析器
  • 新增 Core/I18nUtils: 国际化资源管理（多语言、JSON 加载、点路径键）
  • 新增 Files/ImageUtils: 图片处理（缩放/裁剪/旋转/水印/压缩/格式转换）
  • 新增 Files/PdfUtils: PDF 操作（合并/拆分/水印/文本提取/旋转/图片转 PDF）
  • 新增 Net/RestApiUtils: Fluent REST API 客户端构建器
  • 新增 System/EventLogUtils: Windows 事件日志读写

1.2.0-Alpha1

• feat: 大规模功能扩展
  • 新增 Core/RetryUtils: 重试/弹性机制，支持指数退避
  • 新增 Core/CacheUtils: 线程安全内存缓存，支持 TTL 和 LRU 淘汰
  • 新增 Core/EncodingUtils: 编码转换（Base64/URL/Hex/Unicode/HTML）
  • 新增 Data/CsvUtils: CSV/TSV 读写，支持 RFC 4180
  • 新增 Data/IniUtils: INI 配置文件读写
  • 新增 Data/ValidationUtils: 数据校验（邮箱/手机号/身份证/银行卡/统一社会信用代码等）
  • 新增 Net/WebSocketUtils: WebSocket 客户端，支持自动重连
  • 新增 Net/SocketUtils: TCP/UDP Socket 封装
  • 新增 Net/EmailUtils: SMTP 邮件发送
  • 新增 Net/SshUtils: SSH/SFTP 远程操作
  • 新增 Device/SerialPortUtils: 串口通信封装
  • 新增 Device/WakeOnLan: 网络唤醒（WOL）
  • 新增 Files/FileWatcherUtils: 增强型文件监控（防抖/过滤）
  • 新增 Files/VersionControl/GitUtils: Git CLI 封装
  • 新增 System/ServiceUtils: Windows 服务管理
  • 新增 System/TaskSchedulerUtils: Windows 计划任务管理
  • 新增 System/ClipboardUtils: 剪贴板操作
  • 新增 System/ScreenCaptureUtils: 屏幕截图
  • 新增 System/HardwareInfoUtils: 硬件信息查询（WMI）
  • 重构 Exceptions/CustomException: 统一异常体系

1.1.5-Alpha8

• feat(mqtt): MqttUtils 新增重连控制与 Broker 移除功能
  • 新增 SetReconnectEnabled 方法，支持按 Broker 启用/禁用自动重连
  • 新增 SetAllReconnectEnabled 方法，支持全局启用/禁用自动重连
  • 新增 RemoveBrokerAsync 方法，支持安全移除目标服务器（断开连接、停止重连、清理订阅、释放资源）
  • 断开连接回调中增加重连启用状态判断，禁用时自动跳过重连

1.0.0

• 初始版本

许可证

本项目基于 自定义许可证。

贡献

欢迎贡献代码和报告问题！请参考 贡献指南。

联系方式

• 作者: 张天宝
• 公司: xbgit.cn
• 邮箱: ztianb@foxmail.com