TianWeiToolsPro.Common 3.1.0

TianWeiToolsPro.Common

TianWeiToolsPro.Common 是天威开发的通用基础库，主要沉淀一些项目内高频复用的能力：扩展方法、校验/检测工具、日志能力、MVVM 基类、命令与事件总线等。

目标框架

该项目为多目标框架（TFM）构建（以 TianWeiToolsPro.Common.csproj 为准），当前工作区包含：

• .NET Framework 4.7.2
• .NET Framework 4.8
• .NET 6 (Windows)
• .NET 8 (Windows)
• .NET 10 (Windows)

命名空间概览

Extensions

• ArrayExtension：数组/集合相关扩展，简化常用操作（以源码为准）
• CheckExtension：常用“检测/校验/范围判断/CRC”扩展（以源码为准）
• SerializerExtension：序列化相关扩展（以源码为准）

CheckExtension 常用示例

引入：

using TianWeiToolsPro.Common.Extensions;

范围判断（泛型，基于 IComparable<T>）：

var ok1 = 10.InRange(1, 100);                 // true
var ok2 = 10.InRange(1, 10, true, false);     // [1,10) => false

集合/数组判空：

int[] a = null;
bool isEmpty = a.IsNullOrEmpty();

截断（Clamp）：

int v = 120;
int clamped = v.Clamp(0, 100); // 100

数组安全取值：

var arr = new[] { 1, 2, 3 };
var x1 = arr.GetOrDefault(1);        // 2
var x2 = arr.GetOrDefault(99, -1);   // -1

CRC / 校验：

byte[] data = { 0x01, 0x02, 0x03 };

byte crc8 = data.GetCrc8();
byte[] crc16 = data.GetCrc16_Modbus();
byte[] crc32 = data.GetCrc32();

byte checkSum = data.GetCheckSum();

说明：项目中如已存在 StringExtension.IsNullOrEmpty(string) 等扩展，请避免在 CheckExtension 中重复声明同名 string 扩展，以免出现调用二义性（CS0121）。

Logger

• LoggerEx：增强的日志记录能力，支持多种输出方式与格式，支持外部配置记录类型、按文件夹存储、限制单文件大小等（以实现为准）。

Mvvm

• BindableBase：属性更改通知基类，简化 ViewModel 编写
• ViewModelBase：ViewModel 基类（如存在/以源码为准）

Commands

• DelegateCommand：基于委托的命令实现，简化命令创建与绑定

Events

• EaHelper：事件总线助手，用于模块间通信，降低强引用与耦合。
• TEventArgs<T>：事件载体（字符串参数名版本），用于兼容旧代码。
• TEventArgs<TParaName, TValue>：事件载体（枚举参数名版本，TParaName : Enum），推荐新项目使用，便于类型安全与跨项目扩展。

Events 使用建议（推荐：枚举参数名）

当事件需要通过“参数名/事件类型”区分不同消息时，推荐在业务项目中定义一个枚举，并使用 TEventArgs<TParaName, TValue> 作为载体，避免字符串拼写错误，便于重构。

示例：

// 业务项目中自定义事件类型
public enum AppEventTypes
{
    PlcConnectStateChanged,
    ScannerConnectStateChanged,
    InputData,
    OutputData,
}

// 发布
EaHelper.Publish(new TEventArgs<AppEventTypes, bool>(this, AppEventTypes.PlcConnectStateChanged, true));

// 订阅
EaHelper.Subscribe<AppEventTypes, bool>(args =>
{
    if (args.ParaName == AppEventTypes.PlcConnectStateChanged)
    {
        var connected = args.Value;
    }
});

兼容性说明：如果你已有大量历史代码使用字符串参数名（TEventArgs<T> + ParaName 为 string），可以继续保留该用法；新代码建议逐步迁移到枚举参数名版本。

约定与建议

• 扩展方法尽量保持“无副作用、无状态、可复用”。
• 兼容 .NET Framework 目标时，避免依赖仅 .NET 7+ 的接口（如 INumber<T>）。
• 若出现扩展方法重名冲突，优先在单一位置维护（或通过更明确的命名规避）。

变更记录 2026-01-10 16:30

• 优化了CheckExtension中扩展方法的性能表现，比如 InRange 方法。采用更高效的比较逻辑，减少不必要的装箱操作。
• 优化了ConvertExtension中扩展方法。