Liwendong.Utility 3.3.1

Liwendong.Utility

通用辅助工具集合，一个包覆盖 .NET Framework 老项目到 .NET 8 新项目。

支持的目标框架

多框架差异通过条件编译处理，同一份调用代码在六个框架下均可编译。 已知的平台相关限制见下方「平台与多版本注意事项」。

安装

dotnet add package Liwendong.Utility

工具类一览

使用示例

配置读取（无配置文件也不会崩）

// 缺少 appsettings.json 时返回默认值，不抛异常（net451 与 net8.0 行为一致）
var size = ConfigHelper.GetValue("LogFileMaxSize", 2M);
var conn = ConfigHelper.GetConnectionStrings<string>("Default");

// 可判断配置是否真的加载成功
if (!ConfigHelper.HasConfiguration)
{
    // 输出诊断信息
}

异步 HTTP 请求

// HttpClientHelper：Task-based 异步，支持取消
var json = await HttpClientHelper.GetStringAsync(url, cancellationToken: cts.Token);
var model = await HttpClientHelper.GetJsonAsync<MyModel>(url);
var result = await HttpClientHelper.PostJsonAsync(url, new { name = "test" });

// HttpHelper 的异步重载
var info = await HttpHelper.GetAsync(url, "a=1");

缓存

CacheHelper.Set("key", value);                          // 默认滑动过期 20 分钟
var v = CacheHelper.GetOrAdd("key", () => LoadData());  // 不存在时自动生成

口令哈希与现代加密

var hash = SecurityHelper.HashPassword("mypassword");        // PBKDF2
bool ok = SecurityHelper.VerifyPassword("mypassword", hash);

// AES-256-GCM（仅 net5.0+，密文被篡改会返回 null）
var cipher = SecurityHelper.AesGcmEncrypt("secret", key);
var plain = SecurityHelper.AesGcmDecrypt(cipher, key);

邮件发送（MailKit，推荐）

// 1. 便捷异步：自动按发件人域名推断 SMTP（内置 163/qq/gmail/aliyun 等域名表）
var (ok, msg) = await EmailHelper.SendEmailAsync(
    toEmail:      "receiver@example.com",
    subject:      "订单通知",
    htmlBody:     "<h1>你好</h1>",
    fromEmail:    "sender@qq.com",
    password:     "授权码",
    attachments:  new[] { @"D:\report.xlsx" });

// 2. 完整控制：抄送、密送、纯文本备选、加密方式、超时、取消令牌
var message = new EmailMessage
{
    FromAddress = "sender@example.com",
    FromDisplayName = "系统通知",
    Subject = "中文主题不会乱码",
    HtmlBody = "<b>HTML 正文</b>",
    TextBody = "纯文本备选",
    Priority = MimeKit.MessagePriority.Urgent,
    AttachmentPaths = { @"D:\a.pdf" }
};
message.To.Add("a@example.com");
message.Cc.Add("b@example.com");
message.Bcc.Add("c@example.com");

var options = new SmtpOptions("smtp.example.com", "sender@example.com", "授权码", 587)
{
    SocketOptions = MailKit.Security.SecureSocketOptions.StartTls,
    Timeout = 30000
};

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
var result = await EmailHelper.SendEmailAsync(message, options, cts.Token);

// 3. 同步版本（内部以线程池线程执行，不会因同步上下文死锁）
var sync = EmailHelper.SendEmailByMailKit(message, options);

新旧实现对比：

SendEmail（基于 System.Net.Mail.SmtpClient）保留不变，现有代码无需迁移； 新代码建议使用 MailKit 版本。

JSON

var json = JsonHelper.Serialize(obj);
var obj  = JsonHelper.Deserialize<MyModel>(json);
var name = JsonHelper.GetValue(json, "data.list[0].name");

平台与多版本注意事项

1. System.Drawing 仅 Windows：ImageHelper、BarCodeHelper、Gif/* 依赖 System.Drawing.Common，已标注 [SupportedOSPlatform("windows")]。 在 Linux / 容器环境调用会抛 PlatformNotSupportedException，请改用 ImageSharp / SkiaSharp。

2. AES-GCM 全框架可用：SecurityHelper.AesGcmEncrypt/AesGcmDecrypt 在 net5+ 与 netcoreapp3.1 使用平台原生 AesGcm，在 net451/net46/net48 走 BouncyCastle 实现，密文格式统一（Base64(nonce12+tag16+cipher)），跨框架互操作。 PBKDF2 全框架可用。

3. X509Certificate2 的释放：该类型直到 .NET Framework 4.6 才实现 IDisposable， 因此 net451 下无法使用 using，库内部已按条件编译统一处理。

4. 配置键的命名：netcore 下 GetAppSettings("X") 读取 AppSettings:X 节点， net451 下读取 App.config 的 <appSettings> 配置节，两者配置结构不同， 跨框架迁移时需注意。推荐使用 GetValue 配合统一的配置结构。

重要变更（V3.1.0）

• 修复：ConfigHelper 在缺少 appsettings.json 时抛 TypeInitializationException， 导致控制台 / 类库 / 单元测试等非 ASP.NET 环境下整个类不可用，并连带使 LogHelper 静默失效。 现改为延迟构建 + 缺失时回退空配置。
• 修复：ImageHelper.AddFontWaterMark 判空逻辑写反，调用方传入的水印文字被强制覆盖。
• 修复：ApiHelper.VerifyRequestSignature 转发时漏传 vaildSeconds，导致时间戳有效期校验被忽略。
• 修复：Snowflake 的状态字段误声明为 static，同进程多实例会互相覆盖产生重复 ID。
• 修复：EmailHelper 默认端口误写为 578（修正为 587），并补齐资源释放。
• 修复：CertHelper.GetPrivateKey / GetPrivateKeyFromStore 为半成品（前者丢弃结果，后者恒定返回空串）。
• 更新：CertHelper 公钥 / 私钥读取改用 GetRSAPublicKey() / GetRSAPrivateKey() （PublicKey.Key、PrivateKey 已在 .NET 8 标记为 SYSLIB0027 / SYSLIB0028 过时）。 net451 无新 API，仍走旧路径；非 RSA 证书（如 DSA）自动回退旧路径，行为不变。
• 安全：移除 CertHelper 中硬编码的默认加密串，以及 SecurityHelper 内置的 DES 默认密钥 liwen528（公开代码中硬编码密钥等同于明文）。未显式设置密钥时 DESEncrypt/DESDecrypt 会抛出明确异常。
• 命名：EncodingHepler → EncodingHelper、ValidatetionHelper → ValidationHelper、 ASE_Encrypt/ASE_Decrypt → AES_Encrypt/AES_Decrypt、GetPlulicKey → GetPublicKey。 旧名称保留并标记 [Obsolete]，现有代码仍可编译，建议尽快迁移。
• 破坏性：ConfigHelper.GetEntity<T> 在 net451 下的泛型约束由 class, IConfigurationSectionHandler, new() 放宽为 class, new()，与 netcore 保持一致。
• 新增：EmailHelper 增加基于 MailKit 的 SendEmailAsync / SendEmailByMailKit， 支持异步与取消令牌、多收件人、抄送与密送、多附件、显式加密策略与超时控制。 原 SendEmail（SmtpClient）保持不变，现有代码无需迁移。
• 安全：SecurityHelper.HashPassword 文档声明为 PBKDF2-HMAC-SHA256， 但此前调用 Rfc2898DeriveBytes 三参数重载，实际使用的是 SHA1。 现改为自行实现 PBKDF2-HMAC-SHA256（已通过标准测试向量与 .NET 内置实现交叉验证）。 之所以不直接用带 HashAlgorithmName 的重载，是因为该重载在 net451/net46 上不存在， 按框架分档调用会导致同一口令在不同框架下哈希不同、换框架后存量口令全部校验失败。 哈希串格式相应升级为 版本.迭代次数.盐.哈希，旧的 3 段格式仍可校验通过。

更新日志

3.3.1 (2026-10-17)

• 修复：HttpHelper.SetCer 不再自动关闭 HTTPS 证书校验（进程级），仅显式 SkipCertificateValidation(true) 时跳过校验。
• 修复：Core 分支 WebHelper.GetUserAgent / UserAgent() 读取头名笔误 HeaderUserAgent，恢复为 User-Agent；LogHelper.PrepareLogWriteParameter 判空条件写反（为空时回退 Request URL）；PrepareLogInfo 在 logParms == null 时空引用。
• 修复：ConvertHelper.FormatTime 无 - 分支 AppendFormat("{0}") 必抛 FormatException，重写为按 4/6/8 位数字分段拼接；To* 系列 o == null 时返回 _default；ToDateTimeNull 解析失败返回 null；ToDataTable<T> 支持 Nullable<T> 列；DataTableConvertToJson 改用 Newtonsoft 序列化（补齐转义）；CompareList 多重集比较错误；CutDecimalWithN 与 Extension.Struct 系列改用 InvariantCulture 并消除 (decimal)(int) 溢出；ToSortedObjectDictionary 类型判断笔误；EntityParametersAssignment 三重载抽取 CopyProperties 核心并以 Nullable.GetUnderlyingType 解析可空类型（修复非 mscorlib 类型 NRE）。
• 修复：BarCodeHelper Code128 码表第 76 项 Code128B 值 "I" 更正为 "l"；RandomHelper.GetOneNumber 永不生成 '0'；GuidTo16String 溢出且长度不固定（改为 Guid 前 8 字节 hex）；GetObjectByWeight 重写为标准加权随机（Weight<=0 不参与）；RandomProbability 死循环/重复 key/越界；GetRandomNation 硬编码数量。
• 修复：AttributeHelper/ReflectionHelper（过滤条件写反、缓存键冲突与污染、BadImageFormatException、多处判空）/ExpressionHelper.GetName 不处理装箱 UnaryExpression/CacheHelper 值类型命中误判与 GetOrAdd 非原子、Clear 遍历中删除/CertHelper 证书库未关闭与校验漏 return/IOHelper MIME 校验笔误、扩展名正则、gzip ISIZE OOM、上传短读与边界、magic 比较歧义、GC.Collect/ImageHelper.ToImage 关流后 GDI+ 错误、验证码 GDI 泄漏/CompressHelper.UnZip Zip Slip 防护/EmailHelper 集合判空与域名后缀匹配/Extension.Number.ToString(decimals) 格式串长度/Extension.IEnumerable.AnyData 等问题。
• 修复：ApiHelper 时间戳校验改为双向时间窗、同 key 覆盖不再抛异常；验签比较改为定长时间比较。说明：GetResponseMysign 的 MD5 签名算法仅保留兼容用途，新系统请改用更强的摘要算法。
• 优化：RandomHelper 线程安全随机源（[ThreadStatic]）；HttpHelper.Post_MultimediaHttpClientAsync 复用共享 HttpClient 并改为真异步；LogHelper.EndWrireLog 吞异常改为写入 Trace；StringHelper 静态构造注册 CodePagesEncodingProvider（netcore 下 GB2312 拼音可用，netcoreapp3.1 补引 System.Text.Encoding.CodePages）。

V3.3.*

• [3.3.0] 安全加固与缺陷修复
  1. HtmlHelper.EnsureOnlyAllowedHtml 重写为属性级白名单过滤，防 XSS 注入；FormatText 异常改为记日志；
  2. BBCodeHelper 链接/图片地址经 HtmlHelper.GetSafeUrl 校验，拒绝 javascript: 等伪协议；引用作者名 HTML 编码；
  3. XmlHelper 全部 XmlDocument 禁用 XmlResolver 并在反序列化入口拒绝 DTD（防 XXE）；
  4. HttpHelper.SetHttpsRequest 不再默认关闭证书校验，改为显式 SkipCertificateValidation() 开启；TLS 默认加入 Tls13（net8）；
  5. 验证码与 GenerateCheckCode 改用密码学随机数（新增 RandomHelper.GetSecureRandomValue）；DES_Generator 密钥改用 CSPRNG 生成；
  6. SecurityHelper：AES 非 ECB 模式强制校验 16 字节 IV（缺省即抛 ArgumentException，杜绝随机 IV 解密失败）；VerifyPassword 增加 PBKDF2 迭代次数上限防 DoS；EncodeBase64 移除静默降级 catch；
  7. AES-GCM 跨框架：netcoreapp3.1 启用原生实现，net451/net46/net48 新增 BouncyCastle 实现，密文跨框架互通（已验证 net48↔net8 回环）；
  8. Cookie（CookieHelper/CookieServices）补 HttpOnly/Secure/SameSite=Lax；修复 Core 分支 isEncrypt 参数被丢弃的 bug；
  9. WebHelper.GetIP 改用 X-Forwarded-For/X-Real-IP 头并修复 REMOTE_ADDR 误用；新增 NormalizeClientIp 规范化 IPv4-mapped 地址；
  10. HttpClient 迁移（SYSLIB0014）：EncodingHelper.GetEncodingName(Uri)、IOHelper.GetRemoteFileLength、WebHelper.BuildStaticPage 改用 HttpClientHelper，消除 .NET 6+ 过时警告（非 2xx 异常类型由 WebException 变为 HttpRequestException）；
  11. 修复：ConvertHelper.ToUInt16(object) 返回类型 int→UInt16；ToFileSizeText 单位索引越界；DateTimeHelper.ToUnixTimeSeconds net451 返回类型 int→long、GetTimeRankOfTheWeek 周日归属错误；Snowflake 负 machineId 改为抛 ArgumentOutOfRangeException（原静默置 0 会产生重复 ID）； CompressHelper.ZipSingleFile/ZipDirectory 误把文件路径当目录创建；
  12. 资源与稳健性：IOHelper.ValidateFileBinaryCode 不再关闭调用方传入的流（leaveOpen）；EncodingHelper.GetEncodingName(Uri) 响应释放改为 using； HttpHelper.PostAsync/Post_WebClientAsync 修复回调泄漏与未处理异常；IOHelper.GetSizeName 复用 ConvertHelper.ToFileSizeText（输出格式统一为 1.00KB）；
  13. 弱算法（DES/默认 ECB 模式/MD5 签名/HmacSHA1）仅补文档警示，密钥派生与默认行为保持兼容，存量数据可正常解密。

V3.2.*

• [3.2.2] �޸� ThreadingHelper.RunMutex��
  1. ���� lockTaken ������δ����������ʱ���ٵ��� ReleaseMutex������ ApplicationException����
  2. ǰ�γ����߳�/���̱�����AbandonedMutexException��ʱ��ȷ���ѻ���������ִ�� Action�����������ϱ��β�����
  3. �쳣ֱ�Ӵ��������پ� throw ception ���׵���ԭʼ��ջ��ʧ���Ƴ��˽������ӳ����׵��ظ� catch��

V3.1.*

• [3.1.1] 新增基于 MailKit 的邮件发送（异步 / 取消令牌 / 抄送密送 / 多附件）； 修正 HashPassword 实际使用 SHA1 与文档不符的问题，改为全平台一致的 PBKDF2-HMAC-SHA256； 修复 EncodingHelper.cs 中 1335 处中文注释乱码（2026-08-30 提交误将 GBK 按 UTF-8 转码所致）。
• [3.1.0] 修复 ConfigHelper 跨版本崩溃链与多项缺陷；新增 JsonHelper / CacheHelper / CompressHelper / RegexHelper / IpHelper / HttpClientHelper；补充异步 API 与 CancellationToken； 新增 PBKDF2 与 AES-GCM；补全 README。

V3.0.*

• [3.0.0] 支持 .NET 8.0