JCoder 3.2631.1

JCoder

目录

• 一.架构说明
  • 1.1 引用类库
  • 1.2 相关类库
  • 1.3 模块结构
  • 1.4 重要更新
• 二.获取方式
• 三.使用说明
  • 3.1 主要类与接口
  • 3.2 扩展方法（Extension）
  • 3.3 数据转换（ORM）
  • 3.4 数据校验（Verification）
  • 3.5 存储容器（Storage）
  • 3.6 预操作（Preaction）
  • 3.7 工具类（Utility）
• 实例使用

一.架构说明

1.1 引用类库

1.2 相关类库

说明：JCoder.CoreKits 已于 v2.0 合并入本库，JCoder.Data 已于 v2.14 合并入本库，不再单独发布。

1.3 模块结构

1.4 重要更新

更多历史版本及变更内容请参考 NuGet 发布记录。

二.获取方式

1. 建议使用最新版本（当前最新版本以 3.2630.1 为例）。

三.使用说明

3.1 主要类与接口

1) Attributes（特性）

2) Delegate（委托与事件参数）

3) Extension（扩展方法）

4) ORM（数据转换）

5) Preaction（预操作）

6) Storage（存储容器）

7) Utility（工具类）

8) Verification（数据校验）

3.2 扩展方法（Extension）

1. Array

using JCoder;

var _array = new string[] { "11", "22" };

// Foreach 遍历所有项
_array.Foreach(x => Console.Write(x));
// Foreach 遍历所有项（带下标）
_array.Foreach((i, x) => Console.Write($"第{i}个值为：{x}"));

// 判断 Array 是否为空或者为 Null
bool _isEmpty = _array.IsEmptyOrNull();

// 带转换条件的遍历转数组 / 列表
object[] _converted = _array.ToArray(x => $"【{x}】");

2. String

using JCoder;

// 以指定文本为分隔符，截取文本（include 表示是否包含分隔符本身）
"abc12323df".LeftAt("2", true)      // "abc12"
"abc12323df".LeftAt("2", false)     // "abc1"
"abc12323df".RightAt("2", true)     // "23df"
"abc12323df".RightAt("2", false)    // "3df"

// 截取指定长度的文本
"abc12323df".Left(2)                // "ab"
"abc12323df".Right(2)               // "df"

// 移除指定文本（左/右/全部）
"abc12323df".RemoveLeft("abc")      // "12323df"
"abc12323df".RemoveRight("df")      // "abc12323"
"abc-123-23df".Remove("-")          // "abc12323df"

// 拆分文本
"a,b,c".SplitByChar(',')            // ["a","b","c"]
"a||b".SplitByString("||")          // ["a","b"]

// 正则表达式支持
"Abc123".HasMatch(@"\d+")           // true
"Abc123".GetMatch(@"\d+")           // "123"
"abc123def".ReplaceMatch(@"\d+", "X") // "abcXdef"
"abc123def".RemoveMatch(@"\d+")     // "abcdef"

// 文本判断
"yes".IsPositive()                  // true
"no".IsNegative()                   // true
"123".IsInt()                       // true
"12.5".IsNumber()                   // true
"Abc".IsEnglish()                   // true

// 文本列表合并
new List<string> { "a", "b", "c" }.Concat(",")  // "a,b,c"

3. Value（IConvertible 转换）

using JCoder;

"123".ToValue<int>()               // String => Int
"AA123".ToValue<int>(-1)           // String => Int, Output: -1

"2026-01-01".ToValue<DateTime>()   // String => DateTime

"123".ToValue<double>()            // String => Double
"A123".ToValue<double>(-1.0)       // String => Double, Output: -1.0

"true".ToValue<bool>()             // String => Boolean
"true11".ToValue<bool>(false)      // String => Boolean, Output: false

4. Number（数值判断）

using JCoder;

123.IsBetween(100, 200)            // true
3.14d.IsBetween(3.0, 4.0)          // true
10.5f.IsBetween(0, 100)            // true

5. Byte（位操作与字节转换）

using JCoder;

byte _b = 0b1010_1100;

bool _bit = _b.GetBit(7);          // 获取第7位（最高位）的值 => true
_b = _b.SetBit(0, true);           // 设置第0位（最低位）为 true

// 字节数组与数值互转（默认小端序，HL 后缀为大端序）
long _value = new byte[] { 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 }.BytesToInt64(); // 1
byte[] _bytes = 1024L.Int64ToBytes();

6. DateTime

using JCoder;

// 当前日期在一年中的第几周（周日为一周的第一天）
int _week = DateTime.Now.WeekOfYear();

#if NET5_0_OR_GREATER
// DateOnly => DateTime（.Net 5+）
DateTime _dt = new DateOnly(2026, 1, 1).ToDateTime();
#endif

7. Enum（枚举）

using JCoder;
using System.ComponentModel;

public enum Status
{
    [Description("启用")]
    Enabled,
    [Description("禁用")]
    Disabled,
}

// 获取枚举值的 Description
string _desc = Status.Enabled.GetEnumDescription();          // "启用"

// 获取枚举类型的 Description 列表
List<string> _descs = typeof(Status).GetEnumDescriptions(); // ["启用","禁用"]

// 根据名称获取枚举值
Status _status = "Disabled".ToEnum<Status>() ?? default;    // Status.Disabled

// 获取枚举的所有值
List<Status> _values = Enumeration.GetEnums<Status>();

8. DataTable

using JCoder;
using System.Data;

DataTable _table = new DataTable();
_table.Columns.Add("Name", typeof(string));
_table.Columns.Add("Age", typeof(int));
_table.Rows.Add("Jackie", 18);

// 获取首行首列值
string _name = _table.GetFirstValue<string>();              // "Jackie"

// 获取指定列的值（按列名或列索引）
int _age = _table.GetColumnValue<int>("Age");               // 18

// 获取指定列的整列值
List<string> _names = _table.GetColumnValues<string>("Name");

// 将两列转换为字典
Dictionary<string, int> _dict = _table.ToDictionary<string, int>("Name", "Age");

// 尝试取值（失败返回默认值）
int _try = _table.TryGetColumnValue<int>("Age") ?? 0;       // 18

9. Dictionary

using JCoder;

var _dict = new Dictionary<string, string> { ["age"] = "18" };

int _age = _dict.ToValue<int>("age");                       // 18
int _safe = _dict.ToValue<int>("no", -1);                   // -1（键不存在时返回默认值）
int? _try = _dict.TryToValue<int>("no");                    // null（键不存在时返回 null）

10. 反射遍历（属性/方法/事件/字段）

using JCoder;

var _obj = new User { Name = "Jackie", Age = 18 };

// 属性是否存在 / 设置属性值
bool _has = _obj.ExistProperty("Name");
_obj.SetPropertyValue("Age", 20);

// 遍历所有属性
_obj.ForProperties((name, value) => Console.WriteLine($"{name}={value}"));

// 调用方法
object _ret = _obj.RunMethod("ToString", new object[0]);

// 遍历所有方法
_obj.ForMethods(m => Console.WriteLine(m.Name));

// 遍历所有字段
_obj.ForFields((name, value) => Console.WriteLine($"{name}={value}"));

11. Type（类型判断）

using JCoder;

typeof(int).IsNumberType()                              // true（数值类型）
typeof(int?).IsNullable()                               // true（可空类型）
typeof(int).GetTypeOfNullable()                         // System.Nullable<int>（获取可空类型）
typeof(List<int>).IsBaseOn(typeof(IEnumerable<int>))    // true（是否基于/实现了指定类型）
typeof(DateTime).IsTimeType()                           // true（时间类型）
typeof(string).IsBaseOn(typeof(object))                 // true（继承关系）

3.3 数据转换（ORM）

1. 数据源 ⇒ 实体（支持 DataTable、DataReader、DataRow、Dictionary）

using JCoder;
using System.Data;

public class User
{
    public string Name { get; set; }
    public int Age { get; set; }
}

DataTable _table = new DataTable();
_table.Columns.Add("Name", typeof(string));
_table.Columns.Add("Age", typeof(int));
_table.Rows.Add("Jackie", 18);
_table.Rows.Add("Lucy", 25);

// DataTable => List<User>（属性方式）
List<User> _users = _table.ToObjects<User>();

// DataTable 首行 => User
User _first = _table.ToObject1st<User>();

// DataRow => User
User _rowUser = _table.Rows[0].ToObject<User>();

// DataTable => List<User>（特性方式，支持 tag）
List<User> _entities = _table.ToEntities<User>();

// DataTable => 实体字典（以指定列作为键）
Dictionary<string, User> _dict = _table.ToEntityDictionary<User>("Name");

// 将数据填充到已有对象
var _target = new User();
_table.Rows[0].FillInEntity(_target);

2. 实体 / 列表 ⇒ DataTable

using JCoder;
using System.Data;

List<User> _list = new List<User>
{
    new User { Name = "Jackie", Age = 18 },
    new User { Name = "Lucy", Age = 25 },
};

// List<Entity> => DataTable
DataTable _table = _list.ListToDataTable();

// 单个 Entity => DataTable
User _single = new User { Name = "Tom", Age = 30 };
DataTable _singleTable = _single.ToDataTable();

// 特性方式（配合 TableColumnAttribute 等自定义列名/顺序）
DataTable _entityTable = _list.EntitiesToDataTable();

3. 实体 ⇒ Dictionary

using JCoder;

// 属性方式：将实体属性转换为 Dictionary<string, string>
Dictionary<string, string> _dict = new User { Name = "Jackie", Age = 18 }.ObjectToDictionary();

// 特性方式：配合 NameAttribute 等自定义键名，支持 tag
Dictionary<string, string> _entityDict = new User { Name = "Jackie" }.EntityToDictionary();

4. ComparedTo（对象比较）

using JCoder;

// 比较两个对象的公共属性值是否完全一致
bool _same = Orm.ComparedTo(userA, userB);

3.4 数据校验（Verification）

1. 基本用法

using JCoder;

public class User
{
    [VerifyRequired("姓名", IsRequired = true)]
    [VerifyString(MinLength = 2, MaxLength = 20)]
    public string Name { get; set; }

    [VerifyNumber(Method = VerificationMethod.Greater, Value = 0)]
    public int Age { get; set; }
}

var _user = new User { Name = "Jackie", Age = 18 };
VerifyResult _result = Verification.VerifyObject(_user);
// _result.IsValid => true
// _result.Message  => ""

var _badUser = new User { Name = "", Age = -1 };
VerifyResult _badResult = Verification.VerifyObject(_badUser);
// _badResult.IsValid => false
// _badResult.Message  => 包含校验失败信息

2. 常见属性值类型的校验特性

using JCoder;
using System.ComponentModel;

public enum Status
{
    [Description("启用")] Enabled,
    [Description("禁用")] Disabled,
}

public class Product
{
    // 文本：长度 / 内容 / 忽略大小写
    [VerifyString(Method = VerificationMethod.Contains, Value = "https", IgnoreCase = true)]
    public string Url { get; set; }

    // 数值：范围 / 列表
    [VerifyNumber(Method = VerificationMethod.Between, Value = 1, Value2 = 100)]
    public int Level { get; set; }

    [VerifyNumber(Method = VerificationMethod.IN, Values = new double[] { 1, 2, 3 })]
    public int Type { get; set; }

    // 日期：格式 / 比较 / 范围
    [VerifyDate(Format = "yyyy-MM-dd", MinValue = "2020-01-01", MaxValue = "2030-12-31")]
    public DateTime PublishDate { get; set; }

    // 时间：TimeSpan / TimeOnly / 时刻
    [VerifyTime(Method = VerificationMethod.Between, Value = "08:00:00", Value2 = "18:00:00")]
    public TimeSpan WorkTime { get; set; }

    // 布尔：相等比较
    [VerifyBool(Method = VerificationMethod.Equal, Value = true)]
    public bool IsOnline { get; set; }

    // GUID：非空（Guid.Empty 视为无效）/ 相等 / 列表
    [VerifyGuid]
    public Guid Id { get; set; }

    // 枚举：值已定义 / 白名单 / 列表
    [VerifyEnum(Values = new object[] { Status.Enabled })]
    public Status Status { get; set; }

    // 集合：数量 / 非空 / 范围
    [VerifyCollection(MinCount = 1, MaxCount = 10)]
    public List<string> Tags { get; set; }

    // 正则：模式匹配（默认 Match，可设 NotMatch）
    [VerifyPattern(Pattern = @"^1[3-9]\d{9}$")]
    public string Phone { get; set; }

    // 嵌套对象：递归校验
    [VerifyObject]
    public Address Address { get; set; }
}

3. 校验单个属性（含强类型入口）

using JCoder;

// 反射方式：按 PropertyInfo 校验
bool _ok = Verification.VerifyProperty(_user, typeof(User).GetProperty("Name"), out var _msg);

// 强类型方式：按属性选择器校验（推荐）
VerifyResult _r1 = Verification.VerifyProperty(_user, x => x.Name);
bool _r2 = Verification.VerifyProperty(_user, x => x.Age, out var _msg2);

4. 分组组合（AND / OR）

using JCoder;

// VID 用于标记分组中的属性
// 手机号或邮箱至少提供一个（OR 组合）
[VerifyGroup(VerificationConnctor.OR, 1, 2)]
public class Order
{
    [VerifyRequired(1, "手机号", IsRequired = true)]
    public string Phone { get; set; }

    [VerifyRequired(2, "邮箱", IsRequired = true)]
    public string Email { get; set; }
}

5. 失败消息与占位符

• 默认失败消息模板由 VerificationMethod 决定；可通过 FailedMessage 自定义，支持以下占位符：

[VerifyString(MinLength = 2, MaxLength = 20, FailedMessage = "{Name} 长度需在 2 到 20 之间，当前值：{PropertyValue}")]
public string Name { get; set; }

• 常用校验特性：VerifyRequiredAttribute（必填）、VerifyStringAttribute（文本）、VerifyNumberAttribute（数值）、VerifyDateAttribute（日期）、VerifyTimeAttribute（时间）、VerifyBoolAttribute（布尔）、VerifyGuidAttribute（GUID）、VerifyEnumAttribute（枚举）、VerifyCollectionAttribute（集合）、VerifyPatternAttribute（正则）、VerifyObjectAttribute（嵌套对象）、VerifyGroupAttribute（分组组合）。
• 校验方法枚举 VerificationMethod：NotNull、IsNull、NotEmpty、Equal、NotEqual、Greater、GreaterOrEqual、Less、LessOrEqual、IN、NotIN、Between、NotBetween、Contains、NotContains、Started、NotStarted、Ended、NotEnded、Match、NotMatch。
• 校验组合枚举 VerificationConnctor：AND、OR。

3.5 存储容器（Storage）

1. Storage<TItem>（string 键存储）

using JCoder;

var _storage = new Storage<User>();

// 注册（存在同键时不覆盖）
_storage.Register("key1", new User { Name = "Jackie", Age = 18 });
// 注册或更新（存在时通过工厂更新）
_storage.RegisterOrUpdate("key2", new User(), (key, old) => old);

// 获取
User _user = _storage.Get("key1");
bool _exist = _storage.IsExist("key1");

// 移除 / 清空
_storage.Unregister("key1");
_storage.Clear();

2. UStorage<TItem>（Type 键单例容器）

using JCoder;

var _singletons = new UStorage<object>();

// 按类型注册单例
_singletons.Register(new User());
// 按类型创建并注册单例（调用无参构造）
_singletons.Register(typeof(User));

// 获取
bool _ok = _singletons.TryGet(typeof(User), out object _item);
bool _exist = _singletons.IsExist(typeof(User));

3.6 预操作（Preaction）

using JCoder;

var _caller = new PreactionCaller();

// 注册预操作（以 Key 区分）
_caller.Add("check", (sender, e) =>
{
    Console.WriteLine($"Key={e.Key}, Parameter={e.Parameter}, Tag={e.Tag}");
    return true; // 返回 true 表示继续执行
});

// 同步调用
bool _ok1 = _caller.Call("check", "parameter");
// 异步调用
bool _ok2 = await _caller.CallAsync("check");

3.7 工具类（Utility）

1. FilePath（路径处理）

using JCoder;

bool _isAbs = FilePath.IsAbsPath(@"C:\root\file.txt");        // true
string _ext = FilePath.GetFileExtension(@"C:\root\file.txt"); // ".txt"
string _name = FilePath.GetFileNameWithoutExtension(@"C:\root\file.txt"); // "file"
string _combined = FilePath.CombinePath(@"C:\root", @"sub\file.txt");    // C:\root\sub\file.txt
string _rel = FilePath.ToRelativePath(@"C:\root", @"C:\root\sub\file.txt"); // sub\file.txt
string _abs = FilePath.ToAbsPath(@"C:\root", @"sub\file.txt");           // C:\root\sub\file.txt

2. Numeral（进制转换）

using JCoder;

// 十进制转其他进制（支持 2/8/10/16/32/64 进制）
string _hex = Numeral.ToNumberString(255, NumeralSystem.Hexadecimal); // "FF"
string _bin = Numeral.ToNumberString(255, NumeralSystem.Binary);      // "11111111"

// 其他进制转十进制
int _dec = Numeral.ToDecimalism32("FF", numberSystem: NumeralSystem.Hexadecimal);   // 255
long _dec64 = Numeral.ToDecimalism64("11111111", numberSystem: NumeralSystem.Binary); // 255

3. Valuation（类型转换）

using JCoder;

int _i = "123".ToValue<int>();                     // 123
DateTime _dt = "2026-01-01".ToValue<DateTime>();   // 2026-01-01
TimeSpan _ts = "01:30:00".ToValue<TimeSpan>();     // 01:30:00
DateOnly _date = "2026-01-01".ToDate();            // 2026-01-01（.Net 6+）
TimeOnly _time = "13:30:00".ToTime();              // 13:30:00（.Net 6+）

// 转换失败返回默认值
int _safe = Valuation.ToInt("abc");                // 0
double _safe2 = "A123".ToValue<double>(-1.0);      // -1.0

4. Reflection（反射辅助）

using JCoder;

// 获取成员值
object _value = Reflection.GetMemberValue(typeof(User).GetProperty("Name"), _user);

// 获取调用链中的方法
MethodBase _called = Reflection.GetMethodCalled();
MethodBase _trace = Reflection.GetMethodByTrace(1);

5. AssemblyUtility（程序集处理）

using JCoder;
using System.Reflection;

// 获取程序集中的类型列表（可带过滤条件）
List<Type> _types = Assembly.GetExecutingAssembly().GetTypeList(t => t.IsClass);

// 获取指定类型的所有子类型
List<Type> _subs = Assembly.GetExecutingAssembly().GetSubTypes(typeof(IInterface));

实例使用

1. 参考JCoder