XYS.Utils.Sys 2.6.0

XYS.Utils.Sys

系统级通用工具类库：HTTP/JSON 调用、文件、类型转换、反射、XML、邮件、CSV 导出、数据库映射辅助与配置读取等。

目标框架

net8.0 · net462 · netcoreapp3.1 · netstandard2.0 · netstandard2.1

依赖

• Newtonsoft.Json 13.0.4
• Microsoft.CSharp 4.7.0
• XYS（同解决方案内项目引用）

HttpJsonUtil

基于 HttpClient 的 JSON 请求工具，提供 POST / GET 并自动反序列化响应，支持 HTTPS。

using XYS.Utils.Sys;

// POST：对象自动序列化为 JSON，反序列化为指定类型
var res = HttpJsonUtil.Post<ResultDto>("https://api.example.com/order", new { id = 1 }, timeout: 5000);

// GET
var dto = HttpJsonUtil.Get<ResultDto>("https://api.example.com/order/1");

// 带 Cookie / 自定义 UserAgent
var res2 = HttpJsonUtil.Post("https://api.example.com/x", req, timeout: 3000, userAgent: "MyApp", cookies: myCookies);

// 自定义请求头：全局默认头（启动时注入一次）
HttpJsonUtil.DefaultHeaderProvider = () => new Dictionary<string, string>
{
    ["X-Api-Key"] = "your-api-key",
};
// 或单次请求头（同名覆盖全局默认头），POST/GET 均支持
var res3 = HttpJsonUtil.Post<ResultDto>("https://api.example.com/x", req,
    headers: new Dictionary<string, string> { ["X-Request-Id"] = Guid.NewGuid().ToString() });

// 表单提交（multipart/form-data）：服务端以表单字段接收，字段值本身可为 JSON 字符串
var res4 = HttpJsonUtil.PostForm<ResultDto>("https://api.example.com/gateway",
    new Dictionary<string, string>
    {
        ["interfaceName"] = "doctor",
        ["methodName"]    = "getPatientEmrContentById",
        ["data"]          = "{\"recordId\":\"xxx\",\"contentType\":\"html\"}",
    });
// 需要原始响应字符串时用同名非泛型重载：HttpJsonUtil.PostForm(url, fields)

• HTTPS：静态构造时自动启用 TLS 1.2/1.1（兼容 net462 等旧框架访问现代 HTTPS 服务；.NET Core/5+ 由系统协商，无副作用）。
• 证书校验：HttpJsonUtil.AllowUntrustedCertificate 默认 true，放行自签名/内网证书；生产环境建议置为 false 以启用标准 TLS 校验，防止中间人攻击。
• 自定义请求头：全局 DefaultHeaderProvider + 各方法末尾的 headers 参数，内部 AddOrUpdateHeader 同名覆盖；Key 空或 Value 为 null 的项自动跳过。
• 表单提交：PostForm<T> / PostForm（原始字符串重载）以 multipart/form-data 提交字段，适配「服务端以表单字段接收、字段值为 JSON 字符串」的统一网关类接口；字段 UTF-8 编码，Value 为 null 时按空串提交。
• 错误诊断：请求失败时异常携带状态码与响应体；超时抛出语义明确的 TimeoutException（含 URL 与毫秒数）。
• timeout 单位毫秒。无 Cookie 时复用静态 HttpClient；带 Cookie 时创建独立实例并自动释放。

需要按 baseUrl 复用客户端、请求级超时隔离与 Token 注入的高并发场景，参见 XYS.Utils.Web 中的 HttpRestUtil。

TypeExtension

常用类型扩展方法。

using XYS.Utils.Sys;

string json = anyObject.ToJson();                 // 序列化为 JSON
int? n = "123".ToInt();                            // 安全转 int?
DateTime? d = "2026-07-21".ToDateTime();           // 安全转 DateTime?
string xml = raw.ToXmlStr();                        // XML 特殊字符转义

ToJson / ToInt / ToFloat / ToDouble / ToDecimal / ToDateTime / ToSmallDateTime / ToXmlStr 等，均对 null/非法输入做安全处理。

FileUtil

文件与目录辅助：

• File2Bytes(fullFileName) — 读取文件为字节数组
• GetFullName(params paths) — 拼接路径
• MakeDir(filePath) — 创建目录
• IsFileExist / IsDictExist / DeleteFile / DeleteDict

ConvertUtil

安全类型转换：TryParse 的 int / long / short 重载，转换失败返回 false 且不抛异常。

ReflexUtil

反射辅助：AssemblyShortName / AssemblyFileName / GetTypeFromString（按类型名解析 Type）。

XmlUtil

XML 辅助：

• Serialize<T>(obj) / DeSerialize<T>(xml) — 对象与 XML 字符串互转（序列化输出紧凑、抑制 xsi/xsd 命名空间声明）
• GetData<T>(XmlNode) — 按属性名映射 XML 子节点到实体
• TypeConvert(input, type) 按目标类型转换字符串，DefaultForType(type) 返回类型默认值

MailHelper

邮件发送：MailHelper.SendMail(MailRequest request)，MailRequest 支持正文、收件人及 MailRequestAttachments 附件。成功返回空字符串，失败返回错误信息。

SMTP 参数从 xys.config.json 的 appSettings 读取：

• smtpServer / smtpServerPort — 服务器地址与端口
• mailUser / mailUserPW — 认证账号密码（留空则用默认网络凭据）
• defaultMailFrom — 默认发件人（MailRequest.From 为空时使用）
• smtpEnableSsl — 设为 true 时启用 SSL/TLS（适配 587/465 加密端口，net462 等旧框架自动启用 TLS 1.2）

ExportHelper

CSV 导出：ExportCVS(fileName, rows, csvSeparator = ',', coding = null)，rows 为 List<List<string>>。

SystemInfo

配置读取与系统辅助（配置文件 xys.config.json，读取后缓存）：

• GetAppSetting(key) / GetConfigValue(key) — 读取配置项
• GetConnString(name) / GetConnStruct(name) — 读取数据库连接串
• ReloadConfig() — 重新加载配置
• 另含 GUID、日期格式化、路径、类型判断等杂项工具。

DB（数据库映射辅助）

配合 DBColAttribute + 反射实现实体与数据行/存储过程参数的映射：

• DBUtil.Convert / DeConvert — 实体与数据源对象互转
• DBHelper — 存储过程入/出参装配、DB 值与类型解析
• DBParse — 安全取值（GetSafeInt / GetSafeDate / GetSafeDecimal / GetSafeStr 等）
• NConvert — 数值/日期/布尔转换，含金额转大写 ToCapital
• SqlUtil.GetWhere(paramDict, tableAlias) — 由字典拼接 WHERE 条件

配置加密：Crypto（2.6.0）

保护 xys.config.json 中的敏感值（如数据库连接串），避免明文密码泄露。

• 算法：AES-256-CBC + HMAC-SHA256（Encrypt-then-MAC），全 5 个目标框架原生，无第三方依赖。
• 密钥优先级：Crypto.SetKey(...) > 环境变量 XYS_CRYPTO_KEY > 内置默认密钥。

加密连接串并写回配置

用测试工程内的便捷工具生成密文（PowerShell）：

$env:XYS_ENC_INPUT = 'Server=db;User Id=app;Password=真实密码;'
# 若使用自有密钥，同时设置：$env:XYS_CRYPTO_KEY = '你的密钥'
dotnet test XYS.Utils.Sys.Tests --filter FullyQualifiedName~ConnStrEncryptTool

把输出的 ENC(...) 整行贴回配置：

{
  "connectionStrings": {
    "his": {
      "connectionString": "ENC(base64....)",
      "providerName": "Microsoft.Data.SqlClient"
    }
  }
}

SystemInfo.GetConnStruct("his") 会自动解密；不带 ENC(...) 的明文原样返回，现有配置无需改动即可继续运行。DataFactory / 其他经 GetConnStruct 的消费方无需改代码即受益。

密钥与安全说明

• 内置默认密钥为混淆级：持有程序集者可反出并解密。它挡的是"看到配置即泄露"（误提交 git、运维翻配置、备份/截图），不是已取得服务器全部文件的攻击者。
• 强防护：在应用启动时 Crypto.SetKey("站点专属密钥")，或设置环境变量 XYS_CRYPTO_KEY（密钥不入程序集、不入源码）。宿主亦可将 DPAPI/KMS 作为密钥源接入 SetKey。
• 更换密钥后，旧密钥加密的 ENC(...) 需用新密钥重新生成。

版本

当前版本 2.6.0。