Channing.Cloner 1.0.5

Channing.Cloner

高性能、AOT 友好的 .NET 深度克隆框架，基于 Emit + 源生成器双引擎实现。

功能特性

• 双引擎克隆：运行时使用 Emit 动态生成 IL 代码，编译时通过源生成器生成静态克隆代码
• 多框架兼容：net451、netstandard2.0、netcoreapp2.0、net8.0 四个目标框架全覆盖
• 深度克隆：支持对象、数组、列表、字典、匿名类型、嵌套对象的深拷贝
• 循环引用检测：自动追踪已克隆对象，防止循环引用导致栈溢出
• AOT 友好：net8.0 目标标记 IsAotCompatible=true，支持 Native AOT 发布
• 特性控制：[CloneIgnore]、[ClonePrimaryKey]、[NonCloneable]、[CloneColumn] 等特性精细控制克隆行为
• 只读集合支持：自动克隆仅有 Add 方法的只读集合属性（清空目标并填充克隆项）
• 克隆设置：支持 CloneFieldMode（字段/属性/两者）、CloneDepth（克隆深度）、OnCreateInstance（自定义实例创建）
• 中文 XML 文档：公开 API 完整中文注释，F12 查看定义时显示中文说明
• 代码混淆：Release 构建自动使用 Obfuscar 混淆私有实现，保留公共 API

安装

dotnet add package Channing.Cloner

快速上手

using Channing.Cloner;

// 简单深拷贝
var cloned = myObject.Clone();

// 带设置的克隆
var cloned = myObject.Clone(new CloneSettings
{
    CloneFieldMode = CloneFieldMode.FieldsOnly,
    MaxDepth = 50,
    OnCreateInstance = type => /* 自定义实例创建 */ null
});

// 克隆到现有对象（无需重新分配内存）
target.CloneFrom(source);

// 异步克隆
var cloned = await myObject.CloneAsync();

版本日志

v1.0.5 (2026-08-02)

Bug Fixes:

• 修复源生成器在【无无参构造函数】场景下生成 new T() 导致 CS7036 编译错误的问题：当目标类型仅有带参构造函数（如 MVVM Toolkit 的 ViewModel）时，源生成器现在自动改用 FormatterServices.GetUninitializedObject(typeof(T)) 跳过构造函数创建实例，深克隆与浅克隆两处均已修复
• 修复运行时 SlowCloneReferenceType 在带参构造函数且参数名与属性名不匹配时抛出 "no usable constructor" 的问题：引入 FormatterServices.GetUninitializedObject 作为终极 fallback，跳过构造函数直接分配对象后逐字段复制
• 修复构造函数查找仅使用 BindingFlags.Public 导致找不到 protected/internal 无参构造函数的问题（如继承 ObservableObject 的子类）：现使用 Public | NonPublic | Instance 标志
• 修复 icon.png 作为 <Content> 项流入消费项目并在解决方案资源管理器中显示的问题：改为 <None> + PackageIconUrl，仅作为 NuGet 包元数据存在

Features:

• 完整支持 CommunityToolkit.Mvvm 的 ObservableObject 继承场景：涵盖 [ObservableProperty] 源生成属性、[RelayCommand] 源生成命令、ObservableCollection<T> 集合、手动 SetProperty INPC 属性、自引用嵌套对象
• 新增 CloneDispatcher.IsRegistered(Type) 诊断 API：查询某类型是否已由源生成器自注册克隆委托（走零反射路径），便于区分源生成器路径与 Emit/反射后备路径

Testing:

• 修正测试项目对源生成器的引用方式（OutputItemType="Analyzer"），此前源生成器从未在测试项目中运行，[Clonable] 标记形同虚设
• 新增 Clone_ToolkitObservableItem1_WithOnlyParameterizedCtor_DeepClonesAllMembers 测试，并通过 RuntimeHelpers.RunClassConstructor + IsRegistered 断言验证源生成器路径实际生效
• 测试覆盖：net8.0 72 个、net472 68 个全部通过

v1.0.4 (2026-07-31)

项目重构：

• 整体架构重构为三项目分层：Channing.Cloner.Abstractions（抽象层）+ Channing.Cloner.Runtime（运行时）+ Channing.Cloner.SourceGenerator（源生成器），统一打包为单一 NuGet 包 Channing.Cloner
• 多框架支持扩展至 net451、netstandard2.0、netcoreapp2.0、net8.0 四个目标框架
• net8.0 目标标记 IsAotCompatible=true，恢复 AOT 友好支持（通过源生成器路径实现，无需反射 Emit）

Features:

• 双引擎克隆架构：运行时使用 Emit 动态生成 IL 代码，编译时通过源生成器生成静态克隆代码，自动选择最优路径
• 全局配置体系：新增 CloneConfig 配置类，支持 DefaultMode、DefaultFieldMode、MaxDepth、ThrowOnDepthExceeded、命名空间过滤（IncludeNamespaces/IncludeTypes/ExcludeTypes）、命名约定（NameConventions）
• 二级缓存：新增 ISecondaryCacheProvider 接口与 EnableSecondaryCache 选项，支持克隆结果缓存，避免重复克隆开销
• 变更通知代理：新增 EnableChangeNotification 与 GenerateNotificationProxy 选项，自动生成 INotifyPropertyChanged 代理
• 代理类型解包：新增 IProxyUnwrapper 接口，自动识别并解包 EF 等框架的动态代理类型
• 克隆策略注册：新增 ICloneStrategy 接口与 CloneStrategyRegistry，支持注册自定义类型的克隆策略
• 克隆自定义器：新增 ICloneCustomizer<T> 接口，支持克隆完成后的自定义处理
• 缓存清理策略：新增 ICachePolicy 接口，提供 SlidingTimePolicy、SizePolicy、CompositePolicy 等多种清理策略
• 反射元数据缓存：新增 ReflectionMetadataCache，缓存字段/属性元数据，提升反射性能
• 动态对象克隆：新增 CloneDynamic 方法，支持 dynamic 与匿名类型克隆
• 快速实例创建：新增 CreateInstance<T> 方法，绕过构造函数约束快速创建实例
• 反射缓存访问：新增 GetCloneFields/GetCloneProperties/GetField/GetProperty 扩展方法，统一访问克隆元数据
• 集合类型辅助：新增 GetListItemType 扩展方法，解析集合元素类型
• 代理相关 API：新增 CreateProxyInstance、ActAsInterface 方法（非 netstandard2.0），支持通知代理与接口适配
• 全局配置管理：新增 SetDefaultOptions、InvalidateCache、ClearCache、AddStrategy、WrapForNotification 等全局 API

特性增强：

• 新增 [ClonableAttribute]：标记类型可被克隆，源生成器据此生成克隆代码
• 新增 [NotifyIgnoreAttribute]：标记成员变更时不触发缓存失效
• 增强 [CloneColumnAttribute]：支持点号分隔的嵌套路径映射（如 "Child.Name"）

文档与分发：

• 开启 GenerateDocumentationFile，公开 API 完整中文 XML 文档随包分发，F12 查看定义时显示中文注释
• Release 构建集成 Obfuscar 代码混淆：保留公共 API，重命名字段与内部实现，使用 Unicode 字符增加逆向难度
• NuGet 包正式带上版本号、作者 ChanningMou(牟成贵)、公司 ChanningMou 等元数据

v1.0.3 (2026-07-26)

Bug Fixes:

• 修复 CloneTo 方法跳过只读集合属性的问题（自引用 NestedCollections 等只读集合现在能被正确克隆）

Features:

• 新增 CloneTo 方法对只读集合属性的支持（清空目标集合并填充克隆项）
• 新增自引用只读集合递归克隆测试（List<T> 中 T 包含自身类型的只读集合属性）
• 新增异步克隆方法 CloneAsync的深拷贝
• 新增源生成器支持，编译时生成克隆代码，提升性能
• 移出AOT支持，之前版本AOT支持不完整，且性能不佳，建议使用源生成器方式

v1.0.2 (2026-07-24)

Bug Fixes:

• 修复 CloneFieldMode.Both 模式下字段和属性合并逻辑，字段优先
• 修复 FieldInfo 模式下自动属性的 backing field 被错误克隆的问题

Features:

• 新增只读集合属性克隆功能（支持仅有 Add 方法而无 set 的只读属性，自动克隆集合内元素及嵌套对象）
• 新增 CloneSettings 完整测试覆盖（CloneFieldMode、CloneDepth、OnCreateInstance）
• 新增 CloneColumn 特性支持嵌套路径映射（如 "Child.Name"）
• 新增 CloneTo 方法递归深度保护，防止栈溢出（默认限制 100 层）
• 重构 Value 和 ValueByType 方法，使用策略模式实现类型转换
• 新增类型转换器：NumericTypeConverter、DateTimeTypeConverter、BoolTypeConverter、TimeSpanTypeConverter、EnumTypeConverter、GuidTypeConverter、StringTypeConverter、ByteArrayTypeConverter

v1.0.1 (2026-07-23)

Initial Release:

• 支持对象、数组、列表、字典、匿名类型的深拷贝
• 支持多框架目标：netcoreapp2.0、net451、netstandard2.0、netstandard1.3
• 支持循环引用检测
• 支持特性控制：[CloneIgnore]、[ClonePrimaryKey]、[NonCloneable]
• Release 构建自动混淆

作者与联系方式

• 作者: ChanningMou (牟成贵)
• 公司: ChanningMou
• 邮箱: 2538777526@qq.com

License

MIT