IceTea.Pure 1.3.2

IceTea.Pure (.NET Standard 2.0 类库)

简介

IceTea.Pure 是一个纯净的 .NET Standard 2.0 类库，提供了丰富的基类、工具类和接口，旨在简化日常开发工作，提高代码复用性和可维护性。该库无任何外部依赖，可在 .NET Framework、.NET Core、.NET 5+、Xamarin、MAUI 等平台上使用。

安装

dotnet add package IceTea.Pure

核心功能模块

一、基础模型

1. NotifyBase：ExceptionBase, INotifyPropertyChanged - 属性变更通知

实现 INotifyPropertyChanged 接口，提供属性变更通知功能，适用于 MVVM 模式开发。

核心方法：

• bool SetProperty<T>(ref T storage, T value, [CallerMemberName] string propertyName = null) - 设置属性值并触发变更通知
• void RaisePropertyChanged([CallerMemberName] string propertyName = null) - 触发属性变更通知

特性：

• 支持泛型版本 NotifyBase<T>
• 支持 CallerMemberName 自动属性名
• 自动检测值变化，仅在值改变时触发事件

2. DisposableBase：IDisposable - 资源释放

实现 IDisposable 接口，提供标准的资源释放模式。

核心方法：

• void Dispose() - 释放资源
• protected virtual void DisposeCore() - 派生类重写的资源释放逻辑
• protected void CheckDispose() - 检查对象是否已释放

特性：

• 安全的 Dispose 模式，防止重复释放
• 支持异常传播控制

3. ChildrenBase：IChildren - 子对象管理

管理子对象与父集合的关系。

核心属性：

• IDictionary<Type, ICollection<object>> Parents - 所有父集合字典

核心方法：

• bool TryAddTo<TParent>(TParent parent) - 尝试添加到父集合
• bool TryRemoveFrom<TParent>(TParent parent) - 尝试从父集合移除

特性：

• 自动维护与父集合的关系
• 释放时自动清理所有父集合引用
• 非线程安全设计（单线程使用）

4. CloneableBase - 对象克隆

提供对象克隆支持的基础实现。

非泛型版本：

• 实现 ICloneable 接口
• 核心方法：
  • object Clone() - 使用MemberwiseClone实现浅克隆
  • string GetTableName() - 获取关联表名

泛型版本：

• 实现 ICloneable<T> 接口
• 继承约束：where T : CloneableBase<T>
• 核心方法：
  • T Clone() - 类型安全的浅克隆
  • 支持重写以自定义克隆逻辑

通用特性：

• 默认提供浅克隆实现
• 支持派生类重写克隆方法

5. ValidationBase：INotifyDataErrorInfo, IDataErrorInfo - 数据验证

使用 DataAnnotations 提供内容验证信息的基类。

核心属性：

• bool HasErrors - 是否存在验证错误
• event EventHandler<DataErrorsChangedEventArgs> ErrorsChanged - 错误变更事件

核心方法：

• IEnumerable GetErrors(string propertyName) - 获取指定属性的错误信息
• protected void ValidateNotifyDataError([CallerMemberName] string propName = null) - 验证属性并触发错误变更事件
• protected IEnumerable<string> Validate([CallerMemberName] string propName = null) - 验证属性并返回错误信息
• protected virtual bool ValidateCore(string propName, out ICollection<string> errors) - 核心验证逻辑

特性：

• 实现 INotifyDataErrorInfo 和 IDataErrorInfo 接口
• 支持使用 [Required]、[StringLength]、[Range] 等 DataAnnotations 特性
• 自动触发 ErrorsChanged 事件

6. StarterBase：IStarter - 可启停组件

提供可启停的组件基类，支持状态管理和生命周期控制。

核心属性：

• bool IsStarted - 是否已启动
• EnumStarterStatus Status - 当前状态

核心方法：

• Task<bool> StartAsync() - 启动组件
• protected abstract Task StartAsyncCore() - 启动核心逻辑（派生类实现）
• Task CloseAsync() - 关闭组件
• protected virtual Task CloseAsyncCore() - 关闭核心逻辑（派生类可选）
• protected virtual void CheckStarted() - 检查是否已启动

核心事件：

• event Action Started - 启动成功事件
• event Action StartFailed - 启动失败事件
• event Action Closed - 关闭成功事件
• event Action CloseFailed - 关闭失败事件

特性：

• 支持重复启动模式（构造函数参数 canRestart）
• 线程安全状态检查

7. EncodingBase：IEncoding - 编码转换

编码转换基类。

二、异常处理

1. ExceptionBase：IExceptionPublisher / ExceptionBase<T>：IExceptionPublisher<T>

提供基础的异常处理功能。

核心事件：

• event Action<Exception> ExceptionOccurred - 异常发生时触发

核心方法：

• protected void OnException(Exception ex) - 触发异常事件
• protected void CheckDispose() - 检查对象是否已释放

特性：

• 支持通过构造函数参数 throwWhenExceptionOccurredEvent 配置是否触发ExceptionOccurred事件时抛出异常
• 提供泛型版本 ExceptionBase<T>

三、配置管理

1. IReadOnlyConfigManager - 只读配置管理

提供配置的只读访问。

方法：

• T ReadConfigNode<T>(IList<string> childKeys, T defaultValue = default) - 从配置节点读取值
• bool IsTrue(IList<string> childKeys, bool defaultValue = default) - 检查节点值是否为 true

属性：

• ConfigFile - 配置文件名（如 appsettings.json）
• ConfigBasePath - 配置文件目录
• ConfigFilePath - 完整配置文件路径
• ProgramName - 程序名称
• BaseNodes - 根节点名（多级节点以 : 分割）

2. IConfigManager - 可读写配置管理

继承自 IReadOnlyConfigManager，提供配置的读写功能。

写入方法：

• void WriteConfigNode<T>(T value, IList<string> childKeys) - 写入配置节点
• Task WriteConfigNodeAsync<T>(T value, IList<string> childKeys) - 异步写入

移除方法：

• void Remove(IList<string> childKeys) - 移除配置节点
• Task RemoveAsync(IList<string> childKeys) - 异步移除

清空方法：

• void CleanAll() - 清空所有配置节点
• Task CleanAllAsync() - 异步清空

事件：

• PreSetConfig - 配置写入前触发
• SetConfig - 配置写入时触发
• PostSetConfig - 配置写入后触发

属性：

• MaxDepth - 允许写入的最大深度（默认 5）

实现类：

• ConfigManagerBase - 配置管理器基类
• ReadOnlyConfigManagerBase - 只读配置管理器基类

四、加密与签名

1. IEncrypt / EncryptBase

数据加密接口和基类。

方法：

• byte[] Encrypt(byte[] plainData) - 加密数据
• byte[] Decrypt(byte[] encryptedData) - 解密数据

实现类：

• AESEncrypt - AES 加密
• Base64Encrypt - Base64 编码
• RSAEncrypt - RSA 加密

2. ISignature / SignatureBase

数据签名接口和基类。

方法：

• byte[] Sign(byte[] data) - 签名
• bool Verify(byte[] data, byte[] signature) - 验证签名

实现类：

• HmacSha256MD5Sign - HMAC SHA256/MD5 签名
• MD5Signature - MD5 签名
• RSASignature - RSA 签名

五、事件系统

1. IEvent / IEvent<T>

事件接口。

IEvent 核心成员：

• event Action Execute - 事件执行时触发
• void Invoke() - 触发事件

IEvent<T> 核心成员：

• event Action<T> ExecuteWith - 带参数的事件执行时触发
• void Invoke(T data) - 触发带参数的事件

2. IEventMark

事件标记接口，继承自 IDisposable。

3. IEventManager / CustomEventManager

事件管理器，用于管理和获取事件实例。

IEventManager 接口核心方法：

• E GetEvent<E>() where E : IEventMark, new() - 获取指定类型的事件实例

IEventManager 接口核心属性：

• int Count - 当前管理的事件数量

实现类：

• CustomEventManager - 自定义事件管理器
  • static IEventManager Current - 当前事件管理器实例（单例）

使用方式：

1. 定义事件类实现 IEvent 或 IEvent<T> 接口
2. 通过 CustomEventManager.Current.GetEvent<MyEvent>() 获取事件实例
3. 订阅事件：myEvent.Execute += handler
4. 触发事件：myEvent.Invoke() 或 myEvent.Invoke(data)

六、对象池

1. IObjectPool / ObjectPool

对象池管理接口和实现。

IObjectPool 核心属性：

• int Count - 当前对象池中的对象数量

核心方法：

• T Get() - 从对象池获取对象
• void Return(T obj) - 将对象归还到对象池

特性：

• 高性能对象复用
• 减少内存分配和 GC 压力
• 线程安全

2. IPooledObjectPolicy / AbstractPooledObjectPolicy

对象创建策略接口和抽象基类。

IPooledObjectPolicy 核心方法：

• T Create() - 创建新对象
• bool Return(T obj) - 将对象归还到池中

实现类：

• DefaultPooledObjectPolicy - 默认对象池策略
• AbstractRecyclable - 可回收对象抽象类

七、邮件服务

1. IEmailManager / IEmailSender / IEmailReceiver

邮件管理、发送和接收接口。

IEmailSender 核心方法：

• Task SendAsync(string to, string subject, string body) - 发送邮件
• Task SendAsync(string to, string subject, string body, IEnumerable<string> attachments) - 发送带附件的邮件
• Task SendAsync(MailMessage message) - 发送自定义邮件

IEmailReceiver 核心方法：

• Task<IEnumerable<MailMessage>> ReceiveAsync() - 接收邮件

实现类：

• SmtpMailManagerBase - SMTP 邮件管理基类
• SmtpMailSender - SMTP 邮件发送器
• SmtpMailReceiver - SMTP 邮件接收器（基于 Pop3）
• SmtpMail163Manager - 163 邮箱管理器
• SmtpMailQQManager - QQ 邮箱管理器

八、热键管理

1. IHotKeyManager / IHotKey / IHotKeyGroup

全局热键管理接口。

IHotKeyManager 核心方法：

• bool Register(HotKey hotKey, Action handler) - 注册热键
• bool Unregister(HotKey hotKey) - 取消注册热键

IHotKey 核心属性：

• Key Key - 按键
• ModifierKeys Modifiers - 修饰键

实现类：

• HotKeyManagerBase - 热键管理器基类
• GlobalHotKeyManager - 全局热键管理器
• GlobalHotKey - 全局热键
• GlobalHotKeyGroup - 全局热键组
• CustomKeys - 自定义键映射
• CustomModifierKeys - 自定义修饰键

九、文件操作

工具类

CsvHelper

• IEnumerable<T> Read<T>(string filePath) - 读取 CSV 文件
• void Write<T>(string filePath, IEnumerable<T> data) - 写入 CSV 文件

IniHelper

• string Read(string section, string key) - 读取 INI 配置
• void Write(string section, string key, string value) - 写入 INI 配置

ZipHelper

• void Compress(string sourcePath, string zipPath) - 压缩文件
• void Decompress(string zipPath, string targetPath) - 解压文件

十、序列化

ISerializer / DefaultXmlSerializer

序列化接口和 XML 序列化实现。

方法：

• string Serialize<T>(T obj) - 序列化对象
• T Deserialize<T>(string json) - 反序列化对象

十一、ID 生成器

1. IIdGenerator

ID 生成器接口。

核心方法：

• string Generate() - 生成 ID
• string Generate(string prefix) - 生成带前缀的 ID

实现类：

• IdGeneratorSequentialGuid - 顺序 GUID 生成器
• IdGeneratorSnowflake - 雪花算法 ID 生成器（支持时间戳、机器ID、序列号）

十二、系统工具

工具类

Clock：IClock

• DateTime Now { get; }
• DateTimeKind Kind { get; }
• DateTime Normalize(DateTime dateTime)

AppUtils

• 断言
• IP
• 大小端
• XML
• 进程
• Windows服务 net sc installutil
• 关机、重启
• Cmd命令行执行：Shell和非Shell

AppUtils - 操作系统工具

• 软件开机自启
• 锁屏和激活窗口
• 消息弹窗
• 单进程启动

AppUtils - 计算机信息工具

• 磁盘信息

AssemblyHelper - 程序集帮助类

• Assembly Type

StopWatcher：IDisposable

• void Stop() - 停止计时
• Action<string, TimeSpan>

DisposeAction

Express

• GetMemberExpression
• ToStaticMethod<T>
• CreateParameter<T>
• CreateConstant<T>
• CreateLambda<D>

ModelHelper

• ToModel<T>
• ToTable<T>
• BuildTheModelClassFromTable
• BuildTheModelClassFromColumns

十三、HTTP 客户端

IHttpClientManager / HttpClientManager

HTTP 客户端管理器。

方法：

• HttpClient GetClient(string name) - 获取命名客户端
• void ConfigureClient(string name, Action<HttpClient> configure) - 配置客户端
• Task<T> GetAsync<T>(string url) - 异步 GET 请求
• Task<T> PostAsync<T>(string url, object data) - 异步 POST 请求

十四、设置管理

ISettingManager / SettingManager

设置管理接口和实现。

方法：

• T GetSetting<T>(string key) - 获取设置
• void SaveSetting<T>(string key, T value) - 保存设置

十五、扩展方法

1. ObjectExtensions

• As<T>() - 安全类型转换
• To<T>() - 类型转换（支持基本类型、枚举、Guid、DateTime）
• IsIn()
• IsInRange()/ LimitInRange()
• DoIf()
• DoIfNotNull()
• IsNullOr() / IsNotNullAnd()

2. StringExtensions

常用

• Get<TEnum>()
• IsNullOrBlank()

字符操作

• IsUpper(char c) - 检查字符是否大写字母
• IsLower(char c) - 检查字符是否小写字母
• ToPascal(string str)

空白处理

• TrimWhiteSpace(string str) - 移除首尾空白(支持全角空格)
• NormalizeLineEndings(string str) - 标准化换行符(统一为环境默认)
• TrimAllWhiteSpace(string str) - 移除所有空白(包括内部)

忽略大小写操作

• EqualsIgnoreCase(string left, string right) - 等价比较
• StartsWithIgnoreCase(string left, string right) - 开头匹配
• EndsWithIgnoreCase(string left, string right) - 结尾匹配
• ContainsIgnoreCase(string left, string right) - 包含判断

字符串拼接

• PackInChar(string str, string chars) - 添加前后缀
• AppendLineOr(string str, string newChars) - 追加换行或指定字符
• Join<T>(string separator, IEnumerable<T> items) - 连接集合元素

子字符串处理

• Left(string str, int len) - 获取左侧子串
• Right(string str, int len) - 获取右侧子串
• TryGetLeft(string str, int len) - 安全获取左侧
• TryGetRight(string str, int len) - 安全获取右侧
• EnsureStartsWith(string str, string chars) - 确保前缀
• EnsureEndsWith(string str, string chars) - 确保后缀

编码转换

• Base64Encode(string str) - Base64编码
• Base64Decode(string base64Str) - Base64解码
• GetHex(string str) - 转换为十六进制
• GetStringFromHex(string hexStr) - 十六进制转字符串
• ConvertEncoding(string str, Encoding from, Encoding to) - 编码转换

文本处理

• InChinese(string str) - 是否纯中文
• ContainsChinese(string str) - 包含中文检测
• ContainsEnglish(string str) - 包含英文检测
• ConvertNumber(string number, int fromBase, int toBase) - 进制转换

时间处理

• FormatTime(DateTime time, string format) - 自定义格式化
• GetWeek(DateTime time) - 获取星期几(中文)
• FormatTimeSpan(TimeSpan time) - 时间间隔格式化

颜色处理

• IsHexColorString(string colorStr) - 十六进制颜色验证
• GetContrastColor(string hexColorCode) - 获取对比色

网络相关

• IsURL(string input) - URL格式验证
• IsIPv4(string input) - IPv4地址验证

正则验证

• IsHexString(string hexStr) - 十六进制字符串验证
• IsHexColorString(string colorStr) - 颜色值验证

3. CollectionExtensions

• IsNullOrEmpty - 空值判断
• WhereIf - 条件过滤
• AddRange - 批量添加
• AddIfNotContainsKey
• AddIfNotContainsKeyAsync
• GetOrAdd
• GetOrAddAsync
• AddIfItemNotWhileOrNotExists
• AddIfItemsNotWhileOrNotContains
• AddIfNotAnyWhile
• RemoveAll
• ForEach
• ReSizeToArray
• FillToArray

4. FileExtensions

1. 路径验证

• IsValidPath() - 验证路径有效性
• IsDirectoryExists() - 检查目录是否存在
• IsFileExists() - 检查文件是否存在
• CheckPathValid() - 验证路径并检查条件

2. 目录操作

• TryCreateDir() - 递归创建目录
• TryCreateTodayDir() - 创建当天日期目录
• DeleteDirectory() - 删除目录(包含子目录)
• DeleteDirIfEmptyOr() - 条件删除空目录

3. 路径处理

• GetFullPath() - 获取完整路径
• GetParentPath() - 获取父目录路径
• GetFileName() - 获取文件名
• GetExtension() - 获取文件扩展名
• HasExtension() - 检查是否有扩展名

4. 文件操作

• DeleteFileIfExistOr() - 条件删除文件
• CopyDirContentTo() - 递归复制目录内容
• CopyDirTo() - 复制整个目录

5. 内容获取

• GetContents() - 获取目录内容(文件和子目录)
• GetFiles() - 获取目录中的文件列表

5. ExpressionExtensions

表达式扩展方法。

方法：

• ToPropertyOrField() - 创建属性或字段表达式
• ToAnd() / ToOr() - 创建与/或运算表达式
• ToEqual() / ToNotEqual() - 创建等于/不等于表达式
• ToGreater() / ToGreaterEqual() - 创建大于/大于等于表达式
• ToLess() / ToLessEqual() - 创建小于/小于等于表达式
• ToStartsWith() / ToEndsWith() / ToContains() - 创建字符串匹配表达式
• ToOperation() - 根据运算符创建运算表达式
• ToUnstaticMethod() - 创建调用非静态方法表达式
• ToLambda<TDelegate>() - 创建 Lambda 表达式

6. MemberInfoExtensions

反射扩展方法。

方法：

• GetTableName() TableAttribute
• GetColumnName() ColumnAttribute
• GetDescription>() DescriptionAttribute
• GetDisplayName() DisplayNameAttribute
• GetEnumDescriptions()
• GetRealColumn()
• IsChildOfGenericType()
• IsChildOfUnGenericType()
• IsGenericCollection()

7. LockExtensions

• Locking()

8. SemaphoreSlimExtensions

信号量扩展方法。

方法：

• LockAsync()
• Lock()

9. ObjectCreateExtensions

• CreateWithExpression
• CreateWithReflect

10. ReaderWriterLockSlimExtensions

• GetReadLock
• GetWriteLock

十六、常量定义

RegexConstants

常用正则表达式常量。

十七、数据缓冲记录器

1. IBufferRecorder (位于IceTea.Pure.Contracts.Data命名空间)

通用的缓冲数据记录器接口，用于高性能记录任意类型数据。

核心方法：

• IBufferRecorder Write(object data) - 写入数据到缓冲区
• void Flush() - 立即刷新缓冲区（从IFlusher继承）

实现类：

• BufferRecorderBase - 缓冲记录器基类（位于 Utils.Datas 命名空间）
  • 使用并发队列实现线程安全写入
  • 自动批量处理（默认1000条/批）
  • 动态调整写入间隔（50-500ms）
  • 内置错误处理和恢复机制
  • 抽象方法供派生类实现：
    • FormatEntry - 格式化数据条目
    • CreateWriter - 创建写入器

适用场景：

• 高频数据记录（如传感器数据、审计日志等）
• 需要减少IO操作的应用
• 批量数据处理场景

十九、日志系统

1. ILogger

日志记录器接口，提供标准化的日志记录功能。

核心属性：

• EnumLogLevel MinLogLevel { get; set; } - 获取或设置日志级别，低于此级别的日志不会被记录

核心方法：

• ILogger Log(string message, EnumLogLevel level = EnumLogLevel.Info) - 记录日志
• ILogger Info(string message) - 记录信息级别日志
• ILogger Warning(string message) - 记录警告级别日志
• ILogger Debug(string message) - 记录调试级别日志
• ILogger Error(string message) - 记录错误级别日志
• ILogger Error(Exception exception, string message = null) - 记录异常日志

日志级别枚举（EnumLogLevel）：

• Debug - 调试级别（0）
• Info - 信息级别（1）
• Warning - 警告级别（2）
• Error - 错误级别（3）

日志系统架构：

1. 基础实现

• LoggerBase（抽象类）
  • ILogger接口的核心实现
  • 提供日志格式化、写入器管理等基础功能
  • 位于IceTea.Pure.Utils.Logs.Loggers

2. 缓冲日志实现（IBufferLogger）

• BufferLoggerBase（抽象类）
  • 继承自LoggerBase的基础缓冲实现
  • 高性能并发队列设计
• FileBufferedLogger（具体实现）
  • 支持按日期和级别自动分文件
  • 内置批量写入优化

3. 即时日志实现（IImmediateLogger）

• ImmediateLoggerBase（抽象类）
  • 继承自LoggerBase的即时写入基础实现
• FileImmediateLogger（具体实现）
  • 日志即时写入文件
  • 适用于关键操作场景

特性：

• 统一实现IDisposable接口确保资源释放
• 线程安全设计
• 灵活的扩展接口

特性：

• 支持链式调用
• 线程安全设计
• 异常记录支持自动附加异常类型和堆栈信息

二十、其他接口

1. IName / IBackup

IName 核心属性和方法：

• string Name { get; set; } - 名称
• string GetFullName() - 获取完整名称

IBackup 核心方法：

• void CreateBackup(string backupName) - 创建备份
• void RestoreBackup(string backupName) - 恢复备份

2. IRegister / IReset

IRegister 核心方法：

• bool Register(object item) - 注册项目
• bool Unregister(object item) - 取消注册项目

IReset 核心方法：

• void Reset() - 重置

3. ISubmit / IGoBack

ISubmit 核心方法：

• bool Submit() - 提交

IGoBack 核心方法：

• void GoBack() - 返回上一级

4. IClock

核心属性：

• DateTime Now { get; } - 当前本地时间
• DateTime UtcNow { get; } - 当前 UTC 时间

5. IProxy

核心方法：

• T CreateProxy<T>() - 创建代理
• object Invoke(MethodInfo method, object[] args) - 调用方法

6. IChildren / ICloneable

ICloneable 核心方法：

• T Clone<T>() - 克隆对象

7. IFlusher

核心方法：

• void Flush() - 刷新缓冲区

8. IEncoding / IStarter

IStarter 核心方法：

• Task<bool> StartAsync() - 启动
• Task CloseAsync() - 关闭

使用指南

IceTea.Pure 提供了一系列基类、工具类和接口，您可以根据需要选择使用：

1. 创建可通知属性的模型：继承 NotifyBase
2. 实现可启停服务：继承 StarterBase 并重写 StartAsyncCore 和 CloseAsyncCore
3. 管理配置：继承 ConfigManagerBase 实现自定义配置管理
4. 使用加密功能：使用 AESEncrypt、RSAEncrypt 等实现类
5. 使用对象池：通过 ObjectPool<T> 和 IPooledObjectPolicy<T> 实现对象复用
6. 发送邮件：使用 SmtpMailSender 或预置的 SmtpMail163Manager、SmtpMailQQManager
7. 管理热键：使用 GlobalHotKeyManager 注册全局热键
8. 处理文件：使用 CsvHelper、IniHelper、ZipHelper 处理常见文件格式
9. 记录日志：使用 Logger 进行高性能日志记录，支持按日期分文件和多级别存储
10. 缓冲记录：实现 IBufferRecorder 接口创建自定义缓冲数据记录器

许可证

MIT License

作者

WuMing

贡献

欢迎提交 Issue 和 Pull Request！