Liwendong.Utility 3.2.0

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 仅 .NET 5+：SecurityHelper.AesGcmEncrypt/AesGcmDecrypt 在 net451/net46/netcoreapp3.1 下不参与编译。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 段格式仍可校验通过。

更新日志

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