Hi.Ltd 2026.6.10.1407

Hi.Ltd 类库使用说明

本类库是海蓝智能科技有限公司的基础类库，主要用于提供日志信息、结果类、公共数据定义、通用静态方法等功能。
本类库仅供参考使用，不保证方法的有效性，请谨慎使用！

目录

• 简介
• 安装
• 快速开始
• 核心功能
  • 日志记录 (Logging)
  • 结果类 (Result)
  • 工具类 (Utilities)
  • 安全加密 (Security)
  • HTTP 请求 (Https)
  • 文件操作 (IO)
  • 线程管理 (Threading)
  • 插件管理 (Managements)
  • 应用程序 (App)
  • 互操作 (Interop)
• 完整 API 参考
  • 日志记录 (Logging) API
  • 结果类 (Result) API
  • 工具类 (Utilities) API
    • 第一部分：数值类型扩展方法
    • 第一部分（续）：数值类型扩展方法
    • 第二部分：字符串扩展方法
    • 第三部分：其他类型扩展方法
    • 第三部分（续）：其他类型扩展方法
  • 安全加密 (Security) API
  • HTTP 请求 (Https) API
  • 文件操作 (IO) API
  • 线程管理 (Threading) API
  • 插件管理 (Managements) API
  • 应用程序 (App) API
  • 互操作 (Interop) API
• 版本信息
• 更新日志
• 源码与 Git 约定（master）

简介

Hi.Ltd 是一个功能丰富的 C# 基础类库，提供了大量实用的工具方法和扩展功能，帮助开发者快速构建应用程序。本类库支持 .NET Framework 4.6.2 及以上版本。

主要特性

• ✅ 完善的日志记录系统
• ✅ 统一的结果处理机制
• ✅ 丰富的类型转换扩展方法
• ✅ 多种加密算法支持（含国密 SM2 签名、SM3 摘要、HMAC-SM3、SM4 及 SM4+HMAC-SM3 认证封装等）
• ✅ HTTP 请求封装
• ✅ 文件操作工具
• ✅ 线程安全工具
• ✅ 插件管理系统
• ✅ JSON 序列化与反序列化
• ✅ INI 文件操作
• ✅ XML 文件操作
• ✅ Windows 注册表操作
• ✅ 扫码功能支持

安装

NuGet 包管理器

Install-Package Hi.Ltd

.NET CLI

dotnet add package Hi.Ltd

PackageReference

<PackageReference Include="Hi.Ltd" Version="2025.7.7.1141" />

快速开始

基本使用

using Hi.Ltd;

// 使用日志记录
"这是一条日志信息".Log();

// 使用结果类
var result = SomeMethod();
if (result.Successed)
{
    // 处理成功情况
}
else
{
    // 处理失败情况
    Console.WriteLine(result.Message);
}

核心功能

日志记录 (Logging)

Logging 类提供了简单易用的日志记录功能，支持多种日志级别和文件存储。

基本用法

using Hi.Ltd;

// 记录普通日志
"这是一条日志信息".Log();

// 记录不同级别的日志
"调试信息".Debug();
"信息提示".Info();
"警告信息".Warn();
"错误信息".Error();

// 记录异常
try
{
    // 业务代码
}
catch (Exception ex)
{
    ex.Log();  // 记录异常
    "操作失败".Error(ex);  // 记录错误和异常
}

配置日志路径

// 设置日志存储路径（默认为应用程序目录下的 Logging 文件夹）
Logging.Path = @"C:\MyApp\Logs";

// 设置日志文件最大存储数量（默认 128）
Logging.TotalMaxSize = 200;

// 设置日志保留天数（默认 30 天）
Logging.RetainedDays = 60;

日志级别说明

• Log: 普通日志，记录到文件
• Debug: 调试信息，输出到控制台
• Info: 信息提示，记录到文件
• Warn: 警告信息，记录到文件
• Error: 错误信息，记录到文件

日志文件管理

• 日志文件按日期命名：yyyy-MM-dd.log
• 单个日志文件超过 10MB 时自动备份
• 支持自动清理过期日志文件
• 支持限制日志文件总数

结果类 (Result)

Result 类用于统一处理方法的执行结果，支持成功/失败状态、错误信息和链式操作。

基本用法

using Hi.Ltd;

// 检查结果是否成功
var result = SomeMethod();
if (result.Successed)
{
    // 处理成功
}
else
{
    // 处理失败
    Console.WriteLine(result.Message);
}

// 使用链式操作
SomeMethod()
    .Then(() => AnotherMethod())
    .Then(() => FinalMethod());

泛型结果类

// 返回单个值的结果
Result<int> GetNumber()
{
    return 42;  // 成功返回
    // 或
    return Error.Empty("value", "值不能为空");
}

// 使用结果值
var result = GetNumber();
if (result.Successed)
{
    int value = result;  // 隐式转换获取值
}

链式操作

// Then: 当前操作成功时继续执行下一步
result
    .Then(() => Step1())
    .Then(() => Step2())
    .Then(() => Step3());

// Match: 根据成功/失败执行不同分支
result.Match(
    success: () => HandleSuccess(),
    failure: () => HandleFailure()
);

工具类 (Utilities)

Utilities 类提供了大量扩展方法，简化常见的数据类型转换和操作。

类型转换

using Hi.Ltd;

// 字符串转数字
var intValue = "123".ToInt32();
var doubleValue = "3.14".ToDouble();

// 数字转字符串
var str = 123.ToString();

// 字节数组转换
byte[] bytes = { 0x01, 0x02, 0x03, 0x04 };
var intValue = bytes.GetInt32(0);
var doubleValue = bytes.GetDouble(0);

// 角度弧度转换
double radians = 90.0.ToRadian();  // 角度转弧度
double degrees = Math.PI.ToDegree();  // 弧度转角度

数值限制

// 限制数值范围
double value = 150.0;
double clamped = value.Clamp(0, 100);  // 返回 100

字符串操作

// 检查字符串是否为空
if (str.IsNullOrEmpty())
{
    // 处理空字符串
}

// Base64 编码/解码
string encoded = "Hello".ToBase64();
string decoded = encoded.FromBase64();

安全加密 (Security)

提供了多种加密算法的工具类，包括 AES、RSA、ECC、DES、MD5、SHA256、HMAC，以及国密 SM2 数字签名（GB/T 32918.2）、SM3 杂凑（GB/T 32905）、HMAC-SM3、SM4 分组密码（GB/T 32907，含与 HMAC-SM3 的 Encrypt-then-MAC 封装）。上述国密算法均在 Hi.Ltd.Security 下提供纯托管工具类。

AES 加密

using Hi.Ltd;

// 生成密钥和 IV
var keyIv = AesUtils.GenAesKeyAndIV();
byte[] key = keyIv.Item1;
byte[] iv = keyIv.Item2;

// 加密
byte[] plaintext = Encoding.UTF8.GetBytes("Hello World");
var encrypted = AesUtils.Encrypt(plaintext, key, iv);

// 解密
var decrypted = AesUtils.Decrypt(encrypted, key, iv);
string result = Encoding.UTF8.GetString(decrypted);

RSA 加密

// 生成密钥对
var keyPair = RsaUtils.GenKeyPair();
RSAKeyValue publicKey = keyPair.Item1;
RSAKeyValue privateKey = keyPair.Item2;

// 加密
byte[] data = Encoding.UTF8.GetBytes("Hello World");
var encrypted = RsaUtils.Encrypt(data, publicKey);

// 解密
var decrypted = RsaUtils.Decrypt(encrypted, privateKey);

哈希算法

// MD5 哈希
string md5 = Md5Utils.ComputeHash("Hello World");

// SHA256 哈希
string sha256 = Sha256Utils.ComputeHash("Hello World");

// HMAC
string hmac = HMACUtils.ComputeHMAC("Hello World", "secret-key");

国密 SM3 与 HMAC-SM3

using System.Text;
using Hi.Ltd.Security;

byte[] data = Encoding.UTF8.GetBytes("abc");
// 32 字节摘要；ToHexString 为小写十六进制（与仓库回归向量一致时可对照 OpenSSL sm3）
string digestHex = SM3Utils.ToHexString(SM3Utils.ComputeHash(data));

byte[] macKey = Encoding.UTF8.GetBytes("hmac-sm3-key-32bytes-or-longer!!");
byte[] tag = HmacSm3Utils.ComputeHash(macKey, data); // 32 字节，常作 EtM 中的 MAC

国密 SM2 数字签名

using System.Text;
using Hi.Ltd.Security;

// 32 字节大端私钥 d，须落在曲线阶 (0, n) 内；此处与单元回归用例相同，仅演示 API
byte[] d = new byte[32];
d[30] = 0xA1;
d[31] = 0x3B;
byte[] userId = Encoding.UTF8.GetBytes("interop-user"); // 或 null / 空字节，表示采用 DefaultUserIdAscii
byte[] message = Encoding.UTF8.GetBytes("sm2 roundtrip message");

byte[] signature = SM2Utils.Sign(d, userId, message); // 64 字节 r‖s
byte[] publicKey = SM2Utils.GetPublicKey(d);         // 64 字节 X‖Y
bool ok = SM2Utils.Verify(publicKey, userId, message, signature);

// 与常见协议/OpenSSL DER 互操作：原始签名 ↔ DER
byte[] der = SM2Utils.SignatureToDer(signature);
byte[] raw = SM2Utils.SignatureFromDer(der);

国密 SM4

using System.Security.Cryptography;
using System.Text;
using Hi.Ltd.Security;

// 16 字节 SM4 密钥（生产环境应由 KMS/安全存储注入，勿硬编码）
byte[] sm4Key = new byte[SM4Utils.KeySize];
RandomNumberGenerator.Fill(sm4Key);

byte[] plain = Encoding.UTF8.GetBytes("Hello 国密 SM4");

// 推荐：随机 IV + CBC（输出为 IV(16) ‖ 密文）
byte[] payload = SM4Utils.EncryptCbcWithRandomIv(sm4Key, plain);
byte[] recovered = SM4Utils.DecryptCbcWithPrefixedIv(sm4Key, payload);

// 网络/存储场景：Encrypt-then-MAC（IV ‖ 密文 ‖ HMAC-SM3），先验 MAC 再解密
byte[] macKey = Encoding.UTF8.GetBytes("independent-mac-key-32bytes-min!!");
byte[] authed = SM4Utils.EncryptCbcWithRandomIvAndHmacSm3(sm4Key, macKey, plain);
byte[] opened = SM4Utils.DecryptCbcWithPrefixedIvAndHmacSm3(sm4Key, macKey, authed);

HTTP 请求 (Https)

提供了 HTTP 请求的封装类，简化 HTTP 操作。

基本用法

using Hi.Ltd.Https;

// GET 请求
var httpClient = new HttpClientUtils();
var result = await httpClient.GetAsync("https://api.example.com/data");

// POST 请求
var data = new { name = "test", value = 123 };
var postResult = await httpClient.PostAsync("https://api.example.com/data", data);

文件操作 (IO)

提供了文件和磁盘操作的实用工具。

文件操作

using Hi.Ltd.IO;

// 检查文件是否正在使用
bool inUse = @"C:\file.txt".InUse();

// 删除文件
var result = FileUtils.Delete(@"C:\file.txt");

// 磁盘操作
var diskInfo = DiskUtils.GetDiskInfo(@"C:\");

线程管理 (Threading)

提供了线程安全的工具类。

LRU 缓存

using Hi.Ltd.Threading;

// 创建 LRU 缓存
var cache = new LRUCache<string, object>(capacity: 100);

// 添加和获取
cache.Add("key1", value1);
var value = cache.Get("key1");

混合锁

using Hi.Ltd.Threading;

var hybridLock = new HybridLocked<int>();

// 线程安全操作
hybridLock.Execute(value =>
{
    // 操作 value
    return value + 1;
});

插件管理 (Managements)

提供了插件系统的管理功能。

插件接口

using Hi.Ltd.Interface;

public class MyPlugin : IPlugin
{
    public string Name => "MyPlugin";
    public string Description => "我的插件";
    
    public bool Init(params object[] args)
    {
        // 初始化插件
        return true;
    }
    
    public object Execute(params object[] args)
    {
        // 执行插件逻辑
        return null;
    }
    
    public object InvokeMethod(string methodName, params object[] args)
    {
        // 通过反射调用方法
        return null;
    }
}

插件管理

using Hi.Ltd.Managements;

// 注册插件
PluginManager.Register<MyPlugin>();

// 获取插件
var plugin = PluginManager.Get<MyPlugin>();

应用程序 (App)

提供了应用程序相关的功能。

单例模式

using Hi.Ltd;

var app = new App();
var isSingleton = app.IsSingleton();
if (!isSingleton)
{
    // 应用程序已在运行
    Environment.Exit(0);
}

管理员权限

// 检查是否以管理员权限运行
var isAdmin = app.IsRunAsAdmin();

// 以管理员权限重新启动
if (!isAdmin)
{
    app.RunAsAdmin();
}

性能监控

#if NET40_OR_GREATER
// 获取 CPU 使用率
var cpuUsage = app.GetCpuUsage();

// 获取可用内存
var ramAvailable = app.GetRamAvailable();

// 获取磁盘使用率
var diskUsage = app.GetDiskUsage();

// 获取网络使用量
var networkUsage = app.GetNetworkUsage();

// 获取 GPU 使用率
var gpuUsage = app.GetGpuUsage();
#endif

互操作 (Interop)

提供了与系统和其他组件交互的功能。

JSON 序列化

using Hi.Ltd.Interop;

// 序列化对象
var obj = new { Name = "Test", Value = 123 };
var json = JsonSerializer.Serialize(obj);

// 反序列化
var deserialized = JsonSerializer.Deserialize<MyClass>(json);

INI 文件操作

using Hi.Ltd.Interop;

// 序列化对象到 INI 文件
var connect = new Connect { Id = "ABS", Description = "测试" };
var result = IniHelper.Create.Serialize(@"D:\HiTest.Ini", connect);

// 从 INI 文件反序列化
var deserialized = IniHelper.Create.Deserialize<Connect>(@"D:\HiTest.Ini");

注册表操作

using Hi.Ltd.Interop;

// 使用注册表
var registry = RegistryHelper.Create;
registry.Root = HKey.CURRENT_USER;
registry.Name = @"Software\MyApp";
registry.Key = "Setting";
registry.SetValue("Value1");

// 读取值
var value = registry.GetValue();

扫码功能

using Hi.Ltd.Interop;

// 创建扫码器
var scanner = ScannerUtils.Create;
scanner.OnScannerCode += (code) => {
    Console.WriteLine($"扫码内容: {code}");
};

// 启动扫码
scanner.Start();

XML 文件操作

using Hi.Ltd.Interop;

// 序列化对象到 XML 文件
var connect = new Connect { Id = "ABS", Description = "测试" };
var result = XmlUtils.Instance.Serialize(@"D:\HiTest.xml", connect);

// 从 XML 文件反序列化
var deserialized = XmlUtils.Instance.Deserialize<Connect>(@"D:\HiTest.xml");
if (deserialized.Successed)
{
    Console.WriteLine(deserialized.Content.Id);
}

完整 API 参考

以下内容详细说明 Hi.Ltd 类库中所有 API 的方法、参数、返回值和使用示例。

日志记录 (Logging) API

Logging 类

类说明

Logging 类提供了简单易用的日志记录功能，支持多种日志级别和文件存储。日志记录是线程安全的。

静态属性

Path

public static string Path { get; set; }

功能说明: 获取或设置日志存储路径。

返回值: 日志存储路径字符串

默认值: 应用程序目录下的 Logging 文件夹

异常: 无

使用示例:

Logging.Path = @"C:\MyApp\Logs";

---

TotalMaxSize

public static int TotalMaxSize { get; set; }

功能说明: 获取或设置日志文件最大存储数量。

返回值: 最大文件数量

默认值: 128

异常: 无

使用示例:

Logging.TotalMaxSize = 200;

---

RetainedDays

public static int RetainedDays { get; set; }

功能说明: 获取或设置日志保留天数。

返回值: 保留天数

默认值: 30

异常: 无

使用示例:

Logging.RetainedDays = 60;

---

扩展方法

Log (普通日志)

public static void Log(this string message)

功能说明: 记录普通日志信息到文件。

参数:

• message: 要记录的日志消息

返回值: 无

异常:

• 可能抛出 IOException 当文件写入失败时
• 可能抛出 UnauthorizedAccessException 当没有写入权限时

使用示例:

"这是一条日志信息".Log();

---

public static void Log(this Exception exception)

功能说明: 记录异常信息到文件。

参数:

• exception: 要记录的异常对象

返回值: 无

异常:

• 可能抛出 IOException 当文件写入失败时
• 可能抛出 UnauthorizedAccessException 当没有写入权限时

使用示例:

try
{
    // 业务代码
}
catch (Exception ex)
{
    ex.Log();  // 记录异常
}

---

public static void Log(this string message, Exception exception)

功能说明: 记录日志信息和异常到文件。

参数:

• message: 要记录的日志消息
• exception: 要记录的异常对象

返回值: 无

异常:

• 可能抛出 IOException 当文件写入失败时
• 可能抛出 UnauthorizedAccessException 当没有写入权限时

使用示例:

"操作失败".Log(exception);

---

Debug (调试日志)

public static void Debug(this string message)

功能说明: 记录调试信息到控制台。

参数:

• message: 要记录的调试消息

返回值: 无

异常: 无

使用示例:

"调试信息".Debug();

---

public static void Debug(this Exception exception)

功能说明: 记录异常信息到控制台（调试模式）。

参数:

• exception: 要记录的异常对象

返回值: 无

异常: 无

使用示例:

exception.Debug();

---

public static void Debug(this string message, Exception exception)

功能说明: 记录调试信息和异常到控制台。

参数:

• message: 要记录的调试消息
• exception: 要记录的异常对象

返回值: 无

异常: 无

使用示例:

"调试信息".Debug(exception);

---

Info (信息日志)

public static void Info(this string message)

功能说明: 记录信息提示到文件。

参数:

• message: 要记录的信息消息

返回值: 无

异常:

• 可能抛出 IOException 当文件写入失败时
• 可能抛出 UnauthorizedAccessException 当没有写入权限时

使用示例:

"信息提示".Info();

---

public static void Info(this Exception exception)

功能说明: 记录异常信息到文件（信息级别）。

参数:

• exception: 要记录的异常对象

返回值: 无

异常:

• 可能抛出 IOException 当文件写入失败时
• 可能抛出 UnauthorizedAccessException 当没有写入权限时

使用示例:

exception.Info();

---

public static void Info(this string message, Exception exception)

功能说明: 记录信息提示和异常到文件。

参数:

• message: 要记录的信息消息
• exception: 要记录的异常对象

返回值: 无

异常:

• 可能抛出 IOException 当文件写入失败时
• 可能抛出 UnauthorizedAccessException 当没有写入权限时

使用示例:

"信息提示".Info(exception);

---

Warn (警告日志)

public static void Warn(this string message)

功能说明: 记录警告信息到文件。

参数:

• message: 要记录的警告消息

返回值: 无

异常:

• 可能抛出 IOException 当文件写入失败时
• 可能抛出 UnauthorizedAccessException 当没有写入权限时

使用示例:

"警告信息".Warn();

---

public static void Warn(this Exception exception)

功能说明: 记录异常信息到文件（警告级别）。

参数:

• exception: 要记录的异常对象

返回值: 无

异常:

• 可能抛出 IOException 当文件写入失败时
• 可能抛出 UnauthorizedAccessException 当没有写入权限时

使用示例:

exception.Warn();

---

public static void Warn(this string message, Exception exception)

功能说明: 记录警告信息和异常到文件。

参数:

• message: 要记录的警告消息
• exception: 要记录的异常对象

返回值: 无

异常:

• 可能抛出 IOException 当文件写入失败时
• 可能抛出 UnauthorizedAccessException 当没有写入权限时

使用示例:

"警告信息".Warn(exception);

---

Error (错误日志)

public static void Error(this string message)

功能说明: 记录错误信息到文件。

参数:

• message: 要记录的错误消息

返回值: 无

异常:

• 可能抛出 IOException 当文件写入失败时
• 可能抛出 UnauthorizedAccessException 当没有写入权限时

使用示例:

"错误信息".Error();

---

public static void Error(this Exception exception)

功能说明: 记录异常信息到文件（错误级别）。

参数:

• exception: 要记录的异常对象

返回值: 无

异常:

• 可能抛出 IOException 当文件写入失败时
• 可能抛出 UnauthorizedAccessException 当没有写入权限时

使用示例:

exception.Error();

---

public static void Error(this string message, Exception exception)

功能说明: 记录错误信息和异常到文件。

参数:

• message: 要记录的错误消息
• exception: 要记录的异常对象

返回值: 无

异常:

• 可能抛出 IOException 当文件写入失败时
• 可能抛出 UnauthorizedAccessException 当没有写入权限时

使用示例:

"操作失败".Error(exception);

---

日志文件管理

文件命名规则

日志文件按日期命名，格式为：yyyy-MM-dd.log

例如：

• 2025-01-15.log
• 2025-01-16.log

文件大小限制

• 单个日志文件超过 10MB 时自动备份
• 备份文件命名格式：yyyy-MM-dd.log.bak

自动清理

• 根据 RetainedDays 设置自动清理过期日志文件
• 根据 TotalMaxSize 设置限制日志文件总数
• 清理操作在写入日志时自动执行

线程安全

所有日志记录操作都是线程安全的，可以在多线程环境中安全使用。

---

结果类 (Result) API

本文档详细说明 Hi.Ltd 类库中结果类 (Result) 和错误类 (Error) 的所有方法。

Result 类

类说明

Result 类用于统一处理方法的执行结果，支持成功/失败状态、错误信息和链式操作。实现了 IEquatable<Result> 接口。

特性:

• 统一的结果处理：所有方法返回 Result 或 Result<T> 类型
• 链式操作：支持 Then 和 Match 方法进行链式调用
• 错误追踪：通过 InnerResult 属性追踪错误链
• 自动调用信息：自动记录调用方法名和行号（.NET 4.5+）

静态属性

Success

public static readonly Result Success

功能说明: 表示操作成功的静态结果对象。

返回值: 一个成功的结果对象（Successed 为 true，Message 为 "成功"）

异常: 无

使用示例:

var result = Result.Success;
if (result.Successed)
{
    // 操作成功
}

---

属性

Successed

public bool Successed { get; }

功能说明: 获取操作是否成功。

返回值:

• true: 操作成功
• false: 操作失败

异常: 无

---

Message

public virtual string Message { get; }

功能说明: 获取结果消息。

返回值:

• 成功时: 默认返回 "成功"
• 失败时: 返回错误消息（如果消息为空，则返回异常消息或默认信息）

异常: 无

---

InnerResult

public virtual Result InnerResult { get; }

功能说明: 获取内部结果（用于链式错误追踪）。

返回值: 内部结果对象，可能为 null

异常: 无

使用示例:

var result = SomeMethod()
    .Then(() => Step1())
    .Then(() => Step2());

// 如果失败，可以通过 InnerResult 追踪错误链
if (!result.Successed)
{
    var inner = result.InnerResult;
    while (inner != null)
    {
        Console.WriteLine(inner.Message);
        inner = inner.InnerResult;
    }
}

---

方法

GetBaseResult

public virtual Result GetBaseResult()

功能说明: 获取最初结果内容（错误链的最底层结果）。

返回值: 返回错误链中最底层的 Result 对象

异常: 无

使用示例:

var result = SomeMethod()
    .Then(() => Step1())
    .Then(() => Step2());

// 获取最初的结果
var baseResult = result.GetBaseResult();

---

Collections

public virtual IEnumerable<Result> Collections()

功能说明: 获取所有层级的结果信息内容（遍历整个错误链）。

返回值: 返回所有层级的结果的集合（通过 InnerResult 链遍历）

异常: 无

使用示例:

var result = SomeMethod()
    .Then(() => Step1())
    .Then(() => Step2());

// 遍历所有层级的结果
foreach (var inner in result.Collections())
{
    Console.WriteLine(inner.Message);
}

---

ToString

public override string ToString()

功能说明: 返回结果的字符串表示。

返回值:

• 成功时: 返回 "成功"
• 失败时: 返回包含方法名、消息和行号的格式化字符串

异常: 无

使用示例:

var result = SomeMethod();
Console.WriteLine(result.ToString());  // 输出结果信息

---

Equals / GetHashCode

public virtual bool Equals(Result other)
public override bool Equals(object obj)
public override int GetHashCode()

功能说明: 比较两个 Result 对象是否相等。两个结果相等当且仅当它们的 Successed 和 Message 都相等。

参数:

• other: 要比较的另一个 Result 对象
• obj: 要比较的对象

返回值: 如果相等，返回 true；否则返回 false

异常: 无

使用示例:

var result1 = Result.Success;
var result2 = Result.Success;
var isEqual = result1.Equals(result2);  // 返回 true

---

Then

public virtual Result Then(Func<Result> func)
public virtual Result Then(Action action)

功能说明: 链式操作，当前对象如果成功，就返回接下来的操作方法对象执行的结果。

参数:

• func: 要执行的函数（返回 Result）
• action: 要执行的动作（无返回值）

返回值:

• 如果当前结果成功，返回 func 或 action 执行的结果
• 如果当前结果失败，返回当前结果（不执行后续操作）

异常: 无

使用示例:

var result = Step1()
    .Then(() => Step2())
    .Then(() => Step3());

// 如果 Step1 失败，Step2 和 Step3 都不会执行

---

public virtual Result<TResult> Then<TResult>(Func<Result<TResult>> func)
public virtual Result<TResult> Then<TResult>(Func<TResult> func)

功能说明: 泛型链式操作，支持返回不同类型的泛型结果。

类型参数:

• TResult: 返回结果的类型

参数:

• func: 要执行的函数（返回 Result<TResult> 或 TResult）

返回值:

• 如果当前结果成功，返回 func 执行的结果
• 如果当前结果失败，返回包含错误的 Result<TResult>

异常: 无

使用示例:

var result = Step1()
    .Then(() => Step2())  // 返回 Result<int>
    .Then(() => Step3());  // 返回 Result<string>

---

Match

public virtual TResult Match<TResult>(Func<Result, TResult> onSuccess, Func<Result, TResult> onFailure)
public virtual TResult Match<TResult>(Func<TResult> onSuccess, Func<Result, TResult> onFailure)

功能说明: 匹配操作，根据成功/失败执行不同的分支。

类型参数:

• TResult: 返回结果的类型

参数:

• onSuccess: 成功时执行的函数
• onFailure: 失败时执行的函数

返回值: 根据成功/失败返回对应的结果

异常: 无

使用示例:

var result = SomeMethod();
var value = result.Match(
    onSuccess: () => "成功",
    onFailure: (err) => $"失败: {err.Message}"
);

---

Result<T> 类

类说明

带泛型返回值的结果类，初始默认为正常结果。实现了 IEquatable<Result<T>> 和 IConvertible 接口。

特性:

• 泛型支持：可以返回任意类型的值
• 隐式转换：支持从 T 和 Error 隐式转换为 Result<T>
• 显式转换：支持从 Result<T> 显式转换为 T 或 Error
• 类型转换：实现了 IConvertible 接口，支持各种类型转换
• 数组支持：如果 T 是数组类型，可以通过索引器访问数组元素

构造函数

Result()

public Result()

功能说明: 创建一个成功的结果，内容为 default(T)。

异常: 无

使用示例:

var result = new Result<int>();  // 创建一个成功的结果，Content 为 0

---

Result(Result result)

public Result(Result result)

功能说明: 传入一个 Result 对象，将其作为内部结果。

参数:

• result: 要作为内部结果的 Result 对象

异常: 无

使用示例:

var baseResult = Error.Empty();
var result = new Result<int>(baseResult);  // 创建一个失败的结果

---

Result(T content)

public Result(T content)

功能说明: 传入内容值，创建一个成功的结果。

参数:

• content: 要包含的内容值

异常: 无

使用示例:

var result = new Result<int>(100);  // 创建一个成功的结果，Content 为 100

---

属性

Content

public T Content { get; }

功能说明: 获取泛型对象内容。

返回值:

• 成功时: 返回包含的值
• 失败时: 返回 default(T)

异常: 无

使用示例:

var result = new Result<int>(100);
var value = result.Content;  // 返回 100

---

this[int index]

public Result<TItem> this[int index] { get; }

功能说明: 获取数组对象里的成员内容值（仅当 T 是数组类型时可用）。

参数:

• index: 数组索引

返回值: 返回指定索引的元素（包装为 Result<TItem>）

异常:

• 当 T 不是数组类型时，返回 Error.Argument 错误
• 当 index 超出范围时，返回 Error.OutofRange 错误

使用示例:

var result = new Result<int[]>(new[] { 1, 2, 3, 4, 5 });
var item = result[2];  // 返回 Result<int>，Content 为 3

---

方法

ToString()

public override string ToString()

功能说明: 返回结果的字符串表示。

返回值:

• 成功时: 返回 Content 的字符串表示
• 失败时: 返回包含方法名、消息和行号的格式化字符串

异常: 无

使用示例:

var result = new Result<int>(100);
Console.WriteLine(result.ToString());  // 输出 "100"

---

Equals() / GetHashCode()

public virtual bool Equals(Result<T> other)
public override bool Equals(object obj)
public override int GetHashCode()

功能说明: 比较两个 Result<T> 对象是否相等。两个结果相等当且仅当它们的 Successed、Message 和 Content 都相等。

参数:

• other: 要比较的另一个 Result<T> 对象
• obj: 要比较的对象

返回值: 如果相等，返回 true；否则返回 false

异常: 无

使用示例:

var result1 = new Result<int>(100);
var result2 = new Result<int>(100);
var isEqual = result1.Equals(result2);  // 返回 true

---

Then

public virtual Result<TResult> Then<TResult>(Func<Result<T>, Result<TResult>> func)
public virtual Result<TResult> Then<TResult>(Func<T, Result<TResult>> func)
public virtual Result<TResult> Then<TResult>(Func<Result<T>, TResult> func)
public virtual Result<TResult> Then<TResult>(Func<T, TResult> func)
public virtual Result Then(Func<Result<T>, Result> func)
public virtual Result Then(Func<T, Result> func)
public virtual Result Then(Action<Result<T>> action)
public virtual Result Then(Action<T> action)

功能说明: 泛型链式操作，支持返回不同类型的泛型结果。

类型参数:

• TResult: 返回结果的类型

参数:

• func: 要执行的函数（支持多种重载）
• action: 要执行的动作（无返回值）

返回值:

• 如果当前结果成功，返回 func 或 action 执行的结果
• 如果当前结果失败，返回包含错误的 Result<TResult> 或 Result

异常: 无

使用示例:

var result = Step1()  // 返回 Result<int>
    .Then(x => Step2(x))  // 返回 Result<string>
    .Then(s => Step3(s));  // 返回 Result<bool>

---

Match

public virtual TResult Match<TResult>(Func<Result<T>, TResult> onSuccess, Func<Result<T>, TResult> onFailure)
public virtual TResult Match<TResult>(Func<T, TResult> onSuccess, Func<Result<T>, TResult> onFailure)

功能说明: 泛型匹配操作，支持返回不同类型的泛型结果。

类型参数:

• TResult: 返回结果的类型

参数:

• onSuccess: 成功时执行的函数
• onFailure: 失败时执行的函数

返回值: 根据成功/失败返回对应的结果

异常: 无

使用示例:

var result = SomeMethod();  // 返回 Result<int>
var value = result.Match(
    onSuccess: (x) => $"成功: {x}",
    onFailure: (err) => $"失败: {err.Message}"
);

---

IConvertible 接口实现

Result<T> 实现了 IConvertible 接口，支持各种类型转换方法：

public TypeCode GetTypeCode()
public bool ToBoolean(IFormatProvider provider)
public byte ToByte(IFormatProvider provider)
public char ToChar(IFormatProvider provider)
public DateTime ToDateTime(IFormatProvider provider)
public decimal ToDecimal(IFormatProvider provider)
public double ToDouble(IFormatProvider provider)
public short ToInt16(IFormatProvider provider)
public int ToInt32(IFormatProvider provider)
public long ToInt64(IFormatProvider provider)
public sbyte ToSByte(IFormatProvider provider)
public float ToSingle(IFormatProvider provider)
public string ToString(IFormatProvider provider)
public object ToType(Type conversionType, IFormatProvider provider)
public ushort ToUInt16(IFormatProvider provider)
public uint ToUInt32(IFormatProvider provider)
public ulong ToUInt64(IFormatProvider provider)

功能说明: 将 Result<T> 转换为指定的类型。如果 T 可以转换为目标类型，则进行转换；否则返回默认值或抛出异常。

参数:

• provider: 格式提供程序（可选）

返回值: 转换后的值

异常:

• 当转换失败时，可能抛出 InvalidCastException 或返回默认值

使用示例:

var result = new Result<int>(100);
var doubleValue = result.ToDouble();  // 返回 100.0
var stringValue = result.ToString();   // 返回 "100"

---

Error 类

类说明

提供错误信息类，继承自 Result 类。

静态方法

Empty()

public static Error Empty()

功能说明: 创建一个表示对象为空的错误信息类。

返回值: 一个 Error 对象，Successed 为 false，Message 为 "对象为空"

异常: 无

使用示例:

var error = Error.Empty();

---

OutofRange()

public static Error OutofRange()

功能说明: 创建一个表示对象超出界限的错误信息类。

返回值: 一个 Error 对象，Successed 为 false，Message 为 "对象超出界限"

异常: 无

使用示例:

var error = Error.OutofRange();

---

Format()

public static Error Format()

功能说明: 创建一个表示对象格式不正确的错误信息类。

返回值: 一个 Error 对象，Successed 为 false，Message 为 "对象格式不正确"

异常: 无

使用示例:

var error = Error.Format();

---

Argument()

public static Error Argument()

功能说明: 创建一个表示对象参数无效的错误信息类。

返回值: 一个 Error 对象，Successed 为 false，Message 为 "对象参数无效"

异常: 无

使用示例:

var error = Error.Argument();

---

Result()

public static Error Result(object content)

功能说明: 实例化一个错误结果类，并包含说明此错误的内容对象。

参数:

• content: 说明此错误的内容对象（通常是 Exception 对象）

返回值: 一个 Error 对象，包含错误内容

异常: 无

使用示例:

try
{
    // 某些操作
}
catch (Exception ex)
{
    var error = Error.Result(ex);
}

---

实例属性

ParamName

public string ParamName { get; }

功能说明: 获取参数名称。

返回值: 参数名称，可能为 null

异常: 无

---

MethodName

public string MethodName { get; }

功能说明: 获取方法名。

返回值: 方法名，可能为 null

异常: 无

---

LineNumber

public int LineNumber { get; }

功能说明: 获取错误所在的行数。

返回值: 行号，如果无法获取则返回 0

异常: 无

---

Exception

public Exception Exception { get; }

功能说明: 提供异常信息查询。

返回值: 异常对象，可能为 null

异常: 无

使用示例:

var error = Error.Result(new ArgumentException("参数无效"));
if (error.Exception != null)
{
    Console.WriteLine(error.Exception.Message);
}

---

隐式/显式转换

隐式转换:

• T 可以隐式转换为 Result<T>
• Error 可以隐式转换为 Result<T>

显式转换:

• Result<T> 可以显式转换为 T（成功时返回 Content，失败时返回 default(T)）
• string 可以显式转换为 Error
• Exception 可以显式转换为 Error 或 Result<T>
• Error 可以显式转换为 Exception

使用示例:

// 隐式转换
Result<int> result1 = 100;  // 成功的结果
Result<int> result2 = Error.Empty();  // 失败的结果

// 显式转换
int value = (int)result1;  // 返回 100
Error error = (Error)"错误信息";
Exception ex = (Exception)error;

---

多泛型参数结果类型

除了 Result<T> 之外，类库还支持多泛型参数的结果类型，最多支持 10 个泛型参数：

• Result<T1, T2> - 包含两个值的结果类型
• Result<T1, T2, T3> - 包含三个值的结果类型
• ... 最多支持到 Result<T1, T2, ..., T10>

这些类型提供了类似的属性和方法，可以通过索引器访问各个值：

var result = new Result<int, string>(100, "成功");
var value1 = result.Item1;  // 返回 100
var value2 = result.Item2;  // 返回 "成功"

---

使用示例

链式操作

var result = Step1()
    .Then(() => Step2())
    .Then(() => Step3());

if (result.Successed)
{
    // 所有步骤都成功
}
else
{
    // 处理错误
    Console.WriteLine(result.Message);
}

匹配操作

var result = SomeMethod();
var value = result.Match(
    onSuccess: () => "操作成功",
    onFailure: (err) => $"操作失败: {err.Message}"
);

错误追踪

var result = Step1()
    .Then(() => Step2())
    .Then(() => Step3());

if (!result.Successed)
{
    // 遍历错误链
    foreach (var inner in result.Collections())
    {
        Console.WriteLine($"{inner.MethodName} (Line {inner.LineNumber}): {inner.Message}");
    }
}

---

注意事项

1. 空值处理: 所有方法对 null 值有特殊处理，会返回相应的错误
2. 异常处理: 所有方法返回 Result 类型，请检查 Successed 属性
3. 链式操作: 使用 Then 方法时，如果前面的步骤失败，后续步骤不会执行
4. 类型转换: Result<T> 实现了 IConvertible 接口，支持各种类型转换
5. 性能: 链式操作和错误追踪可能涉及多次对象创建，请注意性能影响

---

工具类 (Utilities) API

工具类提供了超过 2000 个扩展方法，涵盖类型转换、字符串操作、数值计算等功能。由于内容庞大，分为多个部分：

第一部分：数值类型扩展方法

由于 Utilities 类包含的方法数量庞大（超过 2000 个），本文档按类型分组：

• 第一部分（本文档）：数值类型扩展方法（Int32, Int64, Double, Single, Decimal, Int16, UInt16, UInt32, UInt64, SByte, Byte）
• 第二部分：字符串扩展方法
• 第三部分：其他类型扩展方法

Int32 扩展方法

Clamp

public static Result<int> Clamp(this int src, int min, int max)

功能说明: 将目标值限制在 [min, max] 范围内，如果小于 min 则返回 min，如果大于 max 则返回 max，否则返回目标值。

参数:

• src: 目标值
• min: 最小值
• max: 最大值

返回值: 限制后的整数值

异常:

• 当 min > max 时，返回 Error.OutofRange 错误

使用示例:

int value = 150;
var result = value.Clamp(0, 100);  // 返回 100

---

Ceiling

public static Result<int> Ceiling(this float src)

功能说明: 返回大于或等于指定的单精度浮点数的最小整数值。

参数:

• src: 一个单精度浮点数

返回值: 大于或等于 src 的最小整数值。如果 src 等于 NaN、NegativeInfinity 或 PositiveInfinity，则返回该值。

异常: 无

使用示例:

float value = 3.7f;
var result = value.Ceiling();  // 返回 4

---

public static Result<int> Ceiling(this double src)

功能说明: 返回大于或等于指定的双精度浮点数的最小整数值。

参数:

• src: 一个双精度浮点数

返回值: 大于或等于 src 的最小整数值。如果 src 等于 NaN、NegativeInfinity 或 PositiveInfinity，则返回该值。

异常: 无

---

Floor

public static Result<int> Floor(this float src)

功能说明: 返回小于或等于指定单精度浮点数的最大整数值。

参数:

• src: 一个单精度浮点数

返回值: 小于或等于 src 的最大整数值。如果 src 等于 NaN、NegativeInfinity 或 PositiveInfinity，则返回该值。

异常: 无

使用示例:

float value = 3.7f;
var result = value.Floor();  // 返回 3

---

public static Result<int> Floor(this double src)

功能说明: 返回小于或等于指定双精度浮点数的最大整数值。

参数:

• src: 一个双精度浮点数

返回值: 小于或等于 src 的最大整数值。如果 src 等于 NaN、NegativeInfinity 或 PositiveInfinity，则返回该值。

异常: 无

---

ComplementalCode

public static Result<int> ComplementalCode(this int source)

功能说明: 获取 32 位有符号整数的补码。

参数:

• source: 目标数据

返回值: 返回对应的 32 位有符号整数的补码

备注: 如果目标数据为 32 位有符号整数的最小值，则返回其最大值

异常: 无

使用示例:

int value = 5;
var result = value.ComplementalCode();  // 返回 ~5

---

GetDigits

public static int[] GetDigits(this int src)

功能说明: 获取整数的每一位数字。

参数:

• src: 源目标数字

返回值: 返回包含每一位数字的数组（从高位到低位）

异常: 无

使用示例:

int value = 12345;
var digits = value.GetDigits();  // 返回 [1, 2, 3, 4, 5]

---

public static int[] GetDigits(this Result<int> src)

功能说明: 获取整数的每一位数字（Result 版本）。

参数:

• src: 源目标数字（Result 类型）

返回值: 返回包含每一位数字的数组

异常:

• 当 src 失败时，返回空数组或错误

---

GetDigit

public static Result<int> GetDigit(this int src, int pos)

功能说明: 获取整数中指定位置的数字。

参数:

• src: 源目标数字
• pos: 指定位置索引（从 0 开始，0 为最高位）

返回值: 返回指定位置的数字（0-9）

异常:

• 当 pos < 0 或 pos >= 数字位数 时，返回 Error.Argument 错误

使用示例:

int value = 12345;
var digit = value.GetDigit(2);  // 返回 3（第 3 位数字）

---

public static Result<int> GetDigit(this Result<int> src, int pos)

功能说明: 获取整数中指定位置的数字（Result 版本）。

参数:

• src: 源目标数字（Result 类型）
• pos: 指定位置索引

返回值: 返回指定位置的数字

异常:

• 当 src 失败时，返回相应的错误
• 当 pos 超出范围时，返回 Error.Argument 错误

---

Int64 扩展方法

Clamp

public static Result<long> Clamp(this long src, long min, long max)

功能说明: 将目标值限制在 [min, max] 范围内。

参数:

• src: 目标值
• min: 最小值
• max: 最大值

返回值: 限制后的长整数值

异常:

• 当 min > max 时，返回 Error.OutofRange 错误

---

ComplementalCode

public static Result<long> ComplementalCode(this long source)

功能说明: 获取 64 位有符号整数的补码。

参数:

• source: 目标数据

返回值: 返回对应的 64 位有符号整数的补码

备注: 如果目标数据为 64 位有符号整数的最小值，则返回其最大值

异常: 无

---

Double 扩展方法

Clamp

public static Result<double> Clamp(this double src, double min, double max)

功能说明: 将目标值限制在 [min, max] 范围内。

参数:

• src: 目标值
• min: 最小值
• max: 最大值

返回值: 限制后的双精度浮点数值

异常:

• 当 min > max 时，返回 Error.OutofRange 错误

使用示例:

double value = 150.5;
var result = value.Clamp(0.0, 100.0);  // 返回 100.0

---

GetDouble

public static unsafe Result<double> GetDouble(this byte[] src, int index = 0)

功能说明: 将指定的字节数组转化成双精度浮点数。

参数:

• src: 指定字节数组，字节数组长度至少为 index + 8
• index: 指定字节数组的起始索引，默认为 0

返回值: 返回一个由 8 个字节构成、从 index 开始的双精度浮点数

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当 index < 0 或 index > src.Length - 8 时，返回 Error.OutofRange 错误

使用示例:

byte[] bytes = { 0x40, 0x09, 0x21, 0xFB, 0x54, 0x44, 0x2D, 0x18 };
var result = bytes.GetDouble(0);  // 返回对应的 double 值

---

public static Result<double> GetDouble(this Result<byte[]> src, int index = 0)

功能说明: 将指定的字节数组转化成双精度浮点数（Result 版本）。

参数:

• src: 指定字节数组（Result 类型）
• index: 指定字节数组的起始索引，默认为 0

返回值: 返回双精度浮点数

异常:

• 当 src 失败时，返回相应的错误

---

ToRadian

public static Result<double> ToRadian(this double degrees)

功能说明: 将角度转换为弧度。

参数:

• degrees: 角度值

返回值: 对应的弧度值

异常: 无

使用示例:

double degrees = 90.0;
var radians = degrees.ToRadian();  // 返回 π/2

---

ToDegree

public static Result<double> ToDegree(this double radians)

功能说明: 将弧度转换为角度。

参数:

• radians: 弧度值

返回值: 对应的角度值

异常: 无

使用示例:

double radians = Math.PI;
var degrees = radians.ToDegree();  // 返回 180.0

---

Single 扩展方法

Clamp

public static Result<float> Clamp(this float src, float min, float max)

功能说明: 将目标值限制在 [min, max] 范围内。

参数:

• src: 目标值
• min: 最小值
• max: 最大值

返回值: 限制后的单精度浮点数值

异常:

• 当 min > max 时，返回 Error.OutofRange 错误

---

GetSingle

public static unsafe Result<float> GetSingle(this byte[] src, int index = 0)
public static unsafe Result<float> GetSingle(this List<byte> src, int index = 0)

功能说明: 将指定的字节数组或列表转化成单精度浮点数。

参数:

• src: 指定字节数组或列表，长度至少为 index + 4
• index: 指定字节数组的起始索引，默认为 0

返回值: 返回一个由 4 个字节构成、从 index 开始的单精度浮点数

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当 index < 0 或 index > src.Length - 4 时，返回 Error.OutofRange 错误

使用示例:

byte[] bytes = { 0x40, 0x49, 0x0F, 0xDB };
var result = bytes.GetSingle(0);  // 返回对应的 float 值

---

Decimal 扩展方法

Clamp

public static Result<decimal> Clamp(this decimal src, decimal min, decimal max)

功能说明: 将目标值限制在 [min, max] 范围内。

参数:

• src: 目标值
• min: 最小值
• max: 最大值

返回值: 限制后的十进制数值

异常:

• 当 min > max 时，返回 Error.OutofRange 错误

---

Byte 扩展方法

GetBytes

以下方法将各种数值类型转换为字节数组：

public static Result<byte[]> GetBytes(this byte src)
public static Result<byte[]> GetBytes(this sbyte src)
public static Result<byte[]> GetBytes(this short src)
public static Result<byte[]> GetBytes(this ushort src)
public static Result<byte[]> GetBytes(this int src)
public static Result<byte[]> GetBytes(this uint src)
public static Result<byte[]> GetBytes(this long src)
public static Result<byte[]> GetBytes(this ulong src)
public static Result<byte[]> GetBytes(this float src)
public static Result<byte[]> GetBytes(this double src)
public static Result<byte[]> GetBytes(this decimal src)
public static Result<byte[]> GetBytes(this Enum src)

功能说明: 将各种数值类型转换为字节数组。

参数:

• src: 源数据（byte, sbyte, short, ushort, int, uint, long, ulong, float, double, decimal, Enum）

返回值:

• byte, sbyte: 返回包含 1 个字节的数组
• short, ushort: 返回包含 2 个字节的数组
• int, uint: 返回包含 4 个字节的数组
• long, ulong: 返回包含 8 个字节的数组
• float: 返回包含 4 个字节的数组
• double: 返回包含 8 个字节的数组
• decimal: 返回包含 16 个字节的数组
• Enum: 返回枚举值对应的整数字节数组

异常:

• 当 sbyte 值小于 byte.MinValue 时，返回 Error.Result 错误（包含 ArgumentOutOfRangeException）

使用示例:

int value = 123456;
var bytes = value.GetBytes();  // 返回 4 字节数组

long lValue = 123456789L;
var lBytes = lValue.GetBytes();  // 返回 8 字节数组

double dValue = 123.456;
var dBytes = dValue.GetBytes();  // 返回 8 字节数组

decimal decValue = 123.456m;
var decBytes = decValue.GetBytes();  // 返回 16 字节数组

---

GetInt16 / GetUInt16 / GetInt32 / GetUInt32 / GetInt64 / GetUInt64 / GetSByte

以下方法从字节数组获取各种整数类型的值：

public static Result<short> GetInt16(this byte[] src, int index = 0)
public static Result<short> GetInt16(this byte[] src, int index, bool isLittleEndian)
public static Result<short> GetInt16(this byte x, byte y)
public static Result<short> GetInt16(this List<byte> src, int index = 0)

public static Result<ushort> GetUInt16(this byte[] src, int index = 0)
public static Result<ushort> GetUInt16(this byte[] src, int index, bool isLittleEndian)
public static Result<ushort> GetUInt16(this byte x, byte y)
public static Result<ushort> GetUInt16(this List<byte> src, int index = 0)

public static Result<int> GetInt32(this byte[] src, int index = 0)
public static Result<int> GetInt32(this byte[] src, int index, bool isLittleEndian)
public static Result<int> GetInt32(this List<byte> src, int index = 0)

public static Result<uint> GetUInt32(this byte[] src, int index = 0)
public static Result<uint> GetUInt32(this byte[] src, int index, bool isLittleEndian)
public static Result<uint> GetUInt32(this List<byte> src, int index = 0)

public static Result<long> GetInt64(this byte[] src, int index = 0)
public static Result<long> GetInt64(this byte[] src, int index, bool isLittleEndian)
public static Result<long> GetInt64(this List<byte> src, int index = 0)

public static Result<ulong> GetUInt64(this byte[] src, int index = 0)
public static Result<ulong> GetUInt64(this byte[] src, int index, bool isLittleEndian)
public static Result<ulong> GetUInt64(this List<byte> src, int index = 0)

public static Result<sbyte> GetSByte(this byte[] src, int index = 0)

功能说明: 从字节数组或列表中获取指定类型的整数值。

参数:

• src: 字节数组或列表
• index: 起始索引，默认为 0
• isLittleEndian: 是否使用小端字节序（部分重载），默认为系统默认字节序
• x, y: 两个字节（用于组合成 16 位整数）

返回值:

• GetInt16 / GetUInt16: 返回 2 字节的 16 位整数
• GetInt32 / GetUInt32: 返回 4 字节的 32 位整数
• GetInt64 / GetUInt64: 返回 8 字节的 64 位整数
• GetSByte: 返回 1 字节的有符号字节

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当 index 超出范围时，返回 Error.OutofRange 错误

使用示例:

byte[] bytes = { 0x00, 0x00, 0x00, 0x7B };
var int32 = bytes.GetInt32(0);  // 返回 123

byte[] bytes2 = { 0x12, 0x34 };
var int16 = bytes2.GetInt16(0);  // 返回对应的 short 值

// 使用两个字节组合
var int16FromBytes = ((byte)0x12).GetInt16((byte)0x34);

// 指定字节序
var int32BigEndian = bytes.GetInt32(0, false);  // 大端字节序

---

Round

public static Result<int> Round(this float src)
public static Result<int> Round(this double src)

功能说明: 将浮点值舍入到最接近的整数值，并将中点值舍入到最接近的偶数。

参数:

• src: 单精度或双精度浮点数

返回值: 最接近的整数。如果小数部分正好处于两个整数中间，其中一个整数为偶数，另一个整数为奇数，则返回偶数

异常: 无

使用示例:

float f = 3.5f;
var rounded = f.Round();  // 返回 4（中点值舍入到偶数）

double d = 2.5;
var rounded2 = d.Round();  // 返回 2（中点值舍入到偶数）

double d2 = 3.7;
var rounded3 = d2.Round();  // 返回 4

---

注意: 由于文档内容较多，更多扩展方法请查看 第一部分（续）：数值类型扩展方法

---

使用示例

数值限制

// 限制整数范围
int value = 150;
var clamped = value.Clamp(0, 100);  // 返回 100

// 限制浮点数范围
double dValue = 150.5;
var dClamped = dValue.Clamp(0.0, 100.0);  // 返回 100.0

类型转换

// 整数转字节数组
int num = 123456;
var bytes = num.GetBytes();

// 字节数组转整数
byte[] data = { 0x00, 0x00, 0x00, 0x7B };
var result = data.GetInt32(0);  // 返回 123

角度弧度转换

// 角度转弧度
double degrees = 90.0;
var radians = degrees.ToRadian();

// 弧度转角度
double rad = Math.PI;
var deg = rad.ToDegree();  // 返回 180.0

数字操作

// 获取数字的每一位
int number = 12345;
var digits = number.GetDigits();  // 返回 [1, 2, 3, 4, 5]

// 获取指定位置的数字
var digit = number.GetDigit(2);  // 返回 3

---

注意事项

1. 字节序: 字节数组转换方法使用系统默认的字节序（通常是小端序）
2. 范围检查: 使用 Clamp 方法时，确保 min <= max，否则会返回错误
3. 索引范围: 从字节数组读取数据时，确保索引和长度有效
4. 精度: 浮点数转换可能涉及精度损失，请注意
5. 异常处理: 所有方法返回 Result 类型，请检查 Successed 属性

---

第一部分（续）：数值类型扩展方法

本文档是 第一部分：数值类型扩展方法 的续篇，包含更多数值类型的扩展方法。

相关文档:

• 第一部分：数值类型扩展方法（基础方法）
• 第二部分：字符串扩展方法
• 第三部分：其他类型扩展方法

Int32 其他扩展方法

GetDigitLength

public static int GetDigitLength(this int src)

功能说明: 获取整数的位数。

参数:

• src: 源目标数字

返回值: 返回数字的位数（1-10）

异常: 无

使用示例:

int value = 12345;
var length = value.GetDigitLength();  // 返回 5

---

Nullable

public static Result<int> Nullable(this int? src, int defaultvalue = default)

功能说明: 检查可空的 32 位有符号整数是否为空。

参数:

• src: 可空的 32 位有符号整数
• defaultvalue: 当判定为空时的默认值，默认为 0

返回值: 不为空时返回 src，否则返回默认值

异常: 无

---

Round

public static Result<int> Round(this float src)
public static Result<int> Round(this double src)

功能说明: 将浮点值舍入到最接近的整数值，并将中点值舍入到最接近的偶数。

参数:

• src: 单精度或双精度浮点数

返回值: 最接近的整数

异常: 无

---

SetBitValue

public static Result<int> SetBitValue(this int source, int index = 0, bool bitValue = false)

功能说明: 将 32 位有符号整数指定位进行置位/复位操作。

参数:

• source: 32 位有符号整数
• index: 指定的索引，范围为 0~31，默认为 0
• bitValue: 进行置位/复位操作，默认为 false（复位操作）

返回值: 返回变更后的 32 位有符号整数

异常: 无

---

ToBigEndian

public static Result<int> ToBigEndian(this int src)

功能说明: 将整数转换为大端字节序。

参数:

• src: 源整数

返回值: 大端字节序的整数

异常: 无

---

HostToNetworkOrder / NetworkToHostOrder

public static Result<int> HostToNetworkOrder(this int src)
public static Result<int> NetworkToHostOrder(this int src)

功能说明: 将整数值由主机字节顺序转换为网络字节顺序，或反之。

参数:

• src: 要转换的数字

返回值: 转换后的整数值

异常: 无

---

ComplementalCode

public static Result<int> ComplementalCode(this int source)

功能说明: 获取 32 位有符号整数的补码。

参数:

• source: 目标数据

返回值: 返回对应的 32 位有符号整数的补码

备注: 如果目标数据为 32 位有符号整数的最小值，则返回其最大值

异常: 无

使用示例:

int value = 5;
var result = value.ComplementalCode();  // 返回 ~5

---

OnesComplementCode

public static Result<int> OnesComplementCode(this int source)

功能说明: 获取 32 位有符号整数的反码。

参数:

• source: 目标数据

返回值: 返回对应的 32 位有符号整数的反码

备注: 如果目标数据为 32 位有符号整数的最小值，则返回其本身

异常: 无

使用示例:

int value = 5;
var result = value.OnesComplementCode();  // 返回 -5 的反码

---

Ceiling / Floor

public static Result<int> Ceiling(this float src)
public static Result<int> Ceiling(this double src)
public static Result<int> Floor(this float src)
public static Result<int> Floor(this double src)

功能说明: 将浮点数向上或向下取整。

参数:

• src: 单精度或双精度浮点数

返回值:

• Ceiling: 大于或等于指定浮点数的最小整数值
• Floor: 小于或等于指定浮点数的最大整数值

异常: 无

使用示例:

float f = 3.7f;
var ceiling = f.Ceiling();  // 返回 4
var floor = f.Floor();      // 返回 3

double d = 3.2;
var ceiling2 = d.Ceiling();  // 返回 4
var floor2 = d.Floor();      // 返回 3

---

Random

public static Result<int> Random(this int min, int max, int start = 0)

功能说明: 生成指定范围内的随机整数。

参数:

• min: 最小值（包含）
• max: 最大值（不包含）
• start: 随机种子起始位置，默认为 0

返回值: 返回 [min, max) 范围内的随机整数

异常: 无

使用示例:

// 生成 1 到 100 之间的随机数
var random = 1.Random(100);  // 返回 1-99 之间的随机数

---

ToInt32

public static Result<int> ToInt32(this byte src)
public static Result<int> ToInt32(this sbyte src)
public static Result<int> ToInt32(this short src)
public static Result<int> ToInt32(this ushort src)
public static Result<int> ToInt32(this uint src)
public static Result<int> ToInt32(this long src)
public static Result<int> ToInt32(this ulong src)
public static Result<int> ToInt32(this float src)
public static Result<int> ToInt32(this double src)
public static Result<int> ToInt32(this decimal src)

功能说明: 将各种数值类型转换为 32 位有符号整数。

参数:

• src: 源数据（byte, sbyte, short, ushort, uint, long, ulong, float, double, decimal）

返回值: 转换后的 32 位有符号整数

异常:

• 当值超出 Int32 范围时，返回 Error.OutofRange 错误

使用示例:

byte b = 100;
var intValue = b.ToInt32();  // 返回 100

long l = 123456789L;
var intFromLong = l.ToInt32();  // 如果超出范围会返回错误

---

Int64 其他扩展方法

Clamp

public static Result<long> Clamp(this long src, long min, long max)

功能说明: 将目标值限制在 [min, max] 范围内。

参数:

• src: 目标值
• min: 最小值
• max: 最大值

返回值: 限制后的 64 位有符号整数

异常:

• 当 min > max 时，返回 Error.OutofRange 错误

使用示例:

long value = 150L;
var clamped = value.Clamp(0L, 100L);  // 返回 100L

---

ComplementalCode

public static Result<long> ComplementalCode(this long source)

功能说明: 获取 64 位有符号整数的补码。

参数:

• source: 目标数据

返回值: 返回对应的 64 位有符号整数的补码

备注: 如果目标数据为 64 位有符号整数的最小值，则返回其最大值

异常: 无

使用示例:

long value = 5L;
var result = value.ComplementalCode();  // 返回 ~5L

---

Nullable

public static Result<long> Nullable(this long? src)

功能说明: 检查可空的 64 位有符号整数是否为空。

参数:

• src: 可空的 64 位有符号整数

返回值: 不为空时返回 src，否则返回 Error.Empty 错误

异常: 无

---

SetBitValue

public static Result<long> SetBitValue(this long source, int index = 0, bool bitValue = false)

功能说明: 将 64 位有符号整数指定位进行置位/复位操作。

参数:

• source: 64 位有符号整数
• index: 指定的索引，范围为 0~63，默认为 0
• bitValue: 进行置位/复位操作，默认为 false（复位操作）

返回值: 返回变更后的 64 位有符号整数

异常: 无

---

ToUnixTicks / ToUnixMillisecond

public static Result<long> ToUnixTicks(this DateTime source)
public static Result<long> ToUnixMillisecond(this DateTime source)

功能说明: 将 DateTime 转换为 Unix 时间戳（Ticks 或毫秒）。

参数:

• source: 日期时间值

返回值: Unix 时间戳

异常:

• 当日期值早于 Unix 时间戳的起始（1970-01-01）时，返回 Error.Argument 错误

---

OnesComplementCode

public static Result<long> OnesComplementCode(this long source)

功能说明: 获取 64 位有符号整数的反码。

参数:

• source: 目标数据

返回值: 返回对应的 64 位有符号整数的反码

备注: 如果目标数据为 64 位有符号整数的最小值，则返回其本身

异常: 无

---

ElapsedMilliseconds / ElapsedTicks

public static Result<long> ElapsedMilliseconds(this Action action)
public static Result<long> ElapsedMilliseconds<TResult>(this Func<TResult> func, out TResult result)
public static Result<long> ElapsedTicks(this Action action)
public static Result<long> ElapsedTicks<TParam>(this Action<TParam> action, TParam param)

功能说明: 记录方法执行时间（毫秒或 Ticks）。

参数:

• action: 要执行的动作
• func: 要执行的函数（带返回值）
• result: 函数执行结果（输出参数）
• param: 动作参数

返回值: 执行时间（毫秒或 Ticks）

异常: 无

使用示例:

// 测量方法执行时间（毫秒）
var elapsed = (() => DoSomething()).ElapsedMilliseconds();

// 测量带参数的方法执行时间（Ticks）
var ticks = ((int x) => Process(x)).ElapsedTicks(100);

---

Double 其他扩展方法

Nullable

public static Result<double> Nullable(this double? src)

功能说明: 检查可空的双精度浮点数是否为空。

参数:

• src: 可空的双精度浮点数

返回值: 不为空时返回 src，否则返回 Error.Empty 错误

异常: 无

---

SetBitValue

public static Result<double> SetBitValue(this double source, int index = 0, bool bitValue = false)

功能说明: 将双精度浮点数指定位进行置位/复位操作。

参数:

• source: 双精度浮点数
• index: 指定的索引，范围为 0~63，默认为 0
• bitValue: 进行置位/复位操作，默认为 false（复位操作）

返回值: 返回变更后的双精度浮点数

异常: 无

---

ToBigEndian

public static Result<double> ToBigEndian(this double src)

功能说明: 将双精度浮点数转换为大端字节序。

参数:

• src: 源双精度浮点数

返回值: 大端字节序的双精度浮点数

异常: 无

---

ToRound

public static Result<double> ToRound(this object src, int digits = 0)

功能说明: 将对象转换为双精度浮点数并四舍五入到指定小数位数。

参数:

• src: 源对象（可转换为 double 的类型）
• digits: 小数位数，范围为 0~15，默认为 0

返回值: 四舍五入后的双精度浮点数

异常:

• 当 src 为 null 时，返回 Error.Empty 错误
• 当 digits 不在 0~15 范围内时，返回 Error.OutofRange 错误

使用示例:

double value = 123.456789;
var rounded = value.ToRound(2);  // 返回 123.46

decimal dec = 99.995m;
var rounded2 = dec.ToRound(2);  // 返回 100.00

---

ToDegree / ToRadian

public static Result<double> ToDegree(this double radian)
public static Result<double> ToRadian(this double degree)

功能说明: 角度和弧度之间的转换。

参数:

• radian: 弧度值（ToDegree）
• degree: 角度值（ToRadian）

返回值:

• ToDegree: 转换后的角度值
• ToRadian: 转换后的弧度值

异常: 无

使用示例:

double radians = Math.PI;
var degrees = radians.ToDegree();  // 返回 180.0

double deg = 90.0;
var rad = deg.ToRadian();  // 返回 π/2

---

ToDouble / ToDoubles

public static Result<double> ToDouble(this byte src)
public static Result<double> ToDouble(this sbyte src)
public static Result<double> ToDouble(this short src)
public static Result<double> ToDouble(this ushort src)
public static Result<double> ToDouble(this int src)
public static Result<double> ToDouble(this uint src)
public static Result<double> ToDouble(this long src)
public static Result<double> ToDouble(this ulong src)
public static Result<double> ToDouble(this float src)
public static Result<double> ToDouble(this double src)
public static Result<double> ToDouble(this decimal src)
public static Result<double> ToDouble(this bool src)
public static Result<double> ToDouble(this Enum src)
public static Result<double> ToDouble(this object src)

public static Result<double[]> ToDoubles(this byte[] src)
public static Result<double[]> ToDoubles(this sbyte[] src)
public static Result<double[]> ToDoubles(this short[] src)
public static Result<double[]> ToDoubles(this ushort[] src)
public static Result<double[]> ToDoubles(this int[] src)
public static Result<double[]> ToDoubles(this uint[] src)
public static Result<double[]> ToDoubles(this long[] src)
public static Result<double[]> ToDoubles(this ulong[] src)
public static Result<double[]> ToDoubles(this float[] src)
public static Result<double[]> ToDoubles(this double[] src)
public static Result<double[]> ToDoubles(this decimal[] src)
public static Result<double[]> ToDoubles(this bool[] src)
public static Result<double[]> ToDoubles(this Enum[] src)

功能说明: 将各种类型转换为双精度浮点数或双精度浮点数数组。

参数:

• src: 源数据（支持多种数值类型、布尔值、枚举、对象和数组）

返回值: 转换后的双精度浮点数或数组

异常:

• 当 src 为 null 时，返回 Error.Empty 错误
• 当值超出范围时，返回相应的错误

使用示例:

int value = 100;
var doubleValue = value.ToDouble();  // 返回 100.0

bool flag = true;
var boolDouble = flag.ToDouble();  // 返回 1.0

int[] ints = { 1, 2, 3 };
var doubles = ints.ToDoubles();  // 返回 [1.0, 2.0, 3.0]

---

Single 其他扩展方法

Nullable

public static Result<float> Nullable(this float? src)

功能说明: 检查可空的单精度浮点数是否为空。

参数:

• src: 可空的单精度浮点数

返回值: 不为空时返回 src，否则返回 0F

异常: 无

---

SetBitValue

public static Result<float> SetBitValue(this float source, int index = 0, bool bitValue = false)

功能说明: 将单精度浮点数指定位进行置位/复位操作。

参数:

• source: 单精度浮点数
• index: 指定的索引，范围为 0~31，默认为 0
• bitValue: 进行置位/复位操作，默认为 false（复位操作）

返回值: 返回变更后的单精度浮点数

异常: 无

---

DistanceSquared

public static Result<float> DistanceSquared(this PointF start, PointF end)

功能说明: 计算两个点之间的距离的平方。

参数:

• start: 起始位置
• end: 结束位置

返回值: 返回两个点之间距离的平方

异常: 无

---

Decimal 其他扩展方法

Nullable

public static Result<decimal> Nullable(this decimal? src)

功能说明: 检查可空的十进制数是否为空。

参数:

• src: 可空的十进制数

返回值: 不为空时返回 src，否则返回 Error.Empty 错误

异常: 无

---

Byte 其他扩展方法

Clamp

public static Result<byte> Clamp(this byte src, byte min, byte max)

功能说明: 将目标值限制在 [min, max] 范围内。

参数:

• src: 目标值
• min: 最小值
• max: 最大值

返回值: 限制后的字节值

异常:

• 当 min > max 时，返回 Error.OutofRange 错误

---

BigEndian

public static Result<byte[]> BigEndian(this byte[] src)

功能说明: 将字节数组转换为大端字节序。

参数:

• src: 源字节数组

返回值: 大端字节序的字节数组

异常: 无

---

LittleEndian

public static Result<byte[]> LittleEndian(this byte[] src)

功能说明: 将字节数组转换为小端字节序。

参数:

• src: 源字节数组

返回值: 小端字节序的字节数组

异常: 无

使用示例:

byte[] data = { 0x01, 0x02, 0x03, 0x04 };
var littleEndian = data.LittleEndian();  // 转换为小端字节序

---

GetByte

public static Result<byte> GetByte(this short src, int index = 0)
public static Result<byte> GetByte(this ushort src, int index = 0)
public static Result<byte> GetByte(this int src, int index = 0)
public static Result<byte> GetByte(this uint src, int index = 0)
public static Result<byte> GetByte(this long src, int index = 0)
public static Result<byte> GetByte(this ulong src, int index = 0)
public static Result<byte> GetByte(this float src, int index = 0)
public static Result<byte> GetByte(this double src, int index = 0)
public static Result<byte> GetByte(this decimal src, int index = 0)

功能说明: 从各种数值类型中获取指定索引位置的字节。

参数:

• src: 源数据
• index: 字节索引位置，默认为 0

返回值: 指定位置的字节值

异常:

• 当 index 超出范围时，返回 Error.OutofRange 错误

使用示例:

int value = 0x12345678;
var byte0 = value.GetByte(0);  // 获取最低位字节
var byte1 = value.GetByte(1);  // 获取第二个字节

---

GetAndDigit / GetOrDigit

public static Result<byte> GetAndDigit(this int offset)
public static Result<byte> GetOrDigit(this int offset)

功能说明: 获取用于位操作的掩码值。

参数:

• offset: 位偏移量，范围为 0~7

返回值:

• GetAndDigit: 返回用于 AND 操作的掩码值（用于清除指定位）
• GetOrDigit: 返回用于 OR 操作的掩码值（用于设置指定位）

异常:

• 当 offset 不在 0~7 范围内时，返回 Error.OutofRange 错误

使用示例:

// 获取第 3 位的 OR 掩码（用于置位）
var orMask = 3.GetOrDigit();  // 返回 0x08

// 获取第 2 位的 AND 掩码（用于复位）
var andMask = 2.GetAndDigit();  // 返回用于清除第 2 位的掩码

---

其他数值类型扩展方法

Int16, UInt16, UInt32, UInt64, SByte

这些类型也提供了类似的扩展方法：

• Clamp: 限制数值范围
• GetBytes: 转换为字节数组
• GetInt16, GetUInt16, GetUInt32, GetUInt64, GetSByte: 从字节数组获取对应类型的值
• ComplementalCode: 获取补码
• OnesComplementCode: 获取反码（仅 Int16, Int32, Int64）
• SetBitValue: 位操作
• ToBigEndian: 转换为大端字节序
• HostToNetworkOrder / NetworkToHostOrder: 字节序转换
• Nullable: 可空类型处理
• GetDigitLength: 获取数字位数（部分类型）

方法签名和用法与上述 Int32、Int64 等方法类似，只是类型不同。

---

GetInt16 / GetUInt16 / GetUInt32 / GetUInt64 / GetSByte

// GetInt16 示例
public static Result<short> GetInt16(this byte[] src, int index = 0)
public static Result<short> GetInt16(this byte[] src, int index, bool isLittleEndian)
public static Result<short> GetInt16(this byte x, byte y)
public static Result<short> GetInt16(this int src, int index = 0)
public static Result<short> GetInt16(this long src, int index = 0)
// ... 其他重载

// GetUInt16, GetUInt32, GetUInt64, GetSByte 类似

功能说明: 从字节数组或其他类型中获取指定类型的值。

参数:

• src: 源数据（字节数组或其他数值类型）
• index: 起始索引，默认为 0
• isLittleEndian: 是否使用小端字节序（部分重载）
• x, y: 两个字节（用于组合成 16 位整数）

返回值: 转换后的指定类型值

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当 index 超出范围时，返回 Error.OutofRange 错误

使用示例:

byte[] bytes = { 0x12, 0x34 };
var int16 = bytes.GetInt16(0);  // 从字节数组获取 Int16

int value = 0x12345678;
var int16FromInt = value.GetInt16(0);  // 获取 Int16 数组的第一个元素

---

GetDigitLength

以下数值类型提供了 GetDigitLength 方法，用于获取数字的位数：

• byte: 返回 1-3 位
• sbyte: 返回 1-3 位
• short: 返回 1-5 位
• ushort: 返回 1-5 位
• uint: 返回 1-10 位
• int: 返回 1-10 位（已在第一部分文档中说明）

使用示例:

byte b = 123;
var length = b.GetDigitLength();  // 返回 3

short s = 12345;
var sLength = s.GetDigitLength();  // 返回 5

---

GetInt32s

public static Result<int[]> GetInt32s(this long src)
public static Result<int[]> GetInt32s(this ulong src)
public static Result<int[]> GetInt32s(this double src)
public static Result<int[]> GetInt32s(this decimal src)

功能说明: 将 64 位整数、双精度浮点数或十进制数转换为 Int32 数组。

参数:

• src: 源数据（long, ulong, double 或 decimal）

返回值: 包含 Int32 值的数组

• long / ulong: 返回 2 个元素的数组
• double: 返回 2 个元素的数组
• decimal: 返回 4 个元素的数组

异常: 无

使用示例:

// 将 long 转换为 Int32 数组（2 个元素）
long value = 1234567890123456789L;
var intArray = value.GetInt32s();

// 将 double 转换为 Int32 数组（2 个元素）
double dValue = 123.456;
var dIntArray = dValue.GetInt32s();

// 将 decimal 转换为 Int32 数组（4 个元素）
decimal decValue = 123.456m;
var decIntArray = decValue.GetInt32s();

---

ToInt32s

public static Result<int[]> ToInt32s(this byte[] src)
public static Result<int[]> ToInt32s(this sbyte[] src)
public static Result<int[]> ToInt32s(this short[] src)
public static Result<int[]> ToInt32s(this ushort[] src)
public static Result<int[]> ToInt32s(this int[] src)
public static Result<int[]> ToInt32s(this uint[] src)
public static Result<int[]> ToInt32s(this long[] src)
public static Result<int[]> ToInt32s(this ulong[] src)
public static Result<int[]> ToInt32s(this decimal[] src)

功能说明: 将各种数值类型的数组转换为 Int32 数组。

参数:

• src: 源数组（byte[], sbyte[], short[], ushort[], int[], uint[], long[], ulong[], decimal[]）

返回值: 转换后的 Int32 数组

异常:

• 当 src 为 null 或空时，返回 Error.Empty 错误
• 当值超出 Int32 范围时，返回 Error.OutofRange 错误

使用示例:

byte[] bytes = { 100, 200, 255 };
var intArray = bytes.ToInt32s();  // 返回 [100, 200, 255]

long[] longs = { 100L, 200L, 300L };
var ints = longs.ToInt32s();  // 返回 [100, 200, 300]

---

Int64 转换方法

ToInt64

public static Result<long> ToInt64(this bool src)
public static Result<long> ToInt64(this byte src)
public static Result<long> ToInt64(this sbyte src)
public static Result<long> ToInt64(this char src)
public static Result<long> ToInt64(this short src)
public static Result<long> ToInt64(this ushort src)
public static Result<long> ToInt64(this int src)
public static Result<long> ToInt64(this uint src)
public static Result<long> ToInt64(this long src)
public static Result<long> ToInt64(this ulong src)
public static Result<long> ToInt64(this float src)
public static Result<long> ToInt64(this double src, bool isRound = false)
public static Result<long> ToInt64(this decimal src)
public static Result<long> ToInt64(this string src)
public static Result<long> ToInt64(this string src, IFormatProvider provider)
public static Result<long> ToInt64(this Enum src)
public static Result<long> ToInt64(this DateTime src)
public static Result<long> ToInt64(this object src)

功能说明: 将各种类型转换为 64 位有符号整数。

参数:

• src: 源数据（支持多种数值类型、布尔值、字符、字符串、枚举、日期时间、对象等）
• isRound: 对于 double 类型，是否四舍五入，默认为 false（截断）
• provider: 格式提供程序（字符串转换时可选）

返回值: 转换后的 64 位有符号整数

异常:

• 当 src 为 null 时，返回 Error.Empty 错误
• 当值超出 Int64 范围时，返回 Error.OutofRange 错误
• 当字符串格式不正确时，返回 Error.Format 错误

使用示例:

int value = 123456;
var longValue = value.ToInt64();  // 返回 123456L

double d = 123.7;
var long1 = d.ToInt64();      // 返回 123（截断）
var long2 = d.ToInt64(true);  // 返回 124（四舍五入）

string text = "123456789";
var longFromString = text.ToInt64();  // 返回 123456789L

---

---

第二部分：字符串扩展方法

本文档详细说明 Hi.Ltd 类库中工具类 (Utilities) 的字符串类型扩展方法。

本文档包含所有字符串 (string) 类型的扩展方法，按字母顺序组织。

相关文档:

• 第一部分：数值类型扩展方法
• 第三部分：其他类型扩展方法

字符串扩展方法

FormatWithDecimal

public static Result<string> FormatWithDecimal(this long value, int decimalPlaces)

功能说明: 将整数格式化为带小数点的字符串。

参数:

• value: 要格式化的整数值
• decimalPlaces: 小数点后的位数

返回值: 格式化后的字符串

异常:

• 当转换过程中发生异常时，返回 Error.Result 错误

使用示例:

long value = 12345;
var result = value.FormatWithDecimal(2);  // 返回 "123.45"

---

GenHexString

public static Result<string> GenHexString(this byte[] src)

功能说明: 生成16进制格式的字符串。

参数:

• src: byte数组对象

返回值: 返回16进制格式的字符串，每个字节中间以空格隔开

异常: 无

使用示例:

byte[] data = { 0x01, 0x02, 0x0A, 0xFF };
var result = data.GenHexString();  // 返回 "01 02 0A FF "

---

public static Result<string> GenHexString(this Result<byte[]> src)

功能说明: 对 Result<byte[]> 类型执行 GenHexString 操作。

参数:

• src: Result<byte[]> 对象

返回值: 如果 src 成功，返回16进制字符串；否则返回错误

异常: 无

---

GetCombinations

public static IEnumerable<string> GetCombinations(this List<List<string>> src)

功能说明: 将多个 List<string> 进行依次排列组合，生成迭代的组合字符串。

参数:

• src: 目标数据源，包含多个字符串列表

返回值: 返回迭代后的字符串，可以通过 ToArray() 获取字符串数组，或者 foreach 来获取字符串数组成员

异常: 无

使用示例:

var lists = new List<List<string>>
{
    new List<string> { "A", "B" },
    new List<string> { "1", "2" }
};
var combinations = lists.GetCombinations();
// 返回: "A 1", "A 2", "B 1", "B 2"

---

GetDescription

public static Result<string> GetDescription(this MemberInfo type)

功能说明: 获取成员信息的描述属性值。

参数:

• type: 成员信息对象（方法、属性等）

返回值: 如果存在 DescriptionAttribute，返回描述信息；否则返回空字符串

异常: 无

使用示例:

var method = typeof(MyClass).GetMethod("MyMethod");
var description = method.GetDescription();

---

GetDirectories

public static Result<string[]> GetDirectories(this string path)

功能说明: 返回所有目录的名称（包括其路径）。

参数:

• path: 要搜索的目录的相对或绝对路径。此字符串不区分大小写。

返回值: 与所有目录的完整名称（包含路径）的数组；如果未找到任何目录，则为空数组。

异常:

• 当 path 为空或 null 时，返回 Error.Empty 错误
• 当目录不存在时，返回 Error.Empty 错误

使用示例:

var result = @"C:\MyFolder".GetDirectories();
if (result.Successed)
{
    foreach (var dir in result.Content)
    {
        Console.WriteLine(dir);
    }
}

---

GetFile

public static Result<string[]> GetFile(this string path)

功能说明: 返回指定目录中所有文件和目录的名称（包含其路径）。

参数:

• path: 要搜索的目录的相对或绝对路径。此字符串不区分大小写。

返回值: 指定目录中所有文件和目录完整名称（包含路径）的数组；如果未找到任何文件或目录，则为空数组。

异常:

• 当 path 为空或 null 时，返回 Error.Empty 错误

使用示例:

var result = @"C:\MyFolder".GetFile();

---

GetFiles

public static Result<string[]> GetFiles(this string path)

功能说明: 返回指定目录中所有文件的名称（包含其路径）。

参数:

• path: 要搜索的目录的相对或绝对路径。此字符串不区分大小写。

返回值: 指定目录中所有文件完整名称（包含路径）的数组；如果未找到任何文件，则为空数组。

异常:

• 当 path 为空或 null 时，返回 Error.Empty 错误

使用示例:

var result = @"C:\MyFolder".GetFiles();
if (result.Successed)
{
    foreach (var file in result.Content)
    {
        Console.WriteLine(file);
    }
}

---

public static Result<string[]> GetFiles(this Result<string> path)

功能说明: 对 Result<string> 类型执行 GetFiles 操作。

参数:

• path: Result<string> 对象

返回值: 如果 path 成功，返回文件数组；否则返回错误

异常: 无

---

GetString

public static Result<string> GetString(this byte[] src, Encoding encoding = null)

功能说明: 将字节数组转换为字符串。

参数:

• src: 字节数组
• encoding: 编码方式，默认为 UTF8

返回值: 转换后的字符串

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误

使用示例:

byte[] data = Encoding.UTF8.GetBytes("Hello");
var result = data.GetString();  // 返回 "Hello"

---

public static Result<string> GetString(this Result<byte[]> src, Encoding encoding = null)

功能说明: 对 Result<byte[]> 类型执行 GetString 操作。

参数:

• src: Result<byte[]> 对象
• encoding: 编码方式，默认为 UTF8

返回值: 如果 src 成功，返回字符串；否则返回错误

异常: 无

---

NewGuid

public static string NewGuid(bool isUpper = true)

功能说明: 生成新的 GUID 字符串。

参数:

• isUpper: 是否大写，默认大写

返回值: GUID 字符串（N格式，无连字符）

异常: 无

使用示例:

var guid = Utilities.NewGuid();  // 返回大写GUID
var guidLower = Utilities.NewGuid(false);  // 返回小写GUID

---

RemoveLast

public static Result<string> RemoveLast(this string src, int count = 1)

功能说明: 从字符串末尾移除指定数量的字符。

参数:

• src: 源字符串
• count: 要移除的字符数量，默认为 1

返回值: 移除后的字符串

异常:

• 当 count < 0 或 count > src.Length 时，返回 Error.OutofRange 错误

使用示例:

string text = "Hello World";
var result = text.RemoveLast(5);  // 返回 "Hello "

---

RemoveOne

public static Result<string> RemoveOne(this string src, int startIndex = 0)

功能说明: 从字符串中移除指定位置的一个字符。

参数:

• src: 源字符串
• startIndex: 要移除字符的起始索引，默认为 0

返回值: 移除后的字符串

异常:

• 当 startIndex < 0 或 startIndex >= src.Length 时，返回 Error.OutofRange 错误

使用示例:

string text = "Hello";
var result = text.RemoveOne(2);  // 返回 "Helo"

---

Replace

public static Result<string> Replace(this string src, string replacement = "")

功能说明: 将字符串中的连续空白字符替换为指定的替换字符串。

参数:

• src: 源字符串
• replacement: 替换字符串，默认为空字符串

返回值: 替换后的字符串

异常: 无

使用示例:

string text = "Hello    World";
var result = text.Replace(" ");  // 返回 "Hello World"

---

Split

public static Result<string> Split(this string src, int index, params char[] defaultseparator)

功能说明: 获取基于指定的字符将字符串拆分的子字符串数组中指定索引的字符串。

参数:

• src: 目标字符串
• index: 指定索引
• defaultseparator: 指定的分隔字符，默认为逗号（,）

返回值: 返回拆分后字符串数组中指定的 index 的字符串。

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当 index 超出范围时，返回 Error.OutofRange 错误

使用示例:

string text = "A,B,C,D";
var result = text.Split(2);  // 返回 "C"

---

SplitFirst

public static Result<string> SplitFirst(this string src, params char[] defaultseparator)

功能说明: 获取字符串拆分后的第一个子字符串。

参数:

• src: 目标字符串
• defaultseparator: 指定的分隔字符，默认为逗号（,）

返回值: 拆分后的第一个子字符串

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当拆分结果为空时，返回 Error.OutofRange 错误

使用示例:

string text = "A,B,C";
var result = text.SplitFirst();  // 返回 "A"

---

SplitLast

public static Result<string> SplitLast(this string src, params char[] defaultseparator)

功能说明: 获取字符串拆分后的最后一个子字符串。

参数:

• src: 目标字符串
• defaultseparator: 指定的分隔字符，默认为逗号（,）

返回值: 拆分后的最后一个子字符串；如果字符串为空，返回空字符串

异常: 无

使用示例:

string text = "A,B,C";
var result = text.SplitLast();  // 返回 "C"

---

Substring

public static Result<string> Substring(this Result<string> src, int startIndex, int length)

功能说明: 从 Result<string> 中提取子字符串。

参数:

• src: Result<string> 对象
• startIndex: 起始索引
• length: 子字符串长度

返回值: 提取的子字符串

异常:

• 当 src 为空或失败时，返回 Error.Empty 或相应的错误
• 当索引超出范围时，可能抛出 ArgumentOutOfRangeException

使用示例:

Result<string> text = "Hello World";
var result = text.Substring(0, 5);  // 返回 "Hello"

---

ToBase64String

public static Result<string> ToBase64String(this byte[] src)
public static Result<string> ToBase64String(this byte[] src, Base64FormattingOptions options)
public static Result<string> ToBase64String(this byte[] src, int offset, int length)
public static unsafe string ToBase64String(this byte[] src, int offset, int length, Base64FormattingOptions options)
public static unsafe string ToBase64String(this byte[] src, int offset, int length, Base64FormattingOptions options, string defaultvalue)

功能说明: 将字节数组转换为 Base64 字符串。

参数:

• src: 字节数组
• options: Base64 格式化选项（None 或 InsertLineBreaks），可选
• offset: 起始偏移量，可选
• length: 要转换的长度，可选
• defaultvalue: 默认值，当转换失败时返回，可选

返回值: Base64 编码的字符串

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误或空字符串
• 当参数无效时，返回空字符串或默认值

使用示例:

byte[] data = Encoding.UTF8.GetBytes("Hello");
var result = data.ToBase64String();  // 返回 Base64 编码
var result2 = data.ToBase64String(Base64FormattingOptions.InsertLineBreaks);

---

ToHexString

public static Result<string> ToHexString(this byte src, bool isLower = true)
public static Result<string> ToHexString(this short src, bool isLower = true)
public static Result<string> ToHexString(this ushort src, bool isLower = true)
public static Result<string> ToHexString(this sbyte src, bool isLower = true)
public static Result<string> ToHexString(this int src, bool isLower = true)
public static Result<string> ToHexString(this uint src, bool isLower = true)
public static Result<string> ToHexString(this long src, bool isLower = true)
public static Result<string> ToHexString(this ulong src, bool isLower = true)

功能说明: 将各种整数类型转换为16进制字符串。

参数:

• src: 整数值（支持 byte, sbyte, short, ushort, int, uint, long, ulong）
• isLower: 是否小写，默认为小写

返回值: 16进制字符串

异常: 无

使用示例:

byte value = 255;
var result = value.ToHexString();  // 返回 "ff"
var resultUpper = value.ToHexString(false);  // 返回 "FF"

---

ToSaveString

public static Result<string> ToSaveString(this string src)

功能说明: 将字符串转换为安全的字符串（确保不为 null）。

参数:

• src: 源字符串

返回值: 如果 src 为 null，返回空字符串；否则返回原字符串

异常: 无

使用示例:

string text = null;
var result = text.ToSaveString();  // 返回 ""

---

ToStringBuilder

public static Result<StringBuilder> ToStringBuilder(this string src)

功能说明: 将字符串转换为 StringBuilder 对象。

参数:

• src: 源字符串

返回值: StringBuilder 对象

异常: 无

使用示例:

string text = "Hello";
var sb = text.ToStringBuilder();

---

public static Result<StringBuilder> ToStringBuilder(this Result<string> src)

功能说明: 对 Result<string> 类型执行 ToStringBuilder 操作。

参数:

• src: Result<string> 对象

返回值: 如果 src 成功，返回 StringBuilder；否则返回错误

异常: 无

---

ToString (byte[])

public static Result<string> ToString(this byte[] src)

功能说明: 将字节数组转换为16进制格式的字符串（带连字符）。

参数:

• src: 字节数组

返回值: 16进制格式的字符串，每个字节之间用连字符分隔

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误

使用示例:

byte[] data = { 0x01, 0x02, 0xFF };
var result = data.ToString();  // 返回 "01-02-FF"

---

public static Result<string> ToString(this byte[] src, int startIndex, int length)

功能说明: 将字节数组的指定部分转换为16进制格式的字符串。

参数:

• src: 字节数组
• startIndex: 起始索引
• length: 长度

返回值: 16进制格式的字符串

异常:

• 当参数无效时，返回相应的错误

---

ToTitleCase

public static Result<string> ToTitleCase(this string src)

功能说明: 将英文字符串进行首字母大写转换。

参数:

• src: 目标字符串

返回值: 如果当前字符串不是英文则返回其本身，如果字符串为空则返回空字符串，成功则返回转化成功后的首字母大写的字符串。

异常: 无

使用示例:

string text = "hello world";
var result = text.ToTitleCase();  // 返回 "Hello World"

---

TrimChars

public static Result<string> TrimChars(this string src, params char[] chars)

功能说明: 为字符串删除指定的 char。

参数:

• src: 源数据
• chars: 待删除的 char 列表候选

返回值: 返回删除后的字符串

异常: 无

使用示例:

string text = "Hello, World!";
var result = text.TrimChars(',', '!');  // 返回 "Hello World"

---

字符串验证方法

IsNullOrEmpty / IsNullOrWhiteSpace / IsNotNullOrEmpty

public static Result<bool> IsNullOrEmpty(this string src)
public static Result<bool> IsNullOrWhiteSpace(this string src)
public static Result<bool> IsNotNullOrEmpty(this string src)

功能说明: 检查字符串是否为空或空白。

参数:

• src: 要检查的字符串

返回值:

• IsNullOrEmpty: 如果为 null 或长度为 0，返回 true；否则返回 false
• IsNullOrWhiteSpace: 如果为 null 或全部为空白字符，返回 true；否则返回 false
• IsNotNullOrEmpty: 如果不为 null 且长度大于 0，返回 true；否则返回 false

异常: 无

使用示例:

string text = null;
var isEmpty = text.IsNullOrEmpty();  // 返回 true

string whitespace = "   ";
var isWhiteSpace = whitespace.IsNullOrWhiteSpace();  // 返回 true

---

IsEqual / IsNotEqual

public static Result<bool> IsEqual(this string src, string dst, bool ignoreCase = true)
public static Result<bool> IsNotEqual(this string src, string dst, bool ignoreCase = true)

功能说明: 比较两个字符串是否相等。

参数:

• src: 源字符串
• dst: 目标字符串
• ignoreCase: 是否忽略大小写，默认为 true

返回值:

• IsEqual: 如果相等，返回 true；否则返回 false
• IsNotEqual: 如果不相等，返回 true；否则返回 false

异常: 无

使用示例:

string text1 = "Hello";
string text2 = "hello";
var isEqual = text1.IsEqual(text2);  // 返回 true（忽略大小写）
var isNotEqual = text1.IsNotEqual(text2, false);  // 返回 true（区分大小写）

---

IsMatch / IsNotMatch

public static Result<bool> IsMatch(this string src, string des)
public static Result<bool> IsNotMatch(this string src, string dst)

功能说明: 使用通配符模式匹配字符串。

参数:

• src: 源字符串
• des / dst: 匹配模式（支持 * 和 ? 通配符）

返回值:

• IsMatch: 如果匹配，返回 true；否则返回 false
• IsNotMatch: 如果不匹配，返回 true；否则返回 false

异常: 无

使用示例:

string text = "hello world";
var result = text.IsMatch("hello*");  // 返回 true

---

IsGuid

public static Result<bool> IsGuid(this string src, out Guid result)

功能说明: 判断字符串是否为有效的 GUID 格式。

参数:

• src: 要检查的字符串
• result: 如果成功解析，输出解析后的 Guid 值

返回值: 如果是有效的 GUID 格式，返回 true；否则返回 false

异常:

• 当 src 为空或 null 时，返回 Error.Result 错误（包含 ArgumentNullException）

使用示例:

string guidStr = "550e8400-e29b-41d4-a716-446655440000";
if (guidStr.IsGuid(out Guid guid))
{
    // 使用解析后的 guid
}

---

IsEnglish

public static Result<bool> IsEnglish(this string src)

功能说明: 判断字符串是否全部为英文字母（包括空格和标点符号）。

参数:

• src: 要检查的字符串

返回值: 如果全部为英文字母、空格或标点符号，返回 true；否则返回 false

异常: 无

使用示例:

string text = "Hello World!";
var isEnglish = text.IsEnglish();  // 返回 true

---

IsChineseText / IsContainsChinese / IsContainsChineseCharacter

public static Result<bool> IsChineseText(this string src)
public static Result<bool> IsContainsChinese(this string src)
public static Result<bool> IsContainsChineseCharacter(this string src)

功能说明: 检查字符串中的中文字符。

参数:

• src: 要检查的字符串

返回值:

• IsChineseText: 如果全部为中文字符，返回 true；否则返回 false
• IsContainsChinese: 如果包含中文字符，返回 true；否则返回 false
• IsContainsChineseCharacter: 如果包含中文字符，返回 true；否则返回 false

异常:

• 当 src 为空或 null 时，返回 Error.Result 错误（包含 ArgumentNullException）

使用示例:

string text = "你好世界";
var isChinese = text.IsChineseText();  // 返回 true

string mixed = "Hello 世界";
var containsChinese = mixed.IsContainsChinese();  // 返回 true

---

IsContainsSpecialChars

public static Result<bool> IsContainsSpecialChars(this string src)
public static Result<bool> IsContainsSpecialChars(this string src, bool defaultsrc)

功能说明: 检测字符串中是否包含特殊字符（包括中文、日文、韩文等 CJK 字符和控制字符）。

参数:

• src: 要检查的字符串
• defaultsrc: 当字符串为空时的默认返回值（第二个重载）

返回值: 如果包含特殊字符，返回 true；否则返回 false

异常:

• 当 src 为空或 null 时，返回相应的错误或默认值

使用示例:

string text = "Hello 世界";
var hasSpecial = text.IsContainsSpecialChars();  // 返回 true

---

IsValidEmail

public static Result<bool> IsValidEmail(this string src)
public static Result<bool> IsValidEmail(this string src, bool defaultsrc)

功能说明: 验证 Email 地址是否合法。

参数:

• src: 要验证的 Email 地址
• defaultsrc: 当字符串为空时的默认返回值（第二个重载）

返回值: 如果是合法的 Email 地址，返回 true；否则返回 false

异常:

• 当 src 为空或 null 时，返回相应的错误或默认值

使用示例:

string email = "user@example.com";
var isValid = email.IsValidEmail();  // 返回 true

---

IsIpAddressValid

public static Result<bool> IsIpAddressValid(this string src)

功能说明: 验证 IP 地址是否合法。

参数:

• src: 要验证的 IP 地址

返回值: 如果是合法的 IPv4 地址，返回 true；否则返回 false

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当字符串长度不在 7-15 范围内时，返回 Error.OutofRange 错误

使用示例:

string ip = "192.168.1.1";
var isValid = ip.IsIpAddressValid();  // 返回 true

---

IsNumberValid / IsValidRealNumber / IsValidUNumber

public static Result<bool> IsNumberValid(this string src)
public static Result<bool> IsValidRealNumber(this string src)
public static Result<bool> IsValidUNumber(this string src)

功能说明: 验证字符串是否为有效的数字格式。

参数:

• src: 要验证的字符串

返回值:

• IsNumberValid: 如果是整数（可带正负号），返回 true；否则返回 false
• IsValidRealNumber: 如果是实数（可带小数点和正负号），返回 true；否则返回 false
• IsValidUNumber: 如果是正整数，返回 true；否则返回 false

异常:

• 当 src 为空或 null 时，返回相应的错误

使用示例:

string num1 = "123";
var isValid1 = num1.IsNumberValid();  // 返回 true

string num2 = "123.45";
var isValid2 = num2.IsValidRealNumber();  // 返回 true

string num3 = "-123";
var isValid3 = num3.IsValidUNumber();  // 返回 false（不是正数）

---

IsPathValid

public static Result<bool> IsPathValid(this string src)

功能说明: 验证字符串是否为有效的文件路径。

参数:

• src: 要验证的路径字符串

返回值: 如果是有效的路径格式，返回 true；否则返回 false

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当路径长度超过 250 时，返回 Error.Result 错误

使用示例:

string path = @"C:\Users\Documents\file.txt";
var isValid = path.IsPathValid();  // 返回 true

---

IsValidDateFormat

public static Result<bool> IsValidDateFormat(this string dateFormat, out DateTime datetime)

功能说明: 验证日期格式字符串是否有效。

参数:

• dateFormat: 日期格式字符串
• datetime: 如果格式有效，输出解析后的日期时间

返回值: 如果格式有效，返回 true；否则返回 false

异常:

• 当格式无效时，返回 Error.Result 错误

使用示例:

string format = "yyyy-MM-dd";
if (format.IsValidDateFormat(out DateTime dt))
{
    // 使用解析后的日期
}

---

IsBoolean / IsByte / IsChar / IsDecimal / IsDateTime / IsDouble / IsInt16 / IsInt32 / IsInt64 / IsSByte / IsUInt16 / IsUInt32 / IsUInt64 / IsSingle

public static Result<bool> IsBoolean(this string src, out bool des)
public static Result<bool> IsByte(this string src, out byte des)
public static Result<bool> IsChar(this string src, out char des)
public static Result<bool> IsDecimal(this string src, out decimal des)
public static Result<bool> IsDateTime(this string src, out DateTime des)
public static Result<bool> IsDouble(this string src, out double des)
public static Result<bool> IsInt16(this string src, out short des)
public static Result<bool> IsInt32(this string src, out int des)
public static Result<bool> IsInt64(this string src, out long des)
public static Result<bool> IsSByte(this string src, out sbyte des)
public static Result<bool> IsUInt16(this string src, out ushort des)
public static Result<bool> IsUInt32(this string src, out uint des)
public static Result<bool> IsUInt64(this string src, out ulong des)
public static Result<bool> IsSingle(this string src, out float result)

功能说明: 判断字符串是否可以转换为指定的类型，如果可以则输出转换后的值。

参数:

• src: 要检查的字符串
• des / result: 如果转换成功，输出转换后的值

返回值: 如果可以转换，返回 true；否则返回 false

异常:

• 当 src 为空或 null 时，返回 Error.Result 错误（包含 ArgumentNullException）

使用示例:

string text = "123";
if (text.IsInt32(out int value))
{
    // 使用转换后的值
}

string dateStr = "2023-12-25";
if (dateStr.IsDateTime(out DateTime date))
{
    // 使用转换后的日期
}

---

字符串查找方法

IndexOf

public static Result<int> IndexOf(this string src, char dst)
public static Result<int> IndexOf(this string src, string dst)
public static Result<int> IndexOf(this string src, char dst, CompareOptions options)
public static Result<int> IndexOf(this string src, string dst, CompareOptions options)
public static Result<int> IndexOf(this string src, char dst, int startIndex)
public static Result<int> IndexOf(this string src, string dst, int startIndex)
public static Result<int> IndexOf(this string src, char dst, int startIndex, CompareOptions options)
public static Result<int> IndexOf(this string src, string dst, int startIndex, CompareOptions options)
public static Result<int> IndexOf(this string src, char dst, int startIndex, int count)
public static Result<int> IndexOf(this string src, string dst, int startIndex, int count)
public static Result<int> IndexOf(this string src, char dst, int startIndex, int count, CompareOptions options)
public static Result<int> IndexOf(this string src, string dst, int startIndex, int count, CompareOptions options)

功能说明: 搜索指定的字符或字符串，并返回第一个匹配项的从零开始的索引。

参数:

• src: 源字符串
• dst: 要查找的字符或字符串
• options: 比较选项（可选）
• startIndex: 搜索的起始索引（可选）
• count: 要搜索的元素数量（可选）

返回值: 如果找到，返回第一个匹配项的索引；否则返回 -1

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当 startIndex 或 count 超出范围时，返回 Error.OutofRange 错误

使用示例:

string text = "Hello World";
var index = text.IndexOf('o');  // 返回 4
var index2 = text.IndexOf("World");  // 返回 6
var index3 = text.IndexOf('o', 5);  // 从索引 5 开始搜索，返回 7

---

LastIndexOf

public static Result<int> LastIndexOf(this string src, char dst)
public static Result<int> LastIndexOf(this string src, string dst)
public static Result<int> LastIndexOf(this string src, char dst, CompareOptions options)
public static Result<int> LastIndexOf(this string src, string dst, CompareOptions options)
public static Result<int> LastIndexOf(this string src, char dst, int startIndex)
public static Result<int> LastIndexOf(this string src, string dst, int startIndex)
public static Result<int> LastIndexOf(this string src, char dst, int startIndex, CompareOptions options)
public static Result<int> LastIndexOf(this string src, string dst, int startIndex, CompareOptions options)

功能说明: 搜索指定的字符或字符串，并返回最后一个匹配项的从零开始的索引。

参数:

• src: 源字符串
• dst: 要查找的字符或字符串
• options: 比较选项（可选）
• startIndex: 搜索的起始索引（可选）

返回值: 如果找到，返回最后一个匹配项的索引；否则返回 -1

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当 startIndex 超出范围时，返回 Error.OutofRange 错误

使用示例:

string text = "Hello World";
var index = text.LastIndexOf('o');  // 返回 7
var index2 = text.LastIndexOf("l");  // 返回 9

---

GetDigits / GetDigit

public static Result<int[]> GetDigits(this string src)
public static Result<int> GetDigit(this string src, int pos)

功能说明: 从字符串中提取数字。

参数:

• src: 源字符串
• pos: 要获取的数字位置（GetDigit）

返回值:

• GetDigits: 返回字符串中所有数字的数组
• GetDigit: 返回指定位置的数字

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当指定位置的字符不是数字时，返回 Error.Argument 错误

使用示例:

string text = "12345";
var digits = text.GetDigits();  // 返回 [1, 2, 3, 4, 5]
var digit = text.GetDigit(2);  // 返回 3

---

注意事项

1. 空值处理: 大部分方法对 null 字符串有特殊处理，会返回 Error.Empty 错误
2. 索引范围: 使用索引相关方法时，请确保索引在有效范围内
3. 编码: 字节数组转字符串时，默认使用 UTF8 编码
4. 异常处理: 所有方法返回 Result 类型，请检查 Successed 属性
5. 性能: 字符串操作可能涉及内存分配，请注意性能影响

---

第三部分：其他类型扩展方法

本文档详细说明 Hi.Ltd 类库中工具类 (Utilities) 的其他类型扩展方法，包括 DateTime、Boolean、Enum、Object 等类型的扩展方法。

本文档包含其他类型的扩展方法，按类型分组。

相关文档:

• 第一部分：数值类型扩展方法
• 第二部分：字符串扩展方法

DateTime 扩展方法

UnixEpoch

public static readonly DateTime UnixEpoch = new(1970, 1, 1);

功能说明: 标准时间基准值（Unix 时间戳的起始时间）。

返回值: DateTime 对象，表示 1970年1月1日

异常: 无

---

Nullable

public static Result<DateTime> Nullable(this DateTime? src)

功能说明: 将可空的 DateTime 转换为 Result<DateTime>。

参数:

• src: 可空的 DateTime 值

返回值: 如果有值，返回该值；否则返回 Error.Empty 错误

异常: 无

使用示例:

DateTime? date = DateTime.Now;
var result = date.Nullable();

---

ToDateTime

public static Result<DateTime> ToDateTime(this string src)

功能说明: 将字符串转换为 DateTime。

参数:

• src: 要转换的字符串

返回值: 转换后的 DateTime 值

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当字符串格式不正确时，返回 Error.Format 错误

使用示例:

string dateStr = "2023-12-25";
var result = dateStr.ToDateTime();

---

public static Result<DateTime> ToDateTime(this string src, IFormatProvider provider)

功能说明: 使用指定的格式提供程序将字符串转换为 DateTime。

参数:

• src: 要转换的字符串
• provider: 格式提供程序

返回值: 转换后的 DateTime 值

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误

---

public static Result<DateTime> ToDateTime(this int src)
public static Result<DateTime> ToDateTime(this uint src)
public static Result<DateTime> ToDateTime(this long src)
public static Result<DateTime> ToDateTime(this ulong src)
public static Result<DateTime> ToDateTime(this decimal src)

功能说明: 将数值类型转换为 DateTime（基于特定基准时间）。

参数:

• src: 要转换的数值

返回值: 转换后的 DateTime 值

异常:

• 当转换后的值超出 DateTime 范围时，返回 Error.OutofRange 错误

注意: 这些方法使用特定的基准时间（2022年3月6日）进行计算。

---

public static Result<DateTime> ToDateTime(this object src)

功能说明: 将对象转换为 DateTime（支持多种类型）。

参数:

• src: 要转换的对象（支持 DateTime、string、int、uint、long、ulong、decimal 等）

返回值: 转换后的 DateTime 值

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当类型无法解析时，返回 Error.Format 错误

---

UnixMillisecondsToDateTime

public static Result<DateTime> UnixMillisecondsToDateTime(this long source)

功能说明: 将 Unix 毫秒时间戳转换为 DateTime。

参数:

• source: Unix 毫秒时间戳

返回值: 转换后的 DateTime 值

异常: 无

使用示例:

long timestamp = 1672531200000;  // 2023-01-01 00:00:00 UTC
var result = timestamp.UnixMillisecondsToDateTime();

---

IsEqual

public static Result<bool> IsEqual(this DateTime src, DateTime dst, bool ignoreMonth = false, bool ignoreDay = false, bool ignoreHour = false, bool ignoreMinute = false, bool ignoreSecond = false, bool ignoreMillisecond = false)

功能说明: 比较两个 DateTime 是否相等，支持忽略指定的时间部分。

参数:

• src: 源日期时间
• dst: 目标日期时间
• ignoreMonth: 是否忽略月份及以下部分，默认为 false
• ignoreDay: 是否忽略天数及以下部分，默认为 false
• ignoreHour: 是否忽略小时及以下部分，默认为 false
• ignoreMinute: 是否忽略分钟及以下部分，默认为 false
• ignoreSecond: 是否忽略秒数及以下部分，默认为 false
• ignoreMillisecond: 是否忽略毫秒数及以下部分，默认为 false

返回值: 如果相等，返回 true；否则返回 false

异常: 无

使用示例:

DateTime date1 = new DateTime(2023, 12, 25, 10, 30, 45);
DateTime date2 = new DateTime(2023, 12, 25, 10, 30, 50);

// 只比较到分钟，忽略秒和毫秒
var result = date1.IsEqual(date2, ignoreSecond: true, ignoreMillisecond: true);  // 返回 true

---

Enum 扩展方法

ToEnum

public static Result<TEnum> ToEnum<TEnum>(this object src) where TEnum : Enum

功能说明: 将目标对象转换为等效的枚举成员。

类型参数:

• TEnum: 要返回的枚举类型

参数:

• src: 要转换为枚举成员的值（支持字符串、数值等）

返回值: 值为 src 的枚举对象

异常:

• 当目标类型不是枚举类型时，返回 Error.Format 错误
• 当值不在枚举范围内时，返回 Error.OutofRange 错误
• 当类型转换失败时，返回 Error.Result 错误

使用示例:

// 通过字符串名称转换
var result = "Monday".ToEnum<DayOfWeek>();

// 通过数值转换
var result2 = 1.ToEnum<DayOfWeek>();

// 通过描述属性转换（如果枚举成员有 DescriptionAttribute）
var result3 = "星期一".ToEnum<DayOfWeek>();

注意:

• 支持通过枚举成员名称转换
• 支持通过枚举成员的 DescriptionAttribute 描述值转换
• 支持通过数值转换

---

ToDescription

public static Result<string> ToDescription(this Enum src)

功能说明: 获取枚举成员对应的描述信息（从 DescriptionAttribute 获取）。

参数:

• src: 目标枚举项

返回值: 如果枚举成员有 DescriptionAttribute，返回描述信息；否则返回 Error.Empty 错误

异常:

• 当 src 为空时，返回 Error.Empty 错误
• 当枚举成员没有 DescriptionAttribute 时，返回 Error.Empty 错误

使用示例:

public enum Status
{
    [Description("正常")]
    Normal,
    [Description("异常")]
    Abnormal
}

var desc = Status.Normal.ToDescription();  // 返回 "正常"

---

Boolean 扩展方法

IsRunningOnMono

public static Result<bool> IsRunningOnMono { get; }

功能说明: 用于检测当前运行环境是否为 Mono。

返回值:

• true: 当前运行在 Mono 环境
• false: 当前运行在 .NET Framework 环境

异常: 无

---

ToBoolean

public static Result<bool> ToBoolean(this object src)

功能说明: 将对象转换为 Boolean 类型。

参数:

• src: 要转换的对象（支持多种类型）

返回值: 转换后的 Boolean 值

异常:

• 当 src 为空或 null 时，返回 Error.Result 错误（包含 ArgumentNullException）
• 当没有可匹配的转换方式时，返回 Error.Result 错误（包含 ArgumentException）

使用示例:

// 从字符串转换
var result1 = "true".ToBoolean();

// 从数值转换
var result2 = 1.ToBoolean();  // 非零为 true
var result3 = 0.ToBoolean();  // 零为 false

// 从枚举转换
var result4 = MyEnum.Value.ToBoolean();

注意: ToBoolean 方法有大量重载，支持从各种类型转换：

• 基本数值类型（int, long, double 等）
• 字符串类型
• 枚举类型
• Result<T> 类型
• 数组类型（通过 ToBooleans 方法）

---

IsNullOrEmpty

public static Result<bool> IsNullOrEmpty<T>(this T src)

功能说明: 指示指定的对象是否为 null 或者 Empty。

类型参数:

• T: 对象类型

参数:

• src: 要测试的对象

返回值:

• true: 如果为 null 或者 Empty
• false: 否则

异常: 无

使用示例:

string text = null;
var result = text.IsNullOrEmpty();  // 返回 true

int[] array = new int[0];
var result2 = array.IsNullOrEmpty();  // 返回 true

List<string> list = null;
var result3 = list.IsNullOrEmpty();  // 返回 true

注意: 支持多种类型的空值检查：

• 字符串（检查长度是否为 0）
• 数组（检查长度是否为 0）
• 集合（检查 Count 是否为 0）
• 可空类型（检查是否为 null）
• 枚举（检查是否为默认值）
• DBNull

---

IsNotNullOrEmpty

public static Result<bool> IsNotNullOrEmpty<T>(this T src)

功能说明: 指示指定的对象是否不为 null 且不为 Empty。

类型参数:

• T: 对象类型

参数:

• src: 要测试的对象

返回值:

• true: 如果不为 null 且不为 Empty
• false: 否则

异常: 无

使用示例:

string text = "Hello";
var result = text.IsNotNullOrEmpty();  // 返回 true

---

IsEven / IsOdd

public static Result<bool> IsEven(this int src)
public static Result<bool> IsEven(this uint src)
public static Result<bool> IsEven(this long src)
public static Result<bool> IsEven(this ulong src)
public static Result<bool> IsEven(this short src)
public static Result<bool> IsEven(this ushort src)
public static Result<bool> IsEven(this byte src)
public static Result<bool> IsEven(this sbyte src)
public static Result<bool> IsEven(this float src)
public static Result<bool> IsEven(this double src)
public static Result<bool> IsEven(this decimal src)
public static Result<bool> IsEven(this object src)

public static Result<bool> IsOdd(this int src)
public static Result<bool> IsOdd(this uint src)
public static Result<bool> IsOdd(this long src)
public static Result<bool> IsOdd(this ulong src)
public static Result<bool> IsOdd(this short src)
public static Result<bool> IsOdd(this ushort src)
public static Result<bool> IsOdd(this object src)

功能说明: 判断数值是否为偶数或奇数。

参数:

• src: 目标数值

返回值:

• IsEven: 如果是偶数，返回 true；否则返回 false
• IsOdd: 如果是奇数，返回 true；否则返回 false

异常: 无

使用示例:

int value = 10;
var isEven = value.IsEven();  // 返回 true
var isOdd = value.IsOdd();    // 返回 false

---

IsNullableType

public static Result<bool> IsNullableType(this Type type)

功能说明: 判断指定的类型是否为可空类型。

参数:

• type: 要检查的类型

返回值:

• true: 如果是可空类型
• false: 否则

异常:

• 当 type 为 null 时，返回 Error.Argument 错误

使用示例:

Type nullableInt = typeof(int?);
var result = nullableInt.IsNullableType();  // 返回 true

Type normalInt = typeof(int);
var result2 = normalInt.IsNullableType();   // 返回 false

---

类型检查方法

以下方法用于检查类型是否为特定的数值类型：

public static Result<bool> IsBoolean(this Type type)
public static Result<bool> IsByte(this Type type)
public static Result<bool> IsSByte(this Type type)
public static Result<bool> IsChar(this Type type)
public static Result<bool> IsUInt16(this Type type)
public static Result<bool> IsInt16(this Type type)
public static Result<bool> IsUInt32(this Type type)
public static Result<bool> IsInt32(this Type type)
public static Result<bool> IsInt64(this Type type)

功能说明: 检查类型是否为指定的数值类型。

参数:

• type: 要检查的类型

返回值: 如果是指定的类型，返回 true；否则返回 false

异常: 无

使用示例:

Type intType = typeof(int);
var isInt = intType.IsInt32();  // 返回 true

Type stringType = typeof(string);
var isInt2 = stringType.IsInt32();  // 返回 false

---

IsNumeric

public static Result<bool> IsNumeric<T>(this T src)

功能说明: 判断对象是否为数值类型。

类型参数:

• T: 对象类型

参数:

• src: 要检查的对象

返回值: 如果是数值类型（sbyte, short, int, long, byte, ushort, uint, ulong, float, double, decimal），返回 true；否则返回 false

异常:

• 当 src 为 null 时，返回 Error.Result 错误（包含 ArgumentNullException）

使用示例:

int value = 100;
var result = value.IsNumeric();  // 返回 true

string text = "hello";
var result2 = text.IsNumeric();  // 返回 false

---

IsGuid

public static Result<bool> IsGuid(this string src, out Guid result)

功能说明: 判断字符串是否为有效的 GUID 格式。

参数:

• src: 要检查的字符串
• result: 如果成功解析，输出解析后的 Guid 值

返回值: 如果是有效的 GUID 格式，返回 true；否则返回 false

异常:

• 当 src 为空或 null 时，返回 Error.Result 错误（包含 ArgumentNullException）

使用示例:

string guidStr = "550e8400-e29b-41d4-a716-446655440000";
if (guidStr.IsGuid(out Guid guid))
{
    // 使用解析后的 guid
}

---

IsInfinity

public static Result<bool> IsInfinity(this double src)
public static Result<bool> IsInfinity(this float src)

功能说明: 判断浮点数是否为无穷大（正无穷或负无穷）。

参数:

• src: 要检查的浮点数

返回值: 如果是无穷大，返回 true；否则返回 false

异常: 无

使用示例:

double value = double.PositiveInfinity;
var result = value.IsInfinity();  // 返回 true

---

IsList

public static Result<bool> IsList<T>(this T src)

功能说明: 判断对象是否为列表类型（实现了 IList 或 IList<T> 接口）。

类型参数:

• T: 对象类型

参数:

• src: 要检查的对象

返回值: 如果是列表类型，返回 true；否则返回 false

异常:

• 当 src 为 null 时，返回 Error.Empty 错误

使用示例:

List<int> list = new List<int>();
var result = list.IsList();  // 返回 true

int[] array = new int[10];
var result2 = array.IsList();  // 返回 true

---

IsMatch / IsNotMatch

public static Result<bool> IsMatch(this string src, string des)
public static Result<bool> IsNotMatch(this string src, string dst)

功能说明: 使用通配符模式匹配字符串。

参数:

• src: 源字符串
• des / dst: 匹配模式（支持 * 和 ? 通配符）

返回值:

• IsMatch: 如果匹配，返回 true；否则返回 false
• IsNotMatch: 如果不匹配，返回 true；否则返回 false

异常: 无

使用示例:

string text = "hello world";
var result = text.IsMatch("hello*");  // 返回 true
var result2 = text.IsMatch("world*");  // 返回 false

注意:

• * 匹配任意多个字符
• ? 匹配单个字符

---

IsOct

public static Result<bool> IsOct(this int src)

功能说明: 判断整数的字符串表示是否全部为八进制数字（0-7）。

参数:

• src: 要检查的整数

返回值: 如果所有数字都在 0-7 范围内，返回 true；否则返回 false

异常: 无

使用示例:

int value = 12345;  // 包含 8 和 9
var result = value.IsOct();  // 返回 false

int value2 = 12345;  // 如果转换为字符串后只包含 0-7
var result2 = value2.IsOct();  // 返回 false（因为包含 8）

---

Object 扩展方法

GetRequiredService

public static object GetRequiredService(this IServiceProvider provider, Type serviceType)

功能说明: 从服务提供程序获取必需的服务。

参数:

• provider: 服务提供程序
• serviceType: 服务类型

返回值: 服务对象；如果服务不存在，返回 INTPTR_NULL

异常: 无

使用示例:

var service = serviceProvider.GetRequiredService(typeof(IMyService));

---

CreateInstance

public static object CreateInstance(this Type type, params object[] args)

功能说明: 创建指定类型的实例。

参数:

• type: 要创建实例的类型
• args: 构造函数参数（可选）

返回值: 创建的实例对象

异常:

• InvalidOperationException: 当找不到合适的构造函数时
• ArgumentException: 当参数不正确时
• MissingMethodException: 当找不到适合的构造函数时
• Exception: 当发生未知错误时

使用示例:

Type myType = typeof(MyClass);
var instance = myType.CreateInstance();

// 带参数
var instance2 = myType.CreateInstance("param1", 123);

注意:

• 如果未传入参数，则选择参数个数最少的构造函数
• 如果构造函数参数有可选参数，会自动使用默认值

---

IsApplicationSingleton

public static Result<bool> IsApplicationSingleton()

功能说明: 检查应用程序是否以单例模式运行。

返回值:

• true: 如果应用程序是单例实例（只有一个进程）
• false: 否则

异常: 无

使用示例:

var isSingleton = Utilities.IsApplicationSingleton();
if (!isSingleton.Content)
{
    // 应用程序已在运行
}

---

其他扩展方法

Contains (Result<string>)

public static Result<bool> Contains(this Result<string> src, string target)

功能说明: 返回一个值，该值指示指定的子串是否出现在此字符串中。

参数:

• src: 目标对象（Result<string>）
• target: 子对象值

返回值: 如果 target 参数出现在此字符串中，返回 true；否则为 false

异常:

• 当 src 为空或失败时，返回相应的错误
• 当 target 为空或 null 时，返回 Error.Result 错误（包含 ArgumentNullException）

---

StartsWith (Result<string>)

public static Result<bool> StartsWith(this Result<string> src, string target)

功能说明: 确定指定结果字符串的内容是否以给定的目标字符串开头。

参数:

• src: 包含源字符串的结果对象
• target: 要与源字符串开头比较的字符串

返回值: 如果源字符串以目标字符串开头，返回 true；否则返回 false

异常:

• 当 src 为空或失败时，返回相应的错误
• 当 target 为空或 null 时，返回 Error.Result 错误（包含 ArgumentNullException）

使用示例:

Result<string> result = "Hello World";
var starts = result.StartsWith("Hello");  // 返回 true

---

EndsWith (Result<string>)

public static Result<bool> EndsWith(this Result<string> src, string target)

功能说明: 确定指定结果字符串的内容是否以给定的目标字符串结尾。

参数:

• src: 包含源字符串的结果对象
• target: 要与源字符串结尾比较的字符串

返回值: 如果源字符串以目标字符串结尾，返回 true；否则返回 false

异常:

• 当 src 为空或失败时，返回相应的错误
• 当 target 为空或 null 时，返回 Error.Result 错误（包含 ArgumentNullException）

---

Equals (Enum)

public static Result<bool> Equals(this Enum src, Enum des)
public static Result<bool> Equals(this Enum src, string defaultflag)

功能说明: 比较两个枚举值是否相等。

参数:

• src: 源枚举值
• des 或 defaultflag: 目标枚举值或字符串标志

返回值: 如果相等，返回 true；否则返回 false

异常:

• 当 defaultflag 为空或 null 时，返回 Error.Result 错误（包含 ArgumentNullException）

---

注意事项

1. 类型转换: 大部分转换方法支持多种输入类型，会自动选择合适的转换方式
2. 空值处理: 所有方法对 null 值有特殊处理，会返回相应的错误
3. 异常处理: 所有方法返回 Result 类型，请检查 Successed 属性
4. 性能: 某些转换操作可能涉及反射，请注意性能影响
5. 枚举转换: ToEnum 方法支持通过名称、描述属性或数值进行转换

---

注意: 由于文档内容较多，更多扩展方法请查看 第三部分（续）：其他类型扩展方法

---

第三部分（续）：其他类型扩展方法

本文档是 第三部分：其他类型扩展方法 的续篇，包含更多其他类型的扩展方法。

本文档包含第三部分中未包含的其他类型扩展方法，按功能分组。

相关文档:

• 第一部分：数值类型扩展方法
• 第二部分：字符串扩展方法
• 第三部分：其他类型扩展方法

Boolean 扩展方法（续）

GetBoolean

public static Result<bool> GetBoolean(this bool[] src, int index = 0)
public static Result<bool> GetBoolean(this object src, int index = 0)

功能说明: 从布尔数组或对象中获取指定索引位置的布尔值。

参数:

• src: 源数据（布尔数组或对象）
• index: 索引位置，默认为 0

返回值: 指定位置的布尔值

异常:

• 当 src 为空或 null 时，返回 Error.Result 错误（包含 ArgumentNullException）
• 当 index 超出范围时，返回 Error.Result 错误（包含 ArgumentOutOfRangeException）

使用示例:

bool[] bools = { true, false, true };
var result = bools.GetBoolean(1);  // 返回 false

// 从对象获取（支持多种类型）
int value = 5;
var boolValue = value.GetBoolean(0);  // 从整数获取布尔值

---

GetBooleans

public static Result<bool[]> GetBooleans(this bool src)
public static Result<bool[]> GetBooleans(this byte src)
public static Result<bool[]> GetBooleans(this sbyte src)
public static Result<bool[]> GetBooleans(this char src)
public static Result<bool[]> GetBooleans(this short src)
public static Result<bool[]> GetBooleans(this ushort src)
public static Result<bool[]> GetBooleans(this int src)
public static Result<bool[]> GetBooleans(this uint src)
public static Result<bool[]> GetBooleans(this long src)
public static Result<bool[]> GetBooleans(this ulong src)
public static Result<bool[]> GetBooleans(this float src)
public static Result<bool[]> GetBooleans(this double src)
public static Result<bool[]> GetBooleans(this decimal src)
public static Result<bool[]> GetBooleans(this object src)

功能说明: 将各种类型的值转换为布尔数组（按位拆分）。

参数:

• src: 源数据（支持多种数值类型和对象）

返回值: 转换后的布尔数组

异常:

• 当 src 为空或 null 时，返回相应的错误

使用示例:

byte value = 0x0F;  // 二进制: 00001111
var bools = value.GetBooleans();  // 返回 [true, true, true, true, false, false, false, false]

int intValue = 5;
var intBools = intValue.GetBooleans();  // 返回 32 个布尔值（按位拆分）

---

ToBooleans

public static Result<bool[]> ToBooleans(this bool[] src)
public static Result<bool[]> ToBooleans(this byte[] src)
public static Result<bool[]> ToBooleans(this sbyte[] src)
public static Result<bool[]> ToBooleans(this char[] src)
public static Result<bool[]> ToBooleans(this short[] src)
public static Result<bool[]> ToBooleans(this ushort[] src)
public static Result<bool[]> ToBooleans(this int[] src)
public static Result<bool[]> ToBooleans(this uint[] src)
public static Result<bool[]> ToBooleans(this long[] src)
public static Result<bool[]> ToBooleans(this ulong[] src)
public static Result<bool[]> ToBooleans(this float[] src)
public static Result<bool[]> ToBooleans(this double[] src)
public static Result<bool[]> ToBooleans(this decimal[] src)
public static Result<bool[]> ToBooleans(this string[] src)
public static Result<bool[]> ToBooleans(this Enum[] src)
public static Result<bool[]> ToBooleans(this object src)

功能说明: 将各种类型的数组转换为布尔数组。

参数:

• src: 源数组（支持多种类型）

返回值: 转换后的布尔数组

异常:

• 当 src 为空或 null 时，返回 Error.Result 错误（包含 ArgumentNullException）
• 当没有可匹配的转换方式时，返回 Error.Result 错误（包含 ArgumentException）

使用示例:

byte[] bytes = { 0x0F, 0xF0 };
var bools = bytes.ToBooleans();  // 将每个字节转换为布尔数组

int[] ints = { 1, 0, 5 };
var intBools = ints.ToBooleans();  // 将每个整数转换为布尔数组

---

ToBoolean (带索引)

public static Result<bool> ToBoolean(this object src, int index)

功能说明: 从对象数组中获取指定索引位置的布尔值。

参数:

• src: 源对象（支持多种数组类型）
• index: 索引位置

返回值: 指定位置的布尔值

异常:

• 当 src 为空或 null 时，返回 Error.Result 错误（包含 ArgumentNullException）
• 当 index 超出范围时，返回相应的错误
• 当没有可匹配的转换方式时，返回 Error.Result 错误（包含 ArgumentException）

使用示例:

int[] ints = { 1, 0, 5 };
var boolValue = ints.ToBoolean(0);  // 返回 true（非零为 true）

string[] strings = { "true", "false", "yes" };
var strBool = strings.ToBoolean(1);  // 返回 false

---

IsNullOrContainsNull

public static Result<bool> IsNullOrContainsNull<T>(this ICollection<T> src)

功能说明: 检查集合是否为 null 或包含 null 元素。

类型参数:

• T: 集合元素类型

参数:

• src: 要检查的集合

返回值:

• true: 如果集合为 null 或包含 null 元素
• false: 否则

异常: 无

使用示例:

List<string> list = new List<string> { "a", null, "b" };
var result = list.IsNullOrContainsNull();  // 返回 true

List<int> intList = new List<int> { 1, 2, 3 };
var result2 = intList.IsNullOrContainsNull();  // 返回 false

---

IsNullOrEmpty (Array)

public static Result<bool> IsNullOrEmpty(this Array src)

功能说明: 检查数组是否为 null 或为空（包括多维数组）。

参数:

• src: 要检查的数组

返回值:

• true: 如果数组为 null 或为空（任何维度长度为 0）
• false: 否则

异常: 无

使用示例:

int[] array = new int[0];
var result = array.IsNullOrEmpty();  // 返回 true

int[,] multiArray = new int[0, 0];
var result2 = multiArray.IsNullOrEmpty();  // 返回 true

---

IsEqual (Array)

public static Result<bool> IsEqual<T>(this T[] src, T[] dst, int start1, int start2, int length)
public static Result<bool> IsEqual<T>(this T[] src, T[] dst, ref Dictionary<int, T> diff)

功能说明: 比较两个数组是否相等。

类型参数:

• T: 数组元素类型

参数:

• src: 第一个数组
• dst: 第二个数组
• start1: 第一个数组的起始索引
• start2: 第二个数组的起始索引
• length: 要比较的长度
• diff: 输出参数，包含不相等元素的索引和值（第二个重载）

返回值: 如果相等，返回 true；否则返回 false

异常:

• 当 src 或 dst 为空时，返回 Error.Result 错误（包含 ArgumentNullException）
• 当索引或长度超出范围时，返回 Error.Result 错误（包含 ArgumentOutOfRangeException）

使用示例:

int[] array1 = { 1, 2, 3, 4, 5 };
int[] array2 = { 0, 0, 1, 2, 3 };
var result = array1.IsEqual(array2, 0, 2, 3);  // 比较 array1[0-2] 和 array2[2-4]

// 带差异输出
Dictionary<int, int> diff = new Dictionary<int, int>();
var isEqual = array1.IsEqual(array2, ref diff);  // diff 包含不相等的位置

---

Byte 扩展方法（续）

FromBase64String

public static Result<byte[]> FromBase64String(this string src)

功能说明: 将 Base64 编码的字符串转换为字节数组。

参数:

• src: Base64 编码的字符串

返回值: 解码后的字节数组

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当字符串格式不正确时，返回 Error.Format 错误

使用示例:

string base64 = "SGVsbG8gV29ybGQ=";  // "Hello World" 的 Base64
var bytes = base64.FromBase64String();  // 返回字节数组

---

HexToBytes

public static Result<byte[]> HexToBytes(this string hex)

功能说明: 将十六进制字符串转换为字节数组。

参数:

• hex: 十六进制字符串

返回值: 转换后的字节数组

异常:

• 当 hex 为空或 null 时，返回 Error.Empty 错误
• 当字符串格式不正确时，返回 Error.Format 错误

使用示例:

string hex = "48656C6C6F";  // "Hello" 的十六进制
var bytes = hex.HexToBytes();  // 返回 [0x48, 0x65, 0x6C, 0x6C, 0x6F]

---

GetBytes (String)

public static Result<byte[]> GetBytes(this string src)
public static Result<byte[]> GetBytes(this string src, Encoding encoding)

功能说明: 将字符串转换为字节数组。

参数:

• src: 源字符串
• encoding: 字符编码（可选，默认使用 UTF-8）

返回值: 转换后的字节数组

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误

使用示例:

string text = "Hello";
var bytes = text.GetBytes();  // 使用 UTF-8 编码
var bytes2 = text.GetBytes(Encoding.ASCII);  // 使用 ASCII 编码

---

ToByte (String)

public static Result<byte> ToByte(this string src)
public static Result<byte> ToByte(this string src, IFormatProvider provider)

功能说明: 将字符串转换为字节值。

参数:

• src: 源字符串
• provider: 格式提供程序（可选）

返回值: 转换后的字节值

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当字符串无法转换为字节时，返回 Error.Format 错误

使用示例:

string text = "255";
var byteValue = text.ToByte();  // 返回 255

---

ToBytes (String Array)

public static Result<byte[]> ToBytes(this string[] src)
public static Result<byte[]> ToBytes(this string[] src, IFormatProvider provider)

功能说明: 将字符串数组转换为字节数组。

参数:

• src: 源字符串数组
• provider: 格式提供程序（可选）

返回值: 转换后的字节数组

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当字符串无法转换时，返回相应的错误

使用示例:

string[] strings = { "1", "2", "3" };
var bytes = strings.ToBytes();  // 返回 [1, 2, 3]

---

GetByte (Enum / Object)

public static Result<byte> GetByte(this Enum src, int index = 0)
public static Result<byte> GetByte(this object src, int index = 0)

功能说明: 从枚举值或对象中获取指定索引位置的字节。

参数:

• src: 源数据（枚举值或对象）
• index: 字节索引位置，默认为 0

返回值: 指定位置的字节值

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当 index 超出范围时，返回 Error.OutofRange 错误

使用示例:

MyEnum value = MyEnum.Value1;
var byte0 = value.GetByte(0);  // 获取枚举值的第一个字节

---

GetBytes (Enum / Object)

public static Result<byte[]> GetBytes(this Enum src)
public static Result<byte[]> GetBytes(this object src)

功能说明: 将枚举值或对象转换为字节数组。

参数:

• src: 源数据（枚举值或对象）

返回值: 转换后的字节数组

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误

使用示例:

MyEnum value = MyEnum.Value1;
var bytes = value.GetBytes();  // 将枚举值转换为字节数组

---

ToByte (Enum / Object)

public static Result<byte> ToByte(this Enum src)
public static Result<byte> ToByte(this object src)

功能说明: 将枚举值或对象转换为字节值。

参数:

• src: 源数据（枚举值或对象）

返回值: 转换后的字节值

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当值超出字节范围时，返回 Error.OutofRange 错误

使用示例:

MyEnum value = MyEnum.Value1;
var byteValue = value.ToByte();  // 将枚举值转换为字节

---

ToBytes (Enum Array / Object)

public static Result<byte[]> ToBytes(this Enum[] src)
public static Result<byte[]> ToBytes(this object src)

功能说明: 将枚举数组或对象转换为字节数组。

参数:

• src: 源数据（枚举数组或对象）

返回值: 转换后的字节数组

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误

使用示例:

MyEnum[] enums = { MyEnum.Value1, MyEnum.Value2 };
var bytes = enums.ToBytes();  // 将枚举数组转换为字节数组

---

ToCompress / ToDecompress

public static Result<byte[]> ToCompress(this byte[] src)
public static Result<byte[]> ToDecompress(this byte[] src)

功能说明: 压缩或解压缩字节数组（使用 GZip 压缩算法）。

参数:

• src: 源字节数组

返回值:

• ToCompress: 压缩后的字节数组
• ToDecompress: 解压缩后的字节数组

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当解压缩失败时（数据格式不正确），返回相应的错误

使用示例:

byte[] data = { 0x48, 0x65, 0x6C, 0x6C, 0x6F };
var compressed = data.ToCompress();  // 压缩数据

// 解压缩
var decompressed = compressed.ToDecompress();  // 恢复原始数据

---

ToEncryptByte

public static Result<byte> ToEncryptByte(this byte src, byte key)

功能说明: 使用简单的 XOR 加密算法对字节进行加密。

参数:

• src: 要加密的字节
• key: 加密密钥

返回值: 加密后的字节

异常: 无

使用示例:

byte data = 0x48;
byte key = 0x0F;
var encrypted = data.ToEncryptByte(key);  // 加密字节

---

Double 扩展方法（续）

ToDouble (String)

public static Result<double> ToDouble(this string src)
public static Result<double> ToDouble(this string src, IFormatProvider provider)

功能说明: 将字符串转换为双精度浮点数。

参数:

• src: 源字符串
• provider: 格式提供程序（可选）

返回值: 转换后的双精度浮点数

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当字符串格式不正确时，返回 Error.Format 错误

使用示例:

string text = "123.456";
var value = text.ToDouble();  // 返回 123.456

---

ToDoubles (String Array)

public static Result<double[]> ToDoubles(this string[] src)

功能说明: 将字符串数组转换为双精度浮点数数组。

参数:

• src: 源字符串数组

返回值: 转换后的双精度浮点数数组

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当字符串无法转换时，返回相应的错误

使用示例:

string[] strings = { "1.1", "2.2", "3.3" };
var doubles = strings.ToDoubles();  // 返回 [1.1, 2.2, 3.3]

---

GetDouble (Object)

public static Result<double> GetDouble(this object src, int index = 0)

功能说明: 从对象中获取指定索引位置的双精度浮点数。

参数:

• src: 源对象
• index: 索引位置，默认为 0

返回值: 指定位置的双精度浮点数

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当 index 超出范围时，返回 Error.OutofRange 错误

使用示例:

double[] doubles = { 1.1, 2.2, 3.3 };
var value = doubles.GetDouble(1);  // 返回 2.2

---

BitArray 扩展方法

ToBitArray

public static Result<BitArray> ToBitArray(this bool src)
public static Result<BitArray> ToBitArray(this bool[] src)
public static Result<BitArray> ToBitArray(this Enum src)
public static Result<BitArray> ToBitArray(this object src)

功能说明: 将各种类型转换为 BitArray。

参数:

• src: 源数据（布尔值、布尔数组、枚举值或对象）

返回值: 转换后的 BitArray

异常:

• 当 src 为空或 null 时，返回相应的错误

使用示例:

bool value = true;
var bitArray = value.ToBitArray();  // 转换为 BitArray

byte[] bytes = { 0x0F };
var bitArray2 = bytes.ToBitArray();  // 将字节数组转换为 BitArray

---

Array 扩展方法

Index

public static Result<int> Index<T>(this T[] values, T src, int startIndex, int count)

功能说明: 在数组中查找指定元素的索引。

类型参数:

• T: 数组元素类型

参数:

• values: 要搜索的数组
• src: 要查找的元素
• startIndex: 搜索的起始索引
• count: 要搜索的元素数量

返回值: 如果找到，返回元素的索引；否则返回 -1

异常:

• 当 values 或 src 为空时，返回 Error.Empty 错误
• 当 startIndex 或 count 超出范围时，返回 Error.OutofRange 错误

使用示例:

int[] array = { 1, 2, 3, 4, 5 };
var index = array.Index(3, 0, 5);  // 返回 2

---

IndexOf

public static Result<int> IndexOf<T>(this T[] src, T[] dst, int index) where T : struct

功能说明: 在数组中查找子数组的起始位置（使用 KMP 算法）。

类型参数:

• T: 数组元素类型（必须是值类型）

参数:

• src: 源数组
• dst: 要查找的子数组
• index: 搜索的起始索引

返回值: 如果找到，返回子数组的起始索引；否则返回 -1

异常: 无

使用示例:

byte[] data = { 0x01, 0x02, 0x03, 0x04, 0x05 };
byte[] pattern = { 0x03, 0x04 };
var index = data.IndexOf(pattern, 0);  // 返回 2

---

Type 扩展方法

IsList (Type)

public static Result<bool> IsList(this Type type)

功能说明: 判断类型是否为 List<T> 类型。

参数:

• type: 要检查的类型

返回值: 如果是 List<T> 类型，返回 true；否则返回 false

异常: 无

使用示例:

Type listType = typeof(List<int>);
var isList = listType.IsList();  // 返回 true

---

IsDictionary

public static Result<bool> IsDictionary(this Type type)

功能说明: 判断类型是否为 Dictionary<TKey, TValue> 类型。

参数:

• type: 要检查的类型

返回值: 如果是 Dictionary<TKey, TValue> 类型，返回 true；否则返回 false

异常: 无

使用示例:

Type dictType = typeof(Dictionary<string, int>);
var isDict = dictType.IsDictionary();  // 返回 true

---

IsValid

public static Result<bool> IsValid<T>(this T src)

功能说明: 验证对象是否有效（不为 null、不为默认值、不为空字符串、不为空数组等）。

类型参数:

• T: 对象类型

参数:

• src: 要验证的对象

返回值:

• true: 如果对象有效
• false: 如果对象为 null、默认值、空字符串、空数组或 DBNull

异常: 无

使用示例:

string text = "Hello";
var isValid = text.IsValid();  // 返回 true

string empty = "";
var isValid2 = empty.IsValid();  // 返回 false

int[] array = { 1, 2, 3 };
var isValid3 = array.IsValid();  // 返回 true

---

Char 扩展方法

GetCharList

public static Result<List<char>> GetCharList(this int src)
public static Result<List<char>> GetCharList(this uint src)
public static Result<List<char>> GetCharList(this long src)
public static Result<List<char>> GetCharList(this ulong src)
public static Result<List<char>> GetCharList(this float src)
public static Result<List<char>> GetCharList(this double src)
public static Result<List<char>> GetCharList(this decimal src)
public static Result<List<char>> GetCharList(this object src)

功能说明: 将数值类型转换为字符列表（将数字的每一位转换为字符）。

参数:

• src: 源数值（支持多种数值类型）

返回值: 转换后的字符列表

异常:

• 当 src 为空或 null 时，返回相应的错误
• 当类型无法解析时，返回 Error.Format 错误

使用示例:

int number = 12345;
var chars = number.GetCharList();  // 返回 ['1', '2', '3', '4', '5']

---

GetHexValue

public static Result<char> GetHexValue(int numeric, bool isuppercase = true)

功能说明: 获取指定数值对应的十六进制字符。

参数:

• numeric: 数值（0-15）
• isuppercase: 是否使用大写字母，默认为 true

返回值: 对应的十六进制字符（0-9 或 A-F/a-f）

异常:

• 当 numeric 超出 0-15 范围时，返回 Error.OutofRange 错误

使用示例:

var hexChar = Utilities.GetHexValue(10, true);  // 返回 'A'
var hexChar2 = Utilities.GetHexValue(10, false);  // 返回 'a'

---

GetASCCIIChars

public static Result<char[]> GetASCCIIChars(this byte[] src)

功能说明: 将字节数组转换为 ASCII 字符数组。

参数:

• src: 源字节数组

返回值: 转换后的 ASCII 字符数组

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误

使用示例:

byte[] bytes = { 0x48, 0x65, 0x6C, 0x6C, 0x6F };
var chars = bytes.GetASCCIIChars();  // 返回 ['H', 'e', 'l', 'l', 'o']

---

Guid 扩展方法

IsNullOrEmpty / IsNotNullOrEmpty

public static Result<bool> IsNullOrEmpty(this Guid? src)
public static Result<bool> IsNullOrEmpty(this Guid src)
public static Result<bool> IsNotNullOrEmpty(this Guid? src)
public static Result<bool> IsNotNullOrEmpty(this Guid src)

功能说明: 检查 GUID 是否为 null 或空值（Guid.Empty）。

参数:

• src: 要检查的 GUID

返回值:

• IsNullOrEmpty: 如果为 null 或 Guid.Empty，返回 true；否则返回 false
• IsNotNullOrEmpty: 如果不为 null 且不为 Guid.Empty，返回 true；否则返回 false

异常: 无

使用示例:

Guid? guid = null;
var isEmpty = guid.IsNullOrEmpty();  // 返回 true

Guid guid2 = Guid.Empty;
var isEmpty2 = guid2.IsNullOrEmpty();  // 返回 true

---

Dictionary 扩展方法

IsNullOrEmpty / IsNotNullOrEmpty

public static Result<bool> IsNullOrEmpty<TKey, TValue>(this Dictionary<TKey, TValue> src)
public static Result<bool> IsNotNullOrEmpty<TKey, TValue>(this Dictionary<TKey, TValue> src)

功能说明: 检查字典是否为 null 或为空。

类型参数:

• TKey: 键类型
• TValue: 值类型

参数:

• src: 要检查的字典

返回值:

• IsNullOrEmpty: 如果为 null 或元素数量为 0，返回 true；否则返回 false
• IsNotNullOrEmpty: 如果不为 null 且元素数量大于 0，返回 true；否则返回 false

异常: 无

使用示例:

Dictionary<string, int> dict = null;
var isEmpty = dict.IsNullOrEmpty();  // 返回 true

Dictionary<string, int> dict2 = new Dictionary<string, int>();
var isEmpty2 = dict2.IsNullOrEmpty();  // 返回 true

---

IPAddress 扩展方法

ToIPAddress

public static Result<IPAddress> ToIPAddress(this string src)
public static Result<IPAddress> ToIPAddress(this byte[] src)
public static Result<IPAddress> ToIPAddress(this uint src)

功能说明: 将字符串、字节数组或无符号整数转换为 IP 地址。

参数:

• src: 源数据（字符串、字节数组或 uint）

返回值: 转换后的 IP 地址

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误
• 当字符串格式不正确时，返回 Error.Result 错误
• 当字节数组长度不正确时，返回 Error.Result 错误（包含 ArgumentException）

使用示例:

string ipStr = "192.168.1.1";
var ip = ipStr.ToIPAddress();  // 返回 IPAddress 对象

byte[] ipBytes = { 192, 168, 1, 1 };
var ip2 = ipBytes.ToIPAddress();  // 从字节数组创建 IP 地址

uint ipUint = 0xC0A80101;  // 192.168.1.1
var ip3 = ipUint.ToIPAddress();  // 从 uint 创建 IP 地址

---

GetBytes (IPAddress)

public static Result<byte[]> GetBytes(this IPAddress src)

功能说明: 将 IP 地址转换为字节数组。

参数:

• src: 源 IP 地址

返回值: IP 地址的字节数组表示

异常: 无

使用示例:

IPAddress ip = IPAddress.Parse("192.168.1.1");
var bytes = ip.GetBytes();  // 返回 [192, 168, 1, 1]

---

IntPtr / UIntPtr 扩展方法

ToIntPtr

public static Result<IntPtr> ToIntPtr(UIntPtr src)

功能说明: 将 UIntPtr 转换为 IntPtr。

参数:

• src: 源 UIntPtr 值

返回值: 转换后的 IntPtr

异常: 无

使用示例:

UIntPtr uptr = new UIntPtr(100);
var iptr = Utilities.ToIntPtr(uptr);  // 返回 IntPtr

---

ToUIntPtr

public static Result<UIntPtr> ToUIntPtr(this IntPtr src)

功能说明: 将 IntPtr 转换为 UIntPtr。

参数:

• src: 源 IntPtr 值

返回值: 转换后的 UIntPtr

异常: 无

使用示例:

IntPtr iptr = new IntPtr(100);
var uptr = iptr.ToUIntPtr();  // 返回 UIntPtr

---

IsHandleValid

public static Result<bool> IsHandleValid(this IntPtr handle)

功能说明: 检查句柄是否有效（不为零且不为无效句柄值）。

参数:

• handle: 要检查的句柄

返回值: 如果句柄有效，返回 true；否则返回 false

异常: 无

使用示例:

IntPtr handle = GetSomeHandle();
var isValid = handle.IsHandleValid();  // 检查句柄是否有效

---

DataTable 扩展方法

ToDataTable

public static DataTable ToDataTable<T>(this IEnumerable<T> collection)

功能说明: 将集合转换为 DataTable。

类型参数:

• T: 集合元素类型

参数:

• collection: 要转换的集合

返回值: 转换后的 DataTable（列名和类型从集合元素的属性获取）

异常: 无

使用示例:

List<Person> people = new List<Person>
{
    new Person { Name = "John", Age = 30 },
    new Person { Name = "Jane", Age = 25 }
};
var table = people.ToDataTable();  // 转换为 DataTable

---

String 扩展方法（续）

FindChineseCharacters

public static Result<Dictionary<int, string>> FindChineseCharacters(this string src)

功能说明: 查找字符串中的所有中文字符及其位置。

参数:

• src: 源字符串

返回值: 包含中文字符位置和字符的字典（键为位置索引，值为中文字符）

异常:

• 当 src 为空或 null 时，返回 Error.Empty 错误

使用示例:

string text = "Hello 世界 World";
var chinese = text.FindChineseCharacters();  // 返回 { 6: "世", 7: "界" }

---

注意事项

1. 类型转换: 大部分转换方法支持多种输入类型，会自动选择合适的转换方式
2. 空值处理: 所有方法对 null 值有特殊处理，会返回相应的错误
3. 异常处理: 所有方法返回 Result 类型，请检查 Successed 属性
4. 性能: 某些转换操作可能涉及反射或数组操作，请注意性能影响
5. 编码: 字符串转字节数组的方法支持指定编码，默认使用 UTF-8
6. IP 地址: IP 地址转换支持 IPv4 格式（4 字节）
7. 句柄: 句柄验证方法用于检查 Windows 句柄是否有效

---

安全加密 (Security) API

AesUtils 类

类说明

提供 AES 加密解密操作方法。

静态方法

GetAesKey

public static byte[] GetAesKey()

功能说明: 获取默认 AES 密钥。

参数: 无

返回值: 返回默认的 AES 密钥字节数组（128位）

异常: 无

使用示例:

byte[] key = AesUtils.GetAesKey();

---

GetAesIV

public static byte[] GetAesIV()

功能说明: 获取默认 AES 初始化向量（IV）。

参数: 无

返回值: 返回默认的 AES IV 字节数组（128位）

异常: 无

使用示例:

byte[] iv = AesUtils.GetAesIV();

---

GenAesKeyAndIV

public static Result<byte[], byte[]> GenAesKeyAndIV()

功能说明: 生成一组 AES 的密钥和向量值。

参数: 无

返回值: 返回包含密钥和 IV 的元组结果

• Item1: AES 密钥（128位）
• Item2: AES 初始化向量（128位）

异常: 无

使用示例:

var keyIv = AesUtils.GenAesKeyAndIV();
if (keyIv.Successed)
{
    byte[] key = keyIv.Item1;
    byte[] iv = keyIv.Item2;
}

---

扩展方法

ToAes (加密)

public static Result<string> ToAes(this string plainText, byte[] key, byte[] iv)

功能说明: 采用 AES 技术对字符串进行加密。

参数:

• plainText: 要加密的明文内容
• key: AES 密钥（128位）
• iv: AES 初始化向量（128位）

返回值: 返回加密后的 Base64 编码字符串

异常:

• 当 key 或 iv 长度不正确时，可能抛出 CryptographicException
• 当加密过程失败时，返回包含异常信息的错误结果

使用示例:

string plainText = "Hello World";
byte[] key = AesUtils.GetAesKey();
byte[] iv = AesUtils.GetAesIV();
var encrypted = plainText.ToAes(key, iv);
if (encrypted.Successed)
{
    string cipherText = encrypted;
}

---

public static Result<string> ToAes(this Result<string> plainText, byte[] key, byte[] iv)

功能说明: 对结果类中的字符串进行 AES 加密。

参数:

• plainText: 包含要加密字符串的结果类
• key: AES 密钥（128位）
• iv: AES 初始化向量（128位）

返回值: 返回加密后的 Base64 编码字符串

异常:

• 当 plainText 失败时，返回相应的错误结果
• 当加密过程失败时，返回包含异常信息的错误结果

---

FromAes (解密)

public static Result<string> FromAes(this string plainText, byte[] key, byte[] iv)

功能说明: 采用 AES 技术对字符串进行解密。

参数:

• plainText: 要解密的 Base64 编码密文
• key: AES 密钥（128位）
• iv: AES 初始化向量（128位）

返回值: 返回解密后的明文字符串

异常:

• 当 key 或 iv 长度不正确时，可能抛出 CryptographicException
• 当密文格式不正确时，可能抛出 FormatException
• 当解密过程失败时，返回包含异常信息的错误结果

使用示例:

string cipherText = "加密后的字符串";
byte[] key = AesUtils.GetAesKey();
byte[] iv = AesUtils.GetAesIV();
var decrypted = cipherText.FromAes(key, iv);
if (decrypted.Successed)
{
    string plainText = decrypted;
}

---

public static Result<string> FromAes(this Result<string> plainText, byte[] key, byte[] iv)

功能说明: 对结果类中的字符串进行 AES 解密。

参数:

• plainText: 包含要解密字符串的结果类
• key: AES 密钥（128位）
• iv: AES 初始化向量（128位）

返回值: 返回解密后的明文字符串

异常:

• 当 plainText 失败时，返回相应的错误结果
• 当解密过程失败时，返回包含异常信息的错误结果

---

RsaUtils 类

类说明

提供 RSA 加密解密操作方法。

静态属性

GenerateKeys

public static Result<string, string> GenerateKeys { get; }

功能说明: 生成 RSA 的密钥对（公钥和私钥）。

参数: 无

返回值: 返回包含公钥和私钥的元组结果

• Item1: RSA 公钥（XML 格式字符串）
• Item2: RSA 私钥（XML 格式字符串）

异常:

• 当密钥生成失败时，返回包含异常信息的错误结果

使用示例:

var keyPair = RsaUtils.GenerateKeys;
if (keyPair.Successed)
{
    string publicKey = keyPair.Item1;
    string privateKey = keyPair.Item2;
}

---

扩展方法

ToRSA (加密)

public static Result<string> ToRSA(this string source, string key)

功能说明: 对目标字符串进行 RSA 加密。

参数:

• source: 要加密的目标字符串
• key: RSA 公钥（XML 格式字符串）

返回值: 返回加密后的 Base64 编码字符串

异常:

• 当 source 为空时，返回 Error.Empty 错误
• 当 key 为空时，返回 Error.Empty 错误
• 当密钥格式不正确时，可能抛出 CryptographicException
• 当加密过程失败时，返回包含异常信息的错误结果

使用示例:

string plainText = "Hello World";
var keyPair = RsaUtils.GenerateKeys;
if (keyPair.Successed)
{
    var encrypted = plainText.ToRSA(keyPair.Item1);
    if (encrypted.Successed)
    {
        string cipherText = encrypted;
    }
}

---

FromRSA (解密)

public static Result<string> FromRSA(this string source, string src)

功能说明: 对目标字符串进行 RSA 解密。

参数:

• source: 要解密的 Base64 编码密文
• src: RSA 私钥（XML 格式字符串）

返回值: 返回解密后的明文字符串

异常:

• 当 source 为空时，返回 Error.Empty 错误
• 当密钥格式不正确时，可能抛出 CryptographicException
• 当密文格式不正确时，可能抛出 FormatException
• 当解密过程失败时，返回包含异常信息的错误结果

使用示例:

string cipherText = "加密后的字符串";
var keyPair = RsaUtils.GenerateKeys;
if (keyPair.Successed)
{
    var decrypted = cipherText.FromRSA(keyPair.Item2);
    if (decrypted.Successed)
    {
        string plainText = decrypted;
    }
}

---

SM3Utils 类

类说明

SM3Utils 提供 国密 SM3 密码杂凑算法（GB/T 32905-2016）的纯托管实现，输出 32 字节（256 bit）摘要，无第三方原生密码库依赖。

静态方法（摘要）

方法	说明
ComputeHash(byte[] data)	对完整缓冲区计算 SM3
ComputeHash(byte[] data, int offset, int count)	对指定区段计算 SM3
ToHexString(byte[] digest)	摘要转 小写 十六进制字符串（空数组得到空串）

使用示例

using System.Text;
using Hi.Ltd.Security;

byte[] h = SM3Utils.ComputeHash(Encoding.UTF8.GetBytes("abc"));
string hex = SM3Utils.ToHexString(h);

---

HmacSm3Utils 类

类说明

HmacSm3Utils 实现 HMAC-SM3（RFC 2104 结构 + SM3 杂凑），输出 32 字节。与 SM4Utils 的认证封装配合时采用 Encrypt-then-MAC（先加密再算 MAC，验证 MAC 后再解密）。

常量

名称	值	说明
BlockSize	64	HMAC 块宽（与 SM3 分组一致）
TagSize	32	MAC 长度（字节）

静态方法（摘要）

方法	说明
ComputeHash(byte[] key, byte[] data)	标准 HMAC-SM3
ComputeHash(byte[] key, int keyOffset, int keyLength, byte[] data, int dataOffset, int dataLength)	区段版本；超长密钥会先经 SM3 压缩到块宽

---

SM2Utils 类

类说明

SM2Utils 提供 国密 SM2 椭圆曲线数字签名（GB/T 32918.2，曲线 sm2p256v1），配合 SM3 与 Z_A 预处理。签名为 64 字节 r‖s（各 32 字节大端）。实现细节与侧信道、密钥清零等限制见类型 XML 注释；高对抗场景请评估 HSM / 原生国密模块。

常量与默认用户标识

名称	说明
DefaultUserIdAscii	userId 为 null 或 空 时采用的默认标识（ASCII「1234567812345678」，与 RFC 8998 / OpenSSL 行为一致）
ScalarSize	32；私钥、坐标、域元素字节长度
PublicKeyUncompressedSize	64；非压缩公钥 X‖Y
SignatureSize	64；签名 r‖s
MaxMessageByteCount	单条消息最大长度上界（与 SM4Utils.MaxPlaintextByteCount 对齐）

静态方法（摘要）

方法	说明
GetPublicKey(byte[] d)	由 32 字节私钥导出 64 字节公钥 X‖Y
ComputeZa(byte[] userId, byte[] publicKeyXy64)	计算 Z<sub>A</sub>（SM3 预处理）
ComputeSignDigest(byte[] userId, byte[] publicKeyXy64, byte[] message)	待签名字段 e = SM3(Z<sub>A</sub> ‖ M)
Sign(byte[] privateKeyD, byte[] userId, byte[] message)	签名（内部推导公钥）
Sign(byte[] privateKeyD, byte[] userId, byte[] publicKeyXy64, byte[] message)	已持有公钥时可避免重复点乘
Verify(byte[] publicKeyXy64, byte[] userId, byte[] message, byte[] signature)	验签；signature 为 64 字节 r‖s
SignatureToDer / SignatureFromDer	原始签名与 DER（SEQUENCE{INTEGER r, INTEGER s}）互转，便于与 OpenSSL、Java BC 等互通

使用示例

using System.Text;
using Hi.Ltd.Security;

byte[] d = new byte[32];
d[30] = 0xA1;
d[31] = 0x3B;
var uid = Encoding.UTF8.GetBytes("interop-user");
var msg = Encoding.UTF8.GetBytes("sm2 roundtrip message");
byte[] sig = SM2Utils.Sign(d, uid, msg);
byte[] pub = SM2Utils.GetPublicKey(d);
bool ok = SM2Utils.Verify(pub, uid, msg, sig);
byte[] der = SM2Utils.SignatureToDer(sig);

---

SM3Helper 说明

SM3Helper 位于 Hi.Ltd.Security，为 SM3/SM2 内部实现保留的辅助类型，无对外可用的 public 方法。应用代码请统一使用 SM3Utils（及 SM2Utils / HmacSm3Utils）。

---

SM4Utils 类

类说明

SM4Utils 提供 国密 SM4 分组密码（GB/T 32907-2016）的纯托管实现：块长与密钥均为 16 字节；支持单块加解密、ECB/CBC（PKCS#7 填充）、随机 IV 的 CBC（IV ‖ 密文），以及与 HMAC-SM3 组合的 Encrypt-then-MAC（IV ‖ 密文 ‖ Tag(32)）。单独 SM4 不提供完整性保护，对外传输或落盘敏感数据请优先使用 EncryptCbcWithRandomIvAndHmacSm3 / DecryptCbcWithPrefixedIvAndHmacSm3。

常量

名称	值	说明
BlockSize	16	分组字节长度
KeySize	16	密钥字节长度
MaxPlaintextByteCount	64 MiB	单条明文最大长度上界
HmacSm3Utils.TagSize	32	认证封装末尾 MAC 长度（字节）

静态方法（摘要）

方法	说明
EncryptBlock / DecryptBlock	单分组 16 字节明/密文
EncryptEcb / DecryptEcb	ECB + PKCS#7（易暴露模式，仅协议要求或极短随机块时使用）
EncryptCbc / DecryptCbc	CBC + PKCS#7，iv 须 16 字节
EncryptCbcWithRandomIv	生成随机 IV，返回 IV(16) ‖ 密文
DecryptCbcWithPrefixedIv	与上式配对解密
EncryptCbcWithRandomIvAndHmacSm3	EtM：返回 IV ‖ 密文 ‖ HMAC-SM3
DecryptCbcWithPrefixedIvAndHmacSm3	先校验 MAC 再解密

EncryptCbcWithRandomIv

public static byte[] EncryptCbcWithRandomIv(byte[] key, byte[] plaintext)

功能说明: 使用密码学安全随机数生成 16 字节 IV，以 SM4-CBC + PKCS#7 加密明文，返回 IV ‖ 密文（前 16 字节为 IV）。

参数:

• key: SM4 密钥，必须为 16 字节
• plaintext: 明文；长度受 MaxPlaintextByteCount 限制

返回值: 字节数组 IV(16) ‖ ciphertext

异常: 参数非法、长度越界时抛出 ArgumentException / ArgumentNullException

使用示例:

byte[] key = new byte[SM4Utils.KeySize]; /* 由安全模块填充 */
byte[] plain = System.Text.Encoding.UTF8.GetBytes("data");
byte[] payload = SM4Utils.EncryptCbcWithRandomIv(key, plain);

---

DecryptCbcWithPrefixedIv

public static byte[] DecryptCbcWithPrefixedIv(byte[] key, byte[] ivAndCiphertext)

功能说明: 与 EncryptCbcWithRandomIv 配对；入参为 IV ‖ 密文，总长度须 至少 32 字节且为 16 的倍数。

返回值: 解密后的明文字节（已去除 PKCS#7 填充）

使用示例:

byte[] plain = SM4Utils.DecryptCbcWithPrefixedIv(key, payload);

---

EncryptCbcWithRandomIvAndHmacSm3

public static byte[] EncryptCbcWithRandomIvAndHmacSm3(byte[] sm4Key, byte[] macKey, byte[] plaintext)

功能说明: Encrypt-then-MAC：随机 IV + SM4-CBC 密文 + HMAC-SM3（32 字节）。输出为 IV(16) ‖ 密文 ‖ Tag(32)；MAC 计算对象为 IV ‖ 密文。macKey 与 sm4Key 应 独立管理。

使用示例:

byte[] sm4Key = new byte[SM4Utils.KeySize];
byte[] macKey = System.Text.Encoding.UTF8.GetBytes("separate-mac-secret-32bytes!!");
byte[] plain = System.Text.Encoding.UTF8.GetBytes("payload");
byte[] envelope = SM4Utils.EncryptCbcWithRandomIvAndHmacSm3(sm4Key, macKey, plain);

---

DecryptCbcWithPrefixedIvAndHmacSm3

public static byte[] DecryptCbcWithPrefixedIvAndHmacSm3(byte[] sm4Key, byte[] macKey, byte[] payload)

功能说明: 与 EncryptCbcWithRandomIvAndHmacSm3 配对；先验证 HMAC-SM3，再解密。入参为完整 IV ‖ 密文 ‖ Tag。

使用示例:

byte[] plain = SM4Utils.DecryptCbcWithPrefixedIvAndHmacSm3(sm4Key, macKey, envelope);

---

注意事项（SM4）

1. 密钥与 IV: SM4 密钥及 CBC 用 IV 均为 16 字节；随机 IV 由 EncryptCbcWithRandomIv* 内部生成，勿复用固定全零 IV 承载多条不同语义的消息。
2. 完整性: 仅 CBC/ECB 不防篡改；对外信道或不可信存储请使用 EncryptCbcWithRandomIvAndHmacSm3。
3. ECB: 相同明文块得到相同密文块，易泄露模式；除非协议强制，否则优先 CBC 或带 MAC 的 CBC。
4. 合规与侧信道: 本实现为 纯托管表驱动 S 盒；极高对抗模型下存在缓存计时等理论风险，强合规场景请评估硬件密码模块或国密加速方案。

---

AesGcmUtils / AesGcmHelper（.NET 8+）

源码位于 Security 目录，类型定义在命名空间 Hi.Ltd（与 AesUtils 并列），仅在 #if NET8_0_OR_GREATER 目标下编译。AesGcmUtils 与 AesGcmHelper 为同一思路的入口（历史命名并存），使用 12 字节随机 nonce 与 16 字节认证标签，Encrypt 返回 (cipherText, tag, nonce)，Decrypt 入参为密文、标签、nonce 与密钥。

---

Md5Utils 类

类说明

提供 MD5 哈希计算方法。

扩展方法

ToMd5

public static Result<string> ToMd5(this string source)

功能说明: 计算字符串的 MD5 值。

参数:

• source: 目标字符串

返回值: 返回一个 128 位（16 字节）的散列值（32 位十六进制字符串）

异常:

• 当 source 为空时，返回包含 ArgumentNullException 的错误结果
• 当哈希计算失败时，返回包含异常信息的错误结果

使用示例:

string text = "Hello World";
var md5 = text.ToMd5();
if (md5.Successed)
{
    string hash = md5;  // 例如: "B10A8DB164E0754105B7A99BE72E3FE5"
}

---

GetMD5Hash

public static Result<string> GetMD5Hash(this string path)

功能说明: 计算文件的 MD5 值。

参数:

• path: 文件路径

返回值: 返回文件的 MD5 散列值（32 位十六进制字符串）

异常:

• 当文件不存在时，可能抛出 FileNotFoundException
• 当文件无法访问时，可能抛出 IOException
• 当没有文件访问权限时，可能抛出 UnauthorizedAccessException
• 当哈希计算失败时，返回包含异常信息的错误结果

使用示例:

string filePath = @"C:\file.txt";
var md5 = filePath.GetMD5Hash();
if (md5.Successed)
{
    string hash = md5;
}

---

使用示例

AES 加密解密完整示例

using Hi.Ltd;

// 生成密钥和 IV
var keyIv = AesUtils.GenAesKeyAndIV();
if (!keyIv.Successed) return;

byte[] key = keyIv.Item1;
byte[] iv = keyIv.Item2;

// 加密
string plainText = "Hello World";
var encrypted = plainText.ToAes(key, iv);
if (!encrypted.Successed) return;

string cipherText = encrypted;
Console.WriteLine($"加密后: {cipherText}");

// 解密
var decrypted = cipherText.FromAes(key, iv);
if (!decrypted.Successed) return;

string decryptedText = decrypted;
Console.WriteLine($"解密后: {decryptedText}");

RSA 加密解密完整示例

using Hi.Ltd;

// 生成密钥对
var keyPair = RsaUtils.GenerateKeys;
if (!keyPair.Successed) return;

string publicKey = keyPair.Item1;
string privateKey = keyPair.Item2;

// 加密
string plainText = "Hello World";
var encrypted = plainText.ToRSA(publicKey);
if (!encrypted.Successed) return;

string cipherText = encrypted;
Console.WriteLine($"加密后: {cipherText}");

// 解密
var decrypted = cipherText.FromRSA(privateKey);
if (!decrypted.Successed) return;

string decryptedText = decrypted;
Console.WriteLine($"解密后: {decryptedText}");

国密 SM2 / SM3 / SM4 综合示例

using System.Security.Cryptography;
using System.Text;
using Hi.Ltd.Security;

// SM3 摘要（「abc」向量可与 OpenSSL sm3 / BC 对照）
byte[] sm3 = SM3Utils.ComputeHash(Encoding.UTF8.GetBytes("abc"));
string sm3Hex = SM3Utils.ToHexString(sm3);

// HMAC-SM3（常与 SM4 EtM 组合；独立使用时注意密钥长度与存储）
byte[] hmacKey = Encoding.UTF8.GetBytes("mac-key-at-least-32-bytes-long!!");
byte[] mac = HmacSm3Utils.ComputeHash(hmacKey, Encoding.UTF8.GetBytes("payload"));

// SM2 签名验签（私钥须合法；此处与仓库回归用例一致）
byte[] d = new byte[32];
d[30] = 0xA1;
d[31] = 0x3B;
var uid = Encoding.UTF8.GetBytes("interop-user");
var msg = Encoding.UTF8.GetBytes("sm2 roundtrip message");
byte[] sig = SM2Utils.Sign(d, uid, msg);
byte[] pub = SM2Utils.GetPublicKey(d);
bool sm2Ok = SM2Utils.Verify(pub, uid, msg, sig);

// SM4：随机 IV + CBC，以及带 HMAC-SM3 的认证加密
byte[] sm4Key = new byte[SM4Utils.KeySize];
RandomNumberGenerator.Fill(sm4Key);
byte[] plain = Encoding.UTF8.GetBytes("Hello SM4");
byte[] wrapped = SM4Utils.EncryptCbcWithRandomIv(sm4Key, plain);
byte[] back = SM4Utils.DecryptCbcWithPrefixedIv(sm4Key, wrapped);
byte[] macKey = Encoding.UTF8.GetBytes("mac-key-at-least-32-bytes-long!!");
byte[] env = SM4Utils.EncryptCbcWithRandomIvAndHmacSm3(sm4Key, macKey, plain);
byte[] opened = SM4Utils.DecryptCbcWithPrefixedIvAndHmacSm3(sm4Key, macKey, env);

MD5 哈希示例

using Hi.Ltd;

// 字符串 MD5
string text = "Hello World";
var md5 = text.ToMd5();
if (md5.Successed)
{
    Console.WriteLine($"MD5: {md5}");
}

// 文件 MD5
string filePath = @"C:\file.txt";
var fileMd5 = filePath.GetMD5Hash();
if (fileMd5.Successed)
{
    Console.WriteLine($"文件 MD5: {fileMd5}");
}

注意事项

1. 密钥管理:

   • AES 密钥和 IV 必须妥善保管
   • RSA 私钥绝对不能泄露
   • 建议使用安全的密钥存储方案

2. 数据长度:

   • AES 可以加密任意长度的数据
   • RSA 加密的数据长度受密钥长度限制（4096位密钥最多加密约 501 字节）

3. 性能考虑:

   • AES 加密解密速度快，适合大量数据
   • RSA 加密解密速度较慢，适合小量数据或用于加密 AES 密钥

4. 安全性:

   • MD5 已不再安全，仅用于校验，不建议用于密码加密
   • 建议使用 SHA256 或更安全的哈希算法
   • SM4：对称保密；需完整性时请使用 EncryptCbcWithRandomIvAndHmacSm3，勿单独依赖 ECB/CBC 防篡改

---

HTTP 请求 (Https) API

HttpBase 抽象类

类说明

HttpBase 是 HTTP 请求的基类，提供了基础的 HTTP 客户端和 URI 管理功能。

属性

Client

public HttpClient Client { get; set; }

功能说明: HttpClient 实例，用于发起 HTTP 请求。

返回值: HttpClient 实例

异常: 无

使用示例:

var httpBase = new HttpClientHelper();
httpBase.Client.Timeout = TimeSpan.FromSeconds(30);

---

RequestUriString

public virtual string RequestUriString { get; set; }

功能说明: 标识 Internet 资源的 URI。

返回值: URI 字符串

异常: 无

使用示例:

var httpBase = new HttpClientHelper();
httpBase.RequestUriString = "https://api.example.com/data";

---

抽象方法

Get

public abstract Result<string> Get()

功能说明: 发起 GET 请求并返回结果。

参数: 无

返回值: 返回 HTTP 响应的字符串内容

异常:

• 可能抛出网络相关异常，但会被捕获并返回 Error.Result

使用示例:

var httpClient = HttpClientHelper.Create;
httpClient.RequestUriString = "https://api.example.com/data";
var result = httpClient.Get();
if (result.Successed)
{
    Console.WriteLine(result);
}

---

public abstract Result<string> Get(string requestUriString)

功能说明: 发起 GET 请求并返回结果，指定 URI。

参数:

• requestUriString: 请求的 URI 地址

返回值: 返回 HTTP 响应的字符串内容

异常:

• 当 requestUriString 为空时，返回 Error.Empty 错误
• 可能抛出网络相关异常，但会被捕获并返回 Error.Result

使用示例:

var httpClient = HttpClientHelper.Create;
var result = httpClient.Get("https://api.example.com/data");

---

Post

public abstract Result<string> Post(string content)

功能说明: 发起 POST 请求并返回结果。

参数:

• content: POST 请求的内容（通常是 JSON 字符串）

返回值: 返回 HTTP 响应的字符串内容

异常:

• 可能抛出网络相关异常，但会被捕获并返回 Error.Result

使用示例:

var httpClient = HttpClientHelper.Create;
httpClient.RequestUriString = "https://api.example.com/data";
var json = "{\"name\":\"test\",\"value\":123}";
var result = httpClient.Post(json);

---

public abstract Result<string> Post(string requestUriString, string content)

功能说明: 发起 POST 请求并返回结果，指定 URI。

参数:

• requestUriString: 请求的 URI 地址
• content: POST 请求的内容（通常是 JSON 字符串）

返回值: 返回 HTTP 响应的字符串内容

异常:

• 当 requestUriString 为空时，返回 Error.Empty 错误
• 可能抛出网络相关异常，但会被捕获并返回 Error.Result

使用示例:

var httpClient = HttpClientHelper.Create;
var json = "{\"name\":\"test\",\"value\":123}";
var result = httpClient.Post("https://api.example.com/data", json);

---

方法

Dispose

public void Dispose()

功能说明: 释放 HttpClient 资源。

参数: 无

返回值: 无

异常: 无

使用示例:

using (var httpClient = HttpClientHelper.Create)
{
    var result = httpClient.Get("https://api.example.com/data");
}

---

HttpClientHelper 类

类说明

HttpClientHelper 是基于 HttpClient 的 HTTP 请求实现类，使用现代的 HttpClient API。

静态属性

Create

public static IHttps Create { get; }

功能说明: 创建 HttpClientHelper 实例的工厂方法。

返回值: IHttps 接口实例

异常: 无

使用示例:

var httpClient = HttpClientHelper.Create;

---

方法

Get

public override Result<string> Get()

功能说明: 使用 HttpClient 发起 GET 请求并返回结果。

参数: 无

返回值: 返回 HTTP 响应的字符串内容

异常:

• 当网络请求失败时，返回 Error.Result 错误
• 当 HTTP 状态码表示错误时，会抛出 HttpRequestException，但会被捕获并返回错误

使用示例:

var httpClient = HttpClientHelper.Create;
httpClient.RequestUriString = "https://api.example.com/data";
var result = httpClient.Get();
if (result.Successed)
{
    Console.WriteLine(result);
}

---

public override Result<string> Get(string requestUriString)

功能说明: 使用 HttpClient 发起 GET 请求并返回结果，指定 URI。

参数:

• requestUriString: 请求的 URI 地址

返回值: 返回 HTTP 响应的字符串内容

异常:

• 当网络请求失败时，返回 Error.Result 错误

使用示例:

var httpClient = HttpClientHelper.Create;
var result = httpClient.Get("https://api.example.com/data");

---

Post

public override Result<string> Post(string content)

功能说明: 使用 HttpClient 发起 POST 请求并返回结果。

参数:

• content: POST 请求的内容（JSON 字符串，UTF-8 编码）

返回值: 返回 HTTP 响应的字符串内容

异常:

• 当网络请求失败时，返回 Error.Result 错误

使用示例:

var httpClient = HttpClientHelper.Create;
httpClient.RequestUriString = "https://api.example.com/data";
var json = "{\"name\":\"test\",\"value\":123}";
var result = httpClient.Post(json);

---

public override Result<string> Post(string requestUriString, string content)

功能说明: 使用 HttpClient 发起 POST 请求并返回结果，指定 URI。

参数:

• requestUriString: 请求的 URI 地址
• content: POST 请求的内容（JSON 字符串，UTF-8 编码）

返回值: 返回 HTTP 响应的字符串内容

异常:

• 当网络请求失败时，返回 Error.Result 错误

使用示例:

var httpClient = HttpClientHelper.Create;
var json = "{\"name\":\"test\",\"value\":123}";
var result = httpClient.Post("https://api.example.com/data", json);

---

特性说明:

• 自动设置 Accept 头为 application/json
• 使用 UTF-8 编码
• 自动检查 HTTP 状态码，失败时抛出异常

---

HttpWebRequestUtils 类

类说明

HttpWebRequestUtils 是基于 HttpWebRequest 的 HTTP 请求实现类，使用传统的 HttpWebRequest API。

静态属性

Create

public static IHttps Create { get; }

功能说明: 创建 HttpWebRequestUtils 实例的工厂方法。

返回值: IHttps 接口实例

异常: 无

使用示例:

var httpClient = HttpWebRequestUtils.Create;

---

方法

Get

public override Result<string> Get()

功能说明: 使用 HttpWebRequest 从 URI 地址获取结果字符串信息。

参数: 无

返回值: 返回 URI 传递回来的字符串信息

异常:

• 当 RequestUriString 为空时，返回 Error.Empty 错误
• 当网络请求失败时，返回 Error.Result 错误

使用示例:

var httpClient = HttpWebRequestUtils.Create;
httpClient.RequestUriString = "https://api.example.com/data";
var result = httpClient.Get();

---

public override Result<string> Get(string requestUri)

功能说明: 使用 HttpWebRequest 从 URI 地址获取结果字符串信息，指定 URI。

参数:

• requestUri: 标识 Internet 资源的 URI

返回值: 返回 URI 传递回来的字符串信息

异常:

• 当 requestUri 为空时，返回 Error.Empty 错误
• 当网络请求失败时，返回 Error.Result 错误

使用示例:

var httpClient = HttpWebRequestUtils.Create;
var result = httpClient.Get("https://api.example.com/data");

---

Post

public override Result<string> Post(string content)

功能说明: 使用 HttpWebRequest 发起 POST 请求并返回结果。

参数:

• content: POST 请求的内容（字符串，UTF-8 编码）

返回值: 返回 HTTP 响应的字符串内容

异常:

• 当 RequestUriString 为空时，返回 Error.Empty 错误
• 当网络请求失败时，返回 Error.Result 错误

使用示例:

var httpClient = HttpWebRequestUtils.Create;
httpClient.RequestUriString = "https://api.example.com/data";
var json = "{\"name\":\"test\",\"value\":123}";
var result = httpClient.Post(json);

---

public override Result<string> Post(string requestUri, string content)

功能说明: 使用 HttpWebRequest 发起 POST 请求并返回结果，指定 URI。

参数:

• requestUri: 标识 Internet 资源的 URI
• content: POST 请求的内容（字符串，UTF-8 编码）

返回值: 返回 HTTP 响应的字符串内容

异常:

• 当 requestUri 为空时，返回 Error.Empty 错误
• 当网络请求失败时，返回 Error.Result 错误

使用示例:

var httpClient = HttpWebRequestUtils.Create;
var json = "{\"name\":\"test\",\"value\":123}";
var result = httpClient.Post("https://api.example.com/data", json);

---

特性说明:

• 使用 HTTP/1.0 协议
• 设置 User-Agent 为 "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.2; .NET CLR 1.0.3705;)"
• 禁用 KeepAlive
• ContentType 和 Accept 都设置为 application/json

---

使用示例

基本 GET 请求

using Hi.Ltd.Https;

// 使用 HttpClientHelper
var httpClient = HttpClientHelper.Create;
httpClient.RequestUriString = "https://api.example.com/data";
var result = httpClient.Get();

if (result.Successed)
{
    Console.WriteLine($"响应内容: {result}");
}
else
{
    Console.WriteLine($"请求失败: {result.Message}");
}

带 URI 的 GET 请求

var httpClient = HttpClientHelper.Create;
var result = httpClient.Get("https://api.example.com/data");

基本 POST 请求

var httpClient = HttpClientHelper.Create;
httpClient.RequestUriString = "https://api.example.com/data";

var json = "{\"name\":\"test\",\"value\":123}";
var result = httpClient.Post(json);

if (result.Successed)
{
    Console.WriteLine($"响应内容: {result}");
}

带 URI 的 POST 请求

var httpClient = HttpClientHelper.Create;
var json = "{\"name\":\"test\",\"value\":123}";
var result = httpClient.Post("https://api.example.com/data", json);

使用 HttpWebRequestUtils

var httpClient = HttpWebRequestUtils.Create;
var result = httpClient.Get("https://api.example.com/data");

自定义 HttpClient 配置

var httpClient = HttpClientHelper.Create;
httpClient.Client.Timeout = TimeSpan.FromSeconds(60);
httpClient.Client.DefaultRequestHeaders.Add("Authorization", "Bearer token");
var result = httpClient.Get("https://api.example.com/data");

使用 using 语句管理资源

using (var httpClient = HttpClientHelper.Create)
{
    httpClient.RequestUriString = "https://api.example.com/data";
    var result = httpClient.Get();
    // HttpClient 会自动释放
}

注意事项

1. 线程安全: HttpClient 是线程安全的，可以在多线程环境中使用。但建议每个应用程序使用一个 HttpClient 实例。

2. 资源管理: 使用 using 语句或调用 Dispose() 方法释放资源。

3. 异常处理: 所有方法返回 Result<string> 类型，请检查 Successed 属性来判断请求是否成功。

4. 编码:

   • HttpClientHelper 使用 UTF-8 编码
   • HttpWebRequestUtils 使用 UTF-8 编码

5. Content-Type:

   • HttpClientHelper 自动设置 Content-Type 为 application/json
   • HttpWebRequestUtils 设置 Content-Type 为 application/json; charset=UTF-8

6. 协议版本:

   • HttpClientHelper 使用默认的 HTTP 协议版本
   • HttpWebRequestUtils 使用 HTTP/1.0

7. 超时设置: 可以通过 Client.Timeout 属性设置超时时间。

8. 错误处理: 网络错误、HTTP 错误等都会被捕获并返回 Error.Result，不会抛出异常。

---

文件操作 (IO) API

FileUtils 类

类说明

提供文件操作的实用工具方法。

扩展方法

InUse

public static Result<bool> InUse(this string path)

功能说明: 检查文件是否正在使用中。

参数:

• path: 文件路径

返回值:

• true: 文件正在使用中
• false: 文件未被使用

异常:

• 当文件访问失败时，返回包含异常信息的错误结果
• 可能抛出 UnauthorizedAccessException 当没有访问权限时

使用示例:

string filePath = @"C:\file.txt";
var result = filePath.InUse();
if (result.Successed)
{
    bool isInUse = result;
    if (isInUse)
    {
        Console.WriteLine("文件正在使用中");
    }
}

---

Delete

public static Result Delete(this string path)

功能说明: 删除文件。

参数:

• path: 文件路径

返回值: 操作结果，成功返回 Result.Success

异常:

• 当路径无效时，返回包含路径验证错误的错误结果
• 当文件不存在时，返回包含 "文件不存在" 的错误结果
• 当文件正在使用时，可能抛出 IOException
• 当没有删除权限时，可能抛出 UnauthorizedAccessException

使用示例:

string filePath = @"C:\file.txt";
var result = filePath.Delete();
if (result.Successed)
{
    Console.WriteLine("文件删除成功");
}
else
{
    Console.WriteLine($"删除失败: {result.Message}");
}

---

public static Result Delete(this DirectoryInfo info)

功能说明: 删除目录及其所有内容。

参数:

• info: 目录信息对象

返回值: 操作结果，成功返回 Result.Success

异常:

• 当 info 为 null 时，返回包含 "目录信息不能为空" 的错误结果
• 当目录正在使用时，可能抛出 IOException
• 当没有删除权限时，可能抛出 UnauthorizedAccessException

使用示例:

var dirInfo = new DirectoryInfo(@"C:\MyFolder");
var result = dirInfo.Delete();
if (result.Successed)
{
    Console.WriteLine("目录删除成功");
}

---

WriteAllText

public static Result WriteAllText(this string path, string contents)

功能说明: 创建一个新文件，向其中写入指定的字符串，然后关闭文件。如果目标文件已存在，则覆盖该文件。

参数:

• path: 文件路径
• contents: 要写入的字符串内容

返回值: 操作结果，成功返回 Result.Success

异常:

• 当路径无效时，返回包含路径验证错误的错误结果
• 当 contents 为空或仅包含空白字符时，返回包含 "内容不能为空" 的错误结果
• 当文件写入失败时，可能抛出 IOException
• 当没有写入权限时，可能抛出 UnauthorizedAccessException
• 当路径过长时，可能抛出 PathTooLongException

使用示例:

string filePath = @"C:\file.txt";
string content = "Hello World";
var result = filePath.WriteAllText(content);
if (result.Successed)
{
    Console.WriteLine("文件写入成功");
}

---

DiskUtils 类

类说明

提供磁盘操作的实用工具方法。

扩展方法

TotalFreeSpace

public static Result<double> TotalFreeSpace(this string path, StorageUnit unit = StorageUnit.GB)

功能说明: 计算硬盘剩余可用空间。

参数:

• path: 路径，默认获取所在根路径的磁盘信息
• unit: 容量单位，默认为 GB

返回值: 返回剩余可用空间（单位：指定的容量单位）

异常:

• 当路径无效时，返回包含路径验证错误的错误结果
• 当驱动器不可用或未就绪时，返回包含相应错误信息的错误结果

使用示例:

string path = @"C:\";
var result = path.TotalFreeSpace(StorageUnit.GB);
if (result.Successed)
{
    double freeSpace = result;
    Console.WriteLine($"剩余空间: {freeSpace} GB");
}

---

GetFileSize

public static Result<double> GetFileSize(this string path, StorageUnit unit = StorageUnit.MB)

功能说明: 获取文件大小。

参数:

• path: 文件所在路径
• unit: 容量单位，默认为 MB

返回值: 返回文件大小（单位：指定的容量单位）

异常:

• 当文件不存在时，返回包含 FileNotFoundException 的错误结果
• 当文件访问失败时，返回包含异常信息的错误结果

使用示例:

string filePath = @"C:\file.txt";
var result = filePath.GetFileSize(StorageUnit.MB);
if (result.Successed)
{
    double fileSize = result;
    Console.WriteLine($"文件大小: {fileSize} MB");
}

---

StorageUnit 枚举

枚举说明

定义存储容量单位。

枚举值

public enum StorageUnit
{
    B = 1,           // 字节
    KB = 1024,       // 千字节
    MB = 1048576,    // 兆字节
    GB = 1073741824  // 吉字节
}

使用示例:

// 以字节为单位
var sizeInBytes = path.GetFileSize(StorageUnit.B);

// 以KB为单位
var sizeInKB = path.GetFileSize(StorageUnit.KB);

// 以MB为单位
var sizeInMB = path.GetFileSize(StorageUnit.MB);

// 以GB为单位
var sizeInGB = path.GetFileSize(StorageUnit.GB);

---

使用示例

文件操作完整示例

using Hi.Ltd.IO;

// 检查文件是否在使用
string filePath = @"C:\file.txt";
var inUseResult = filePath.InUse();
if (inUseResult.Successed && !inUseResult)
{
    // 文件未被使用，可以操作
    var deleteResult = filePath.Delete();
    if (deleteResult.Successed)
    {
        Console.WriteLine("文件删除成功");
    }
}

// 写入文件
string content = "Hello World\n这是第二行";
var writeResult = filePath.WriteAllText(content);
if (writeResult.Successed)
{
    Console.WriteLine("文件写入成功");
}

// 获取文件大小
var sizeResult = filePath.GetFileSize(StorageUnit.KB);
if (sizeResult.Successed)
{
    Console.WriteLine($"文件大小: {sizeResult} KB");
}

磁盘操作完整示例

using Hi.Ltd.IO;

// 获取磁盘剩余空间
string path = @"C:\";
var freeSpaceResult = path.TotalFreeSpace(StorageUnit.GB);
if (freeSpaceResult.Successed)
{
    double freeSpace = freeSpaceResult;
    Console.WriteLine($"C盘剩余空间: {freeSpace} GB");
    
    if (freeSpace < 10)
    {
        Console.WriteLine("警告: 磁盘空间不足！");
    }
}

目录删除示例

using Hi.Ltd.IO;
using System.IO;

// 删除目录及其所有内容
var dirInfo = new DirectoryInfo(@"C:\Temp\MyFolder");
var result = dirInfo.Delete();
if (result.Successed)
{
    Console.WriteLine("目录删除成功");
}
else
{
    Console.WriteLine($"删除失败: {result.Message}");
}

注意事项

1. 文件权限:

   • 确保应用程序对目标文件/目录有相应的操作权限
   • 删除操作需要写入权限

2. 文件锁定:

   • 使用 InUse() 方法检查文件是否被其他进程占用
   • 删除或写入文件前建议先检查文件状态

3. 路径格式:

   • 支持相对路径和绝对路径
   • Windows 路径使用反斜杠 \，也可以使用正斜杠 /

4. 异常处理:

   • 所有方法都返回 Result 类型，请务必检查 Successed 属性
   • 建议使用链式操作处理错误

5. 性能考虑:

   • 大文件操作可能耗时较长
   • 目录删除操作会递归删除所有子目录和文件，请谨慎使用

---

线程管理 (Threading) API

LRUCache<TKey, TValue> 类

类说明

LRUCache<TKey, TValue> 是一个线程安全的 LRU（Least Recently Used，最近最少使用）缓存管理类，可以自定义最大缓存数。实现了 IDictionary<TKey, TValue>、IDictionary 和 IReadOnlyDictionary<TKey, TValue> 接口。

特性:

• 线程安全：使用 ConcurrentDictionary 和锁机制保证线程安全
• LRU 策略：当缓存满时，自动移除最久未使用的项
• 高性能：访问时间复杂度为 O(1)
• 接口兼容：实现了多种字典接口，可以像普通字典一样使用

构造函数

LRUCache()

public LRUCache()

功能说明: 无参初始化，默认最大值为 1024。

参数: 无

返回值: 无

异常: 无

---

LRUCache(int capacity)

public LRUCache(int capacity)

功能说明: 初始化最大缓存数量。

参数:

• capacity: 最大缓存数量

返回值: 无

异常: 无

使用示例:

var cache = new LRUCache<string, object>(100);

---

属性

this[TKey key]

public TValue this[TKey key] { get; set; }

功能说明: 根据键来获取或设置对应的值内容。

参数:

• key: 键值

返回值: 对应的值

异常:

• ArgumentNullException: 当 key 为 null 时
• KeyNotFoundException: 当键不存在时（get 操作）

使用示例:

cache["key1"] = value1;
var value = cache["key1"];

---

Count

public int Count { get; }

功能说明: 获取当前缓存的数量。

返回值: 缓存项的数量

异常: 无

---

IsEmpty

public bool IsEmpty { get; }

功能说明: 判断缓存是否为空。

返回值:

• true: 缓存为空
• false: 缓存不为空

异常: 无

---

Keys

public IEnumerable<TKey> Keys { get; }

功能说明: 获取所有的键。

返回值: 键的集合

异常: 无

---

Values

public IEnumerable<TValue> Values { get; }

功能说明: 获取所有的值内容。

返回值: 值的集合

异常: 无

---

方法

TryGetValue

public bool TryGetValue(TKey key, out TValue value)

功能说明: 尝试获取指定键的值，如果存在则返回 true，并将值输出到 out 参数中；否则返回 false。

参数:

• key: 键值
• value: 输出参数，如果找到则包含对应的值

返回值:

• true: 键存在
• false: 键不存在

异常: 无

使用示例:

if (cache.TryGetValue("key1", out var value))
{
    // 使用 value
}

---

TryAdd

public bool TryAdd(TKey key, TValue value)

功能说明: 尝试添加一个键值对到缓存中，如果键已存在则返回 false；如果添加成功则返回 true。

参数:

• key: 键值
• value: 值

返回值:

• true: 添加成功
• false: 键已存在或 key 为 null

异常:

• InvalidOperationException: 当缓存状态不一致时（极少发生）

使用示例:

if (cache.TryAdd("key1", value1))
{
    // 添加成功
}

---

TryRemove

public bool TryRemove(TKey key, out TValue value)

功能说明: 尝试移除指定键的缓存项。

参数:

• key: 键值
• value: 输出参数，如果找到则包含被移除的值

返回值:

• true: 移除成功
• false: 键不存在或 key 为 null

异常: 无

---

TryUpdate

public bool TryUpdate(TKey key, TValue value)

功能说明: 更新缓存区的键值信息。

参数:

• key: 键值
• value: 新值

返回值:

• true: 更新成功
• false: 键不存在或 key 为 null

异常: 无

---

GetOrAdd

public TValue GetOrAdd(TKey key, TValue value)
public TValue GetOrAdd(TKey key, Func<TValue> value)
public TValue GetOrAdd(TKey key, Func<TKey, TValue> value)

功能说明: 获取或添加一个键值对，如果键已存在，则返回现有值；如果不存在，则添加新值并返回。

参数:

• key: 键值
• value: 值或值工厂函数

返回值: 键对应的值（已存在或新添加的）

异常: 无

使用示例:

var value = cache.GetOrAdd("key1", () => ExpensiveOperation());

---

ContainsKey

public bool ContainsKey(TKey key)

功能说明: 用于检查缓存中是否包含指定的键。

参数:

• key: 键值

返回值:

• true: 键存在
• false: 键不存在

异常:

• ArgumentNullException: 当 key 为 null 时

---

Clear

public void Clear()

功能说明: 清除所有的缓存信息。

参数: 无

返回值: 无

异常: 无

---

ToArray

public KeyValuePair<TKey, TValue>[] ToArray()

功能说明: 转换为数组形式的键值对，按照 LRU 顺序（最近使用的在前）。

返回值: 键值对数组

异常: 无

使用示例:

var items = cache.ToArray();
foreach (var item in items)
{
    Console.WriteLine($"{item.Key}: {item.Value}");
}

---

GetEnumerator

public IEnumerator<KeyValuePair<TKey, TValue>> GetEnumerator()

功能说明: 获取枚举器，用于遍历缓存中的所有键值对（按照 LRU 顺序）。

返回值: 键值对枚举器

异常: 无

使用示例:

foreach (var item in cache)
{
    Console.WriteLine($"{item.Key}: {item.Value}");
}

注意: LRUCache 实现了 IEnumerable<KeyValuePair<TKey, TValue>> 接口，支持 LINQ 操作。

---

HybridLocked 类

类说明

HybridLocked 是一个混合锁，结合了用户模式锁和内核模式锁，提供高效的线程同步机制。当没有竞争时使用用户模式锁（快速路径），当有竞争时自动升级到内核模式锁（使用 AutoResetEvent）。

特性:

• 混合模式：结合用户模式和内核模式锁的优势
• 高性能：无竞争时性能接近自旋锁
• 资源管理：实现了 IDisposable 接口

使用场景:

• 需要高性能的线程同步
• 临界区代码执行时间较短
• 竞争不频繁的场景

属性

IsBusy

public bool IsBusy { get; }

功能说明: 获取锁是否正在被使用。

返回值:

• true: 锁正在被使用
• false: 锁未被使用

异常: 无

---

方法

Enter

public void Enter()

功能说明: 进入锁。

参数: 无

返回值: 无

异常: 无

使用示例:

var hybridLock = new HybridLocked();
hybridLock.Enter();
try
{
    // 临界区代码
}
finally
{
    hybridLock.Exit();
}

---

Exit

public void Exit()

功能说明: 退出锁。

参数: 无

返回值: 无

异常: 无

---

Dispose

public void Dispose()

功能说明: 释放资源。

参数: 无

返回值: 无

异常: 无

---

OneManyLock 类

类说明

OneManyLock 是一个读写锁，支持一个写者或多个读者同时访问资源。使用位操作和信号量实现高效的读写锁机制。

特性:

• 读写分离：支持多个读者或一个写者
• 状态管理：使用位操作高效管理锁状态
• 等待队列：使用信号量管理等待的读者和写者
• 资源管理：实现了 IDisposable 接口

锁状态:

• Free: 空闲状态
• OwnedByWriter: 被写者持有
• OwnedByReaders: 被读者持有
• OwnedByReadersAndWriterPending: 被读者持有，但有写者等待
• ReservedForWriter: 为写者保留

使用场景:

• 读多写少的场景
• 需要细粒度锁控制的场景

方法

Enter

public void Enter(bool exclusive)

功能说明: 进入锁。

参数:

• exclusive:
  • true: 独占模式（写锁）
  • false: 共享模式（读锁）

返回值: 无

异常: 无

使用示例:

var lock = new OneManyLock();
lock.Enter(exclusive: false);  // 读锁
try
{
    // 读取操作
}
finally
{
    lock.Leave();
}

---

Leave

public void Leave()

功能说明: 释放锁。

参数: 无

返回值: 无

异常: 无

---

Dispose

public void Dispose()

功能说明: 释放资源。

参数: 无

返回值: 无

异常: 无

---

Invoked 类

类说明

Invoked 类提供将操作封送到 已创建句柄 的 System.Windows.Forms.Control 所在线程的扩展方法（通过 SynchronizationContext 或 BeginInvoke/Invoke）。

方法

UpdateAction

public static Result UpdateAction<TControl>(this TControl ctrl, Action<object[]> action, SynchronizationContext context = null, params object[] args) where TControl : Control, new()
public static Result UpdateAction<TControl>(this TControl ctrl, Action<object[]> action, params object[] args) where TControl : Control, new()

功能说明: 用于跨线程控件刷新时使用。如果提供了 context，则使用 context.Post 异步执行；否则使用控件的 BeginInvoke 方法。

类型参数:

• TControl: 控件类型

参数:

• ctrl: 目标控件
• action: 要执行的操作
• context: 同步上下文（可选，第一个重载）
• args: 操作参数

返回值: 操作结果

异常:

• ObjectDisposedException: 当控件已释放或句柄未创建时
• 其他异常会被包装在 Error.Result 中

使用示例:

// 使用同步上下文
label.UpdateAction(args => 
{
    label.Text = args[0].ToString();
}, SynchronizationContext.Current, "New Text");

// 不使用同步上下文（使用控件的 BeginInvoke）
label.UpdateAction(args => 
{
    label.Text = args[0].ToString();
}, "New Text");

---

UpdateFunc

public static object UpdateFunc<TControl>(this TControl ctrl, Func<object[], object> func, SynchronizationContext context = null, params object[] args) where TControl : Control, new()
public static object UpdateFunc<TControl>(this TControl ctrl, Func<object[], object> func, params object[] args) where TControl : Control, new()

功能说明: 用于跨线程控件刷新时使用，可以返回对象。如果提供了 context，则使用 context.Post 异步执行；否则使用控件的 Invoke 方法同步执行。

类型参数:

• TControl: 控件类型

参数:

• ctrl: 目标控件
• func: 要执行的函数
• context: 同步上下文（可选，第一个重载）
• args: 函数参数

返回值: 函数的返回值

异常:

• 当控件已释放或句柄未创建时，可能返回 null 或抛出异常

使用示例:

// 获取控件文本
var text = label.UpdateFunc(args => label.Text, null);

// 使用同步上下文
var result = label.UpdateFunc(args => label.Text.Length, SynchronizationContext.Current);

---

UpdatePost

public static Result UpdatePost<TControl>(this TControl ctrl, SendOrPostCallback d, SynchronizationContext context = null, params object[] args) where TControl : Control, new()
public static Result UpdatePost<TControl>(this TControl ctrl, SendOrPostCallback d, params object[] args) where TControl : Control, new()

功能说明: 使用 Post 方式异步更新控件（不等待执行完成）。如果提供了 context，则使用 context.Post；否则使用控件的 BeginInvoke。

类型参数:

• TControl: 控件类型

参数:

• ctrl: 目标控件
• d: 要执行的回调委托
• context: 同步上下文（可选，第一个重载）
• args: 回调参数

返回值: 操作结果

异常:

• 当控件已释放或句柄未创建时，返回相应的错误

使用示例:

label.UpdatePost(state => 
{
    if (state is string text)
    {
        label.Text = text;
    }
}, null, "New Text");

---

UpdateSend

public static Result UpdateSend<TControl>(this TControl ctrl, SendOrPostCallback d, SynchronizationContext context = null, params object[] args) where TControl : Control, new()
public static Result UpdateSend<TControl>(this TControl ctrl, SendOrPostCallback d, params object[] args) where TControl : Control, new()

功能说明: 使用 Send 方式同步更新控件（等待执行完成）。如果提供了 context，则使用 context.Send；否则使用控件的 BeginInvoke（注意：实际实现中仍使用 BeginInvoke，不会阻塞）。

类型参数:

• TControl: 控件类型

参数:

• ctrl: 目标控件
• d: 要执行的回调委托
• context: 同步上下文（可选，第一个重载）
• args: 回调参数

返回值: 操作结果

异常:

• 当控件已释放或句柄未创建时，返回相应的错误

使用示例:

label.UpdateSend(state => 
{
    if (state is string text)
    {
        label.Text = text;
    }
}, SynchronizationContext.Current, "New Text");

---

Add

public static Result Add<T1, T2>(this T1 ctrl, T2 item, DockStyle dockStyle = DockStyle.None, SynchronizationContext context = null) where T1 : Control, new() where T2 : Control, new()
public static Result Add<T1, T2>(this T1 ctrl, IEnumerable<T2> items, DockStyle dockStyle = DockStyle.None, SynchronizationContext context = null) where T1 : Control, new() where T2 : Control, new()

功能说明: 跨线程添加控件到父控件。

类型参数:

• T1: 父控件类型
• T2: 子控件类型

参数:

• ctrl: 父控件
• item 或 items: 要添加的控件或控件集合
• dockStyle: 停靠样式，默认为 DockStyle.Fill
• context: 同步上下文（可选）

返回值: 操作结果

异常:

• 当参数为 null 时，返回相应的错误

---

Remove

public static Result Remove<T>(this T ctrl, T item, SynchronizationContext context = null) where T : Control, new()

功能说明: 跨线程从父控件移除子控件。

类型参数:

• T: 控件类型

参数:

• ctrl: 父控件
• item: 要移除的控件
• context: 同步上下文（可选）

返回值: 操作结果

异常:

• 当控件不包含在父控件中时，返回相应的错误

---

Text

public static Result Text<TControl, TValue>(this TControl ctrl, TValue text, SynchronizationContext context = null) where TControl : Control, new()

功能说明: 跨线程设置控件的文本。

类型参数:

• TControl: 控件类型
• TValue: 文本值类型

参数:

• ctrl: 目标控件
• text: 文本值
• context: 同步上下文（可选）

返回值: 操作结果

异常:

• 当参数为 null 时，返回相应的错误

---

BackColor / ForeColor

public static Result BackColor<T>(this T ctrl, Color color, SynchronizationContext context = null) where T : Control, new()
public static Result ForeColor<T>(this T ctrl, Color color, SynchronizationContext context = null) where T : Control, new()

功能说明: 跨线程设置控件的背景色或前景色。

类型参数:

• T: 控件类型

参数:

• ctrl: 目标控件
• color: 颜色值
• context: 同步上下文（可选）

返回值: 操作结果

异常:

• 当参数为 null 时，返回相应的错误

---

Enabled / Visible

public static Result Enabled<T>(this T ctrl, bool enabled = false, SynchronizationContext context = null) where T : Control, new()
public static Result Visible<T>(this T ctrl, bool isVisible = false, SynchronizationContext context = null) where T : Control, new()

功能说明: 跨线程设置控件的启用状态或可见性。

类型参数:

• T: 控件类型

参数:

• ctrl: 目标控件
• enabled 或 isVisible: 状态值
• context: 同步上下文（可选）

返回值: 操作结果

异常:

• 当参数为 null 时，返回相应的错误

---

Clear

public static Result Clear<T>(this T ctrl, SynchronizationContext context = null) where T : Control, new()

功能说明: 跨线程清空控件的子控件集合。

类型参数:

• T: 控件类型

参数:

• ctrl: 目标控件
• context: 同步上下文（可选）

返回值: 操作结果

异常:

• 当参数为 null 时，返回相应的错误

---

DataSource

public static Result DataSource(this ComboBox comboBox, object datasource = null, SynchronizationContext context = null)
public static Result DataSource(this DataGridView dataGridView, object datasource = null, SynchronizationContext context = null)

功能说明: 跨线程设置 ComboBox 或 DataGridView 的数据源。设置数据源前会先清空现有数据源，然后刷新控件。

参数:

• comboBox 或 dataGridView: 目标控件
• datasource: 数据源（可以为 null）
• context: 同步上下文（可选）

返回值: 操作结果

异常:

• 当控件为 null 时，返回相应的错误

使用示例:

var data = new List<string> { "Item1", "Item2", "Item3" };
comboBox.DataSource(data);

---

BackgroundImage

public static Result BackgroundImage<T>(this T ctrl, Image image, ImageLayout imageLayout = ImageLayout.None, SynchronizationContext context = null) where T : Control, new()

功能说明: 跨线程设置控件的背景图片和布局方式。

类型参数:

• T: 控件类型

参数:

• ctrl: 目标控件
• image: 背景图片
• imageLayout: 图片布局方式，默认为 ImageLayout.Stretch
• context: 同步上下文（可选）

返回值: 操作结果

异常:

• 当 ctrl 或 image 为 null 时，返回相应的错误

使用示例:

var image = Image.FromFile("background.png");
panel.BackgroundImage(image, ImageLayout.Tile);

---

Image

public static Result Image<T>(this T ctrl, Image image, SynchronizationContext context = null) where T : ButtonBase, new()

功能说明: 跨线程设置按钮控件的图片（适用于 Button、CheckBox、RadioButton 等继承自 ButtonBase 的控件）。

类型参数:

• T: 按钮控件类型（必须继承自 ButtonBase）

参数:

• ctrl: 目标按钮控件
• image: 图片
• context: 同步上下文（可选）

返回值: 操作结果

异常:

• 当 ctrl 或 image 为 null 时，返回相应的错误

使用示例:

var image = Image.FromFile("icon.png");
button.Image(image);

---

Tag

public static Result Tag<T>(this T ctrl, object tag, SynchronizationContext context = null) where T : Control, new()

功能说明: 跨线程设置控件的标签（Tag 属性），用于存储与控件关联的自定义数据。

类型参数:

• T: 控件类型

参数:

• ctrl: 目标控件
• tag: 标签对象
• context: 同步上下文（可选）

返回值: 操作结果

异常:

• 当 ctrl 为 null 时，返回相应的错误

使用示例:

button.Tag(new { Id = 123, Name = "Button1" });

---

Value

public static Result Value(this ProgressBar ctrl, int value, SynchronizationContext context = null)

功能说明: 跨线程设置进度条的值。

参数:

• ctrl: 目标进度条控件
• value: 进度值（必须在 Minimum 和 Maximum 范围内）
• context: 同步上下文（可选）

返回值: 操作结果

异常:

• 当 ctrl 为 null 时，返回相应的错误
• 当 value 超出 Minimum 和 Maximum 范围时，返回 Error.Result（包含 ArgumentOutOfRangeException）

使用示例:

progressBar.Value(50);  // 设置进度为 50

---

使用示例

LRU 缓存使用示例

// 创建缓存，最大容量为 100
var cache = new LRUCache<string, object>(100);

// 添加项
cache.TryAdd("key1", "value1");
cache["key2"] = "value2";

// 获取项
if (cache.TryGetValue("key1", out var value))
{
    Console.WriteLine(value);
}

// 获取或添加（如果不存在则添加）
var result = cache.GetOrAdd("key3", () => ExpensiveOperation());

// 更新项
cache.TryUpdate("key1", "new value");

// 移除项
if (cache.TryRemove("key2", out var removedValue))
{
    Console.WriteLine($"Removed: {removedValue}");
}

// 遍历缓存
foreach (var item in cache)
{
    Console.WriteLine($"{item.Key}: {item.Value}");
}

// 清空缓存
cache.Clear();

混合锁使用示例

var hybridLock = new HybridLocked();
try
{
    hybridLock.Enter();
    // 临界区代码
    // 执行需要同步的操作
}
finally
{
    hybridLock.Exit();
}

// 或使用 using 语句
using (var hybridLock = new HybridLocked())
{
    hybridLock.Enter();
    try
    {
        // 临界区代码
    }
    finally
    {
        hybridLock.Exit();
    }
}

读写锁使用示例

var lock = new OneManyLock();
try
{
    // 获取读锁（多个读者可以同时持有）
    lock.Enter(exclusive: false);
    try
    {
        // 读取操作
        var data = ReadData();
    }
    finally
    {
        lock.Leave();
    }
}
finally
{
    lock.Dispose();
}

// 写锁示例
lock.Enter(exclusive: true);
try
{
    // 写入操作（独占）
    WriteData();
}
finally
{
    lock.Leave();
}

跨线程 UI 封送示例

功能说明: 演示在后台线程中通过 Invoked 扩展将更新封送到 Control 所在线程（类型约束为 System.Windows.Forms.Control）。

// 在后台线程中更新 UI
Task.Run(() =>
{
    // 设置文本
    label.Text("Processing...");
    
    // 设置颜色
    label.ForeColor(Color.Red);
    
    // 设置进度条
    progressBar.Value(50);
    
    // 添加控件
    panel.Add(newButton, DockStyle.Fill);
    
    // 执行自定义操作
    label.UpdateAction(args =>
    {
        label.Text = $"Processed {args[0]} items";
    }, null, 100);
});

注意事项

1. 线程安全:

   • LRUCache 是线程安全的，可以在多线程环境中安全使用
   • HybridLocked 和 OneManyLock 是线程同步原语，需要正确使用
   • 所有 Invoked 类的方法都是线程安全的，可以在任何线程中调用

2. 锁的使用:

   • 使用锁时，务必在 finally 块中释放锁，避免死锁
   • 不要在持有锁的情况下调用可能阻塞的操作
   • 使用 using 语句可以自动释放实现了 IDisposable 的锁

3. 跨线程操作:

   • 所有 Invoked 类的方法都使用控件的 Invoke 或 BeginInvoke 方法，确保线程安全
   • 如果提供了 SynchronizationContext，会优先使用它
   • 控件必须已创建句柄（IsHandleCreated 为 true）

4. 性能:

   • LRU 缓存使用 ConcurrentDictionary 和 LinkedList 实现，访问时间复杂度为 O(1)
   • 混合锁在无竞争时性能接近自旋锁
   • 读写锁适合读多写少的场景

5. 资源释放:

   • 所有实现了 IDisposable 的类（HybridLocked、OneManyLock），使用完毕后应调用 Dispose() 方法
   • 建议使用 using 语句确保资源正确释放

6. LRU 缓存注意事项:

   • 当缓存满时，会自动移除最久未使用的项
   • 访问缓存项（TryGetValue、索引器）会更新其使用时间
   • 键不能为 null，否则会抛出 ArgumentNullException

---

插件管理 (Managements) API

PluginManager 类

类说明

PluginManager 类提供插件管理器，用于加载和管理插件程序集。

方法

CreateInstance

public static PluginManager CreateInstance()

功能说明: 创建 PluginManager 实例。

参数: 无

返回值: PluginManager 实例

异常: 无

使用示例:

var manager = PluginManager.CreateInstance();

---

LoadFrom

public Result LoadFrom(string assemblyPath)

功能说明: 从指定路径加载程序集。

参数:

• assemblyPath: 程序集文件路径

返回值: 操作结果

异常:

• 当加载失败时，返回 Error.Result 错误（包含异常信息）

使用示例:

var result = manager.LoadFrom(@"C:\Plugins\MyPlugin.dll");
if (result.Successed)
{
    // 加载成功
}

---

Singleton<T> 类

类说明

Singleton<T> 是一个泛型单例模式实现，支持参数化构造函数。

属性

Instance

public static T Instance { get; }

功能说明: 获取默认实例（无参数）。

返回值: 单例实例

异常:

• InvalidOperationException: 当找不到合适的构造函数时
• ArgumentException: 当参数不正确时
• MissingMethodException: 当找不到适合的构造函数时
• Exception: 当发生未知错误时

使用示例:

var instance = Singleton<MyClass>.Instance;

---

方法

GetInstance

public static T GetInstance(params object[] args)

功能说明: 获取单例实例（支持参数化构造函数）。

参数:

• args: 构造函数参数（可选）

返回值: 单例实例

异常:

• InvalidOperationException: 当找不到合适的构造函数时
• ArgumentException: 当参数不正确时
• MissingMethodException: 当找不到适合的构造函数时
• Exception: 当发生未知错误时

使用示例:

// 无参数
var instance1 = Singleton<MyClass>.GetInstance();

// 带参数
var instance2 = Singleton<MyClass>.GetInstance("param1", 123);

注意:

• 如果未传入参数，则选择参数个数最少的构造函数
• 如果构造函数参数有可选参数，会自动使用默认值
• 使用弱引用缓存实例，支持垃圾回收

---

ServiceCollection 类

类说明

ServiceCollection 类实现了 IServiceCollection 接口，用于管理服务描述符集合。

属性

Count

public int Count { get; }

功能说明: 获取服务描述符的数量。

返回值: 服务描述符的数量

异常: 无

---

IsReadOnly

public bool IsReadOnly { get; }

功能说明: 获取集合是否为只读。

返回值:

• true: 集合为只读
• false: 集合可写

异常: 无

---

this[int index]

public ServiceDescriptor this[int index] { get; set; }

功能说明: 获取或设置指定索引的服务描述符。

参数:

• index: 索引

返回值: 服务描述符

异常: 无

注意: 当集合为只读时，设置操作无效。

---

方法

Add

public void Add(ServiceDescriptor item)

功能说明: 添加服务描述符。

参数:

• item: 服务描述符

返回值: 无

异常: 无

注意: 当集合为只读时，操作无效。

---

Remove

public bool Remove(ServiceDescriptor item)

功能说明: 移除服务描述符。

参数:

• item: 要移除的服务描述符

返回值:

• true: 移除成功
• false: 移除失败或集合为只读

异常: 无

---

Clear

public void Clear()

功能说明: 清空所有服务描述符。

参数: 无

返回值: 无

异常: 无

注意: 当集合为只读时，操作无效。

---

Contains

public bool Contains(ServiceDescriptor item)

功能说明: 检查集合是否包含指定的服务描述符。

参数:

• item: 服务描述符

返回值:

• true: 包含
• false: 不包含或集合为只读

异常: 无

---

MakeReadOnly

public void MakeReadOnly()

功能说明: 将集合设置为只读。

参数: 无

返回值: 无

异常: 无

---

LocateFactory 类

类说明

LocateFactory 类是一个本地化的操作工厂，用于切换语言和获取本地化资源。

方法

SetCulture

public static void SetCulture(string culterName)

功能说明: 设置切换本地化语言。

参数:

• culterName: 文化名称（如 "zh-CN", "en-US"）

返回值: 无

异常: 无

使用示例:

LocateFactory.SetCulture("en-US");

---

GetValue

public static string GetValue(string name, string key, params object[] args)

功能说明: 获取本地化资源值。

参数:

• name: 资源名称
• key: 资源键
• args: 格式化参数（可选）

返回值: 本地化字符串；如果找不到，返回 key 本身

异常: 无

使用示例:

var text = LocateFactory.GetValue("MyApp", "WelcomeMessage", userName);

---

AttachLocales

public static void AttachLocales(ConcurrentDictionary<string, string> contetnts)

功能说明: 附加本地化语言资源。

参数:

• contetnts: 本地化内容字典

返回值: 无

异常: 无

使用示例:

var locales = new ConcurrentDictionary<string, string>
{
    ["Key1"] = "Value1",
    ["Key2"] = "Value2"
};
LocateFactory.AttachLocales(locales);

---

注意事项（插件与服务）

1. 插件加载: 使用 PluginManager.LoadFrom 加载插件时，请确保程序集路径有效
2. 单例模式: Singleton<T> 使用弱引用缓存，支持垃圾回收
3. 服务集合: ServiceCollection 可以设置为只读，设置后无法修改
4. 本地化: LocateFactory 支持动态切换语言，资源文件应放在 Locales 文件夹下

---

应用程序 (App) API

App 类

类说明

App 类提供了应用程序相关的功能，包括单例模式检查、管理员权限检查和性能监控。实现了 IDisposable 接口。

构造函数

App()

public App()

功能说明: 初始化 App 实例。

参数: 无

返回值: 无

异常: 无

使用示例:

var app = new App();

---

方法

IsSingleton

public Result<bool> IsSingleton()

功能说明: 检查应用程序是否以单例模式运行（只有一个实例）。

参数: 无

返回值:

• true: 应用程序是单例实例（当前是第一个实例）
• false: 应用程序不是单例实例（已有其他实例在运行）

异常:

• 当创建 Mutex 失败时，返回 Error.Result 错误（包含异常信息）

使用示例:

var app = new App();
var result = app.IsSingleton();
if (!result.Content)
{
    // 应用程序已在运行，退出
    Environment.Exit(0);
}

注意: 此方法使用命名 Mutex 来检查单例，Mutex 名称固定为 "Hi.Ltd.Application"。

---

IsRunAsAdmin

public Result<bool> IsRunAsAdmin()

功能说明: 判断当前的软件是否是以管理员的权限启动的。

参数: 无

返回值:

• true: 当前以管理员权限运行
• false: 当前不是以管理员权限运行

异常:

• 当检查失败时，返回 Error.Result 错误（包含异常信息）

使用示例:

var app = new App();
var result = app.IsRunAsAdmin();
if (!result.Content)
{
    // 需要管理员权限
    app.RunAsAdmin();
}

---

RunAsAdmin

public Result RunAsAdmin()

功能说明: 以管理员权限重新启动当前应用程序。

参数: 无

返回值: 操作结果

异常:

• 当启动失败时，返回 Error.Result 错误（包含异常信息）

使用示例:

var app = new App();
if (!app.IsRunAsAdmin().Content)
{
    app.RunAsAdmin();  // 会重新启动应用程序
    return;  // 当前进程会退出
}

注意:

• 此方法会启动新的管理员权限进程
• 当前进程会调用 Environment.Exit(0) 退出
• 需要用户确认 UAC 提示

---

性能监控方法（需要 NET40_OR_GREATER）

以下方法仅在 .NET Framework 4.0 或更高版本中可用。

GetCpuUsage

public Result<float> GetCpuUsage()

功能说明: 获取 CPU 使用率。

参数: 无

返回值: CPU 使用率百分比（0-100）

异常: 无

使用示例:

#if NET40_OR_GREATER
var app = new App();
var cpuUsage = app.GetCpuUsage();
Console.WriteLine($"CPU 使用率: {cpuUsage.Content}%");
#endif

注意:

• 首次调用可能返回 0，需要等待下一次调用才能获取准确值
• 使用 PerformanceCounter 实现

---

GetRamAvailable

public Result<float> GetRamAvailable()

功能说明: 获取可用内存（MB）。

参数: 无

返回值: 可用内存大小（MB）

异常: 无

使用示例:

#if NET40_OR_GREATER
var app = new App();
var ramAvailable = app.GetRamAvailable();
Console.WriteLine($"可用内存: {ramAvailable.Content} MB");
#endif

---

GetDiskUsage

public Result<float> GetDiskUsage()

功能说明: 获取磁盘使用率。

参数: 无

返回值: 磁盘使用率百分比（0-100）

异常: 无

使用示例:

#if NET40_OR_GREATER
var app = new App();
var diskUsage = app.GetDiskUsage();
Console.WriteLine($"磁盘使用率: {diskUsage.Content}%");
#endif

---

GetNetworkUsage

public Result<float> GetNetworkUsage()

功能说明: 获取网络使用量（字节/秒）。

参数: 无

返回值: 网络传输速率（字节/秒）

异常: 无

使用示例:

#if NET40_OR_GREATER
var app = new App();
var networkUsage = app.GetNetworkUsage();
Console.WriteLine($"网络使用量: {networkUsage.Content} 字节/秒");
#endif

---

GetGpuUsage

public Result<float> GetGpuUsage()

功能说明: 获取 GPU 使用率。

参数: 无

返回值: GPU 使用率百分比（0-100）

异常: 无

使用示例:

#if NET40_OR_GREATER
var app = new App();
var gpuUsage = app.GetGpuUsage();
Console.WriteLine($"GPU 使用率: {gpuUsage.Content}%");
#endif

注意:

• 需要系统支持 GPU 性能计数器
• 某些系统可能不支持此功能

---

方法

Dispose

public void Dispose()

功能说明: 释放资源。

参数: 无

返回值: 无

异常: 无

使用示例:

using (var app = new App())
{
    // 使用 app
}

---

使用示例

完整的单例模式检查

var app = new App();
var singletonResult = app.IsSingleton();
if (!singletonResult.Successed || !singletonResult.Content)
{
    // 应用程序已在运行
    MessageBox.Show("应用程序已在运行！");
    Environment.Exit(0);
    return;
}

// 检查管理员权限
var adminResult = app.IsRunAsAdmin();
if (!adminResult.Successed || !adminResult.Content)
{
    // 需要管理员权限
    var runAsAdminResult = app.RunAsAdmin();
    if (runAsAdminResult.Successed)
    {
        // 已重新启动，当前进程退出
        return;
    }
}

// 应用程序正常启动

性能监控

#if NET40_OR_GREATER
var app = new App();

// 获取 CPU 使用率
var cpuResult = app.GetCpuUsage();
if (cpuResult.Successed)
{
    Console.WriteLine($"CPU: {cpuResult.Content}%");
}

// 获取可用内存
var ramResult = app.GetRamAvailable();
if (ramResult.Successed)
{
    Console.WriteLine($"可用内存: {ramResult.Content} MB");
}

// 获取磁盘使用率
var diskResult = app.GetDiskUsage();
if (diskResult.Successed)
{
    Console.WriteLine($"磁盘: {diskResult.Content}%");
}

// 获取网络使用量
var networkResult = app.GetNetworkUsage();
if (networkResult.Successed)
{
    Console.WriteLine($"网络: {networkResult.Content}");
}

// 获取 GPU 使用率
var gpuResult = app.GetGpuUsage();
if (gpuResult.Successed)
{
    Console.WriteLine($"GPU: {gpuResult.Content}%");
}
#endif

注意事项

1. 单例模式: IsSingleton() 方法使用命名 Mutex，Mutex 名称固定，请确保应用程序名称唯一
2. 管理员权限: RunAsAdmin() 会触发 UAC 提示，需要用户确认
3. 性能监控: 性能监控方法需要 .NET Framework 4.0 或更高版本
4. 资源释放: 使用完毕后应调用 Dispose() 方法释放资源
5. 性能计数器: 首次调用性能监控方法可能返回不准确的值，建议调用两次
6. 线程安全: 性能监控方法不是线程安全的，请在单线程环境中使用

使用示例:

#if NET40_OR_GREATER
var app = new App();
var cpu = app.GetCpuUsage();
var ram = app.GetRamAvailable();
#endif

---

互操作 (Interop) API

JsonSerializer 类

类说明

JsonSerializer 类是一个轻量级 JSON 序列化与反序列化工具类，提供与 Newtonsoft.Json 相近的常用功能。

属性

UseCamelCase

public static bool UseCamelCase { get; set; }

功能说明: 是否使用 CamelCase 命名策略（默认：true，与 Newtonsoft.Json 一致）。

返回值: 布尔值，表示是否使用 CamelCase

异常: 无

使用示例:

JsonSerializer.UseCamelCase = true;
var json = JsonSerializer.Serialize(new { Name = "A" });

---

IncludeNullValues

public static bool IncludeNullValues { get; set; }

功能说明: 是否在序列化时包含 null 值（默认：false，跳过 null）。

返回值: 布尔值，表示是否包含 null 值

异常: 无

使用示例:

JsonSerializer.IncludeNullValues = true;
var json = JsonSerializer.Serialize(new { X = (string)null });

---

方法

Serialize

public static string Serialize(object obj)

功能说明: 将对象序列化为 JSON 字符串。

参数:

• obj: 要序列化的对象

返回值: JSON 字符串

异常: 无

使用示例:

var obj = new { Name = "Test", Value = 123 };
var json = JsonSerializer.Serialize(obj);
// 结果: {"name":"Test","value":123}

---

Deserialize

public static T Deserialize<T>(string json)

功能说明: 将 JSON 字符串反序列化为指定类型的对象。

参数:

• json: JSON 字符串

返回值: 反序列化后的对象

异常:

• FormatException: JSON 格式错误时抛出

使用示例:

var json = "{\"name\":\"Test\",\"value\":123}";
var obj = JsonSerializer.Deserialize<MyClass>(json);

---

注意事项

1. 循环引用: 遇到循环引用时会输出 null，避免死循环
2. 类型支持: 支持基本类型、对象、数组、列表、字典等常见数据结构
3. 特性支持: 支持 JsonIgnore 和 JsonProperty 特性
4. 命名策略: 默认使用 CamelCase，可通过 UseCamelCase 属性修改

---

IniHelper 类

类说明

IniHelper 类提供高性能的 INI 文件序列化和反序列化功能，支持类和结构体的自动转换。

属性

Create

public static readonly IIni Create

功能说明: 获取单例实例（无路径版本）。

返回值: INI 操作接口实例

异常: 无

使用示例:

var ini = IniHelper.Create;

---

方法

Serialize

public Result Serialize<T>(string path, T obj)

功能说明: 将对象序列化到 INI 文件。

参数:

• path: INI 文件路径
• obj: 要序列化的对象

返回值: 操作结果

异常: 无

使用示例:

var connect = new Connect { Id = "ABS", Description = "测试" };
var result = IniHelper.Create.Serialize(@"D:\HiTest.Ini", connect);

---

Deserialize

public Result<T> Deserialize<T>(string path)

功能说明: 从 INI 文件反序列化对象。

参数:

• path: INI 文件路径

返回值: 反序列化后的对象结果

异常: 无

使用示例:

var result = IniHelper.Create.Deserialize<Connect>(@"D:\HiTest.Ini");
if (result.Successed)
{
    Console.WriteLine(result.Content.Id);
}

---

注意事项

1. 线程安全: 带 path 参数的方法是线程安全的，可以并发调用
2. 类型支持: 支持类、结构体、嵌套对象、枚举、可空类型等
3. 性能优化: 使用表达式树和 LRU 缓存优化，避免重复反射
4. 限制: 不支持数组、列表和字典类型的序列化

---

RegistryHelper 类

类说明

RegistryHelper 类提供 Windows 注册表操作功能，支持注册表键和值的创建、读取、写入、删除。

属性

Create

public static IRegistry Create

功能说明: 获取单例实例（无参版本）。

返回值: 注册表操作接口实例

异常: 无

使用示例:

var reg = RegistryHelper.Create;

---

方法

Instance

public static IRegistry Instance(HKey root, string name, string key)

功能说明: 获取带参数的单例实例。

参数:

• root: 注册表根（HKey），如 HKey.CURRENT_USER
• name: 子键名称，如 @"Software\MyApp"
• key: 值名称

返回值: 注册表操作接口实例

异常: 无

使用示例:

var registry = RegistryHelper.Instance(HKey.CURRENT_USER, @"Software\MyApp", "Setting");
var value = registry.GetValue();

---

注意事项

1. 权限要求: 修改注册表需要适当的权限，某些根需要管理员权限
2. 线程安全: 单例实例在多线程环境下需要同步访问
3. 路径格式: 子键路径使用反斜杠分隔，如 @"Software\MyApp\Settings"

---

ScannerUtils 类

类说明

ScannerUtils 类提供扫码功能，通过键盘钩子捕获扫码枪输入。

属性

Create

public static IScanner Create

功能说明: 创建扫码器实例。

返回值: 扫码器接口实例

异常: 无

使用示例:

var scanner = ScannerUtils.Create;

---

事件

OnScannerCode

event ScannerCodeEventHandler OnScannerCode

功能说明: 扫码内容变化时触发的事件。

参数:

• code: 扫码内容

异常: 无

使用示例:

var scanner = ScannerUtils.Create;
scanner.OnScannerCode += (code) => {
    Console.WriteLine($"扫码内容: {code}");
};
scanner.Start();

---

方法

Start

Result<bool> Start()

功能说明: 启动扫码监听。

参数: 无

返回值: 操作结果，成功返回 true

异常: 无

使用示例:

var scanner = ScannerUtils.Create;
var started = scanner.Start();

---

Stop

Result<bool> Stop()

功能说明: 停止扫码监听。

参数: 无

返回值: 操作结果，成功返回 true

异常: 无

---

注意事项

1. 权限要求: 键盘钩子需要适当的权限
2. 资源释放: 使用完毕后应调用 Dispose() 方法释放资源
3. 输入间隔: 可通过 Interval 属性设置判定连续输入的间隔时间

使用示例:

var scanner = ScannerUtils.Create;
scanner.Start();
scanner.Stop();

---

XmlUtils 类

类说明

XmlUtils 类提供 XML 文件序列化与反序列化功能，支持线程安全和性能优化。

属性

Instance

public static readonly IXml Instance

功能说明: 获取单例实例（无路径、根节点版本，调用需传 path/root 参数）。

返回值: XML 操作接口实例

异常: 无

使用示例:

var xml = XmlUtils.Instance;

---

方法

GetInstance

public static IXml GetInstance(string rootName, string xmlFilePath)

功能说明: 获取配置了根节点和文件路径的单例实例。

参数:

• rootName: XML 根节点名称
• xmlFilePath: XML 文件路径

返回值: XML 操作接口实例

异常: 无

使用示例:

var xml = XmlUtils.GetInstance("Root", @"D:\config.xml");

---

Serialize

public Result Serialize<T>(string path, T src)

功能说明: 将对象序列化到指定 XML 文件（线程安全）。

参数:

• path: XML 文件路径
• src: 要序列化的对象

返回值: 操作结果

异常: 无

使用示例:

var connect = new Connect { Id = "ABS", Description = "测试" };
var result = XmlUtils.Instance.Serialize(@"D:\HiTest.xml", connect);

---

Deserialize

public Result<T> Deserialize<T>(string path)

功能说明: 从指定 XML 文件反序列化对象（线程安全）。

参数:

• path: XML 文件路径

返回值: 反序列化后的对象结果

异常: 无

使用示例:

var result = XmlUtils.Instance.Deserialize<Connect>(@"D:\HiTest.xml");
if (result.Successed)
{
    Console.WriteLine(result.Content.Id);
}

---

注意事项

1. 线程安全: 读写均使用 ReaderWriterLockSlim，支持并发访问
2. 性能优化: 缓存 XmlSerializer 实例，避免重复构造
3. 自动创建目录: 序列化时自动创建目录及空文件
4. 单例模式: 提供无参与带路径/根节点双重单例

---

版本信息

• 当前版本: 2025.7.7.1141
• 支持框架: .NET Framework 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
• 许可证: MIT
• 作者: chustange
• 公司: 海蓝智能科技有限公司

更新日志

2025.7.7.1141

• 本次版本围绕“基础能力完备化 + 组件可用性提升”进行了较大范围更新，覆盖核心模块与 API 文档。
• 详细更新项
  • 日志模块（Logging）
    • 功能说明：完善日志写入、日志路径配置、日志级别控制与日志文件管理能力，支持更稳定的运行期诊断。
    • 典型用例：桌面端/服务端启动时统一初始化日志，在业务异常、接口调用、关键状态变更时按级别输出并落盘。
  • 结果模块（Result）
    • 功能说明：补充并优化 Result、Result<T> 与 Error 的返回结构，增强链式处理与统一错误表达能力。
    • 典型用例：在“参数校验 → 业务执行 → 持久化 → 返回响应”流程中使用统一结果对象，避免异常风格混杂。
  • 工具模块（Utilities）
    • 功能说明：扩展数值、字符串及常用类型扩展方法，补足类型转换、范围限制与文本处理等基础能力。
    • 典型用例：表单输入清洗、配置项类型转换、业务参数边界裁剪（如最小值/最大值限制）。
  • 安全模块（Security）
    • 功能说明：在 AES、RSA、国密 SM2（SM2Utils）、SM3（SM3Utils）、HMAC-SM3（HmacSm3Utils）、SM4（SM4Utils，含 HMAC-SM3 的 EtM 封装）、MD5 等方向完善方法集，统一加密、解密、摘要与密钥相关入口。涉及 GetAesKey、GetAesIV、GenAesKeyAndIV、ToAes、FromAes、GenerateKeys、ToRSA、FromRSA、SM2Utils.Sign/Verify、SM3Utils.ComputeHash、HmacSm3Utils.ComputeHash、SM4Utils.EncryptCbcWithRandomIvAndHmacSm3、ToMd5、GetMD5Hash 等；net8 目标下另有 Hi.Ltd 命名空间的 AesGcmUtils/AesGcmHelper（#if NET8_0_OR_GREATER）。
    • 典型用例：本地配置可用 AES/SM4 加密存储；跨系统小数据可用 RSA；需国密摘要或完整性时用 SM3 / HMAC-SM3；需国密签名协议对接时用 SM2（含 DER 互转）；需国密对称且带完整性时用 EncryptCbcWithRandomIvAndHmacSm3 封装后传输或落盘；文件校验仍可用 ToMd5/GetMD5Hash（知悉 MD5 强度边界）。
  • 网络模块（Https）
    • 功能说明：补充 HttpBase、HttpClientHelper、HttpWebRequestUtils 能力说明，完善常见请求封装方式。
    • 典型用例：统一封装 GET/POST 调用外部平台接口，集中处理请求头、超时、返回解析与错误日志。
  • 文件模块（IO）
    • 功能说明：增强 FileUtils、DiskUtils 与存储单位相关能力说明，完善文件与磁盘操作支持。
    • 典型用例：业务报表导出、目录自动创建、磁盘容量检查与文件清理策略执行。
  • 线程模块（Threading）
    • 功能说明：完善 LRUCache<TKey, TValue>、HybridLocked、OneManyLock、Invoked 的并发与缓存能力说明。
    • 典型用例：热点数据缓存、防止重复触发关键操作、读多写少场景下提升并发吞吐与一致性。
  • 插件模块（Managements）
    • 功能说明：补充 PluginManager、Singleton<T>、ServiceCollection、LocateFactory 等能力说明。
    • 典型用例：主程序按约定动态加载扩展模块，使用 ServiceCollection 管理服务生命周期，并结合 LocateFactory 做本地化资源解析。
  • 应用模块（App）
    • 功能说明：完善单例控制、管理员权限拉起、性能监控等运行时辅助能力。
    • 典型用例：桌面程序限制单实例运行，需要特权操作时请求管理员权限，并周期采集 CPU/内存指标。
  • 互操作模块（Interop）
    • 功能说明：补充 JsonSerializer、IniHelper、RegistryHelper、ScannerUtils、XmlUtils 等组件说明。
    • 典型用例：应用配置读写（INI/JSON/XML）、注册表参数维护、扫码设备接入与数据落地。
• 文档与示例
  • 功能说明：大幅补充 API 级说明与示例代码，覆盖更多常用调用方式。
  • 典型用例：新成员可按模块示例快速完成首个功能集成，老项目可按章节对照逐步替换旧实现。
• 兼容性
  • 保持对 .NET Framework 4.6.2 ~ 4.8.1 的兼容支持。

2023.10.11

• 新增特性相关方法

---

注意事项

1. 错误处理: 本类库的方法返回 Result 类型，请务必检查 Successed 属性
2. 线程安全: 日志记录是线程安全的，但其他操作请根据实际情况考虑线程安全
3. 性能考虑: 某些操作可能涉及性能开销，请根据实际需求选择合适的方法
4. 兼容性: 部分功能需要特定版本的 .NET Framework 支持

技术支持

如有问题或建议，请联系：

• 公司: 海蓝智能科技有限公司
• 版权: © 2025 海蓝智能科技有限公司 保留所有权利

源码与 Git 约定（master）

向远程 master 分支推送本仓库变更时，提交信息请遵守：

1. 说明清晰：使用 git commit -m "..." 时仅写简短中文改动说明，便于审阅与追溯。
2. 禁止工具尾缀：勿在提交信息中加入 Made-with: Cursor、Co-authored-by 等与工具或 Agent 相关的尾缀或署名行。

---

免责声明: 本类库仅供参考使用，不保证方法的有效性，请谨慎使用！