用途:让 .NET 项目兼容 Native AOT 与 IL 裁剪,通过系统性消除 IL 裁剪/AOT 分析器警告(ILXXXX)达成目标。适用于“让项目 AOT 兼容”“修复裁剪/IL 警告”“解决 IL2070/IL2067/IL2072/IL2026/IL3050”“添加 DynamicallyAccessedMembers 注解”“在 .csproj 启用 IsAotCompatible”等请求。不适用于仅面向 .NET Framework(net4x)的项目,因其不支持裁剪/AOT 分析器。
前提:已有面向 net8.0 或更高版本(或多目标且至少含一个 net8.0+ TFM)的 .NET 项目,并安装对应 SDK。
主要能力与规则:Native AOT 与裁剪器通过静态分析判断可达代码,反射会破坏该分析。IsAotCompatible 属性会启用分析器,将问题标记为构建警告。禁止用 #pragma warning disable 或 [UnconditionalSuppressMessage] 抑制 IL 警告,否则裁剪/发布时仍会失败。优先使用 [DynamicallyAccessedMembers] 注解让类型信息沿调用链流动;优先重构以消除破坏注解流动的模式(如把 Type 装箱进 object[]);必要时用 [RequiresUnreferencedCode]/[RequiresDynamicCode]/[RequiresAssemblyFiles] 标记方法并传播给调用者。
使用方式:先启用分析,在 .csproj 添加 <IsAotCompatible Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">true</IsAotCompatible>;再构建收集警告:dotnet build <project.csproj> -f <net8.0-or-later-tfm> --no-incremental 2>&1 | grep 'IL[0-9]{4}';按警告码分组,从最内层反射调用向外修复,每修 5-10 条即重建。常见策略:A 添加 [DynamicallyAccessedMembers];B 重构保持注解流动;C 对 JsonSerializer 批量改用源生成 JsonSerializerContext;D 最后才用 [RequiresUnreferencedCode]。最后构建所有 TFM 验证 0 警告。
限制:不要预先探索代码库,让编译器引导;每个警告模式最多分析 2-3 个代表文件;每个警告最多 3 次构建-修复迭代,否则升级为 [RequiresUnreferencedCode];不追逐无法修改的第三方依赖警告;若需大规模架构重构(如替换整个序列化层)应记录并停止。多目标含 netstandard2.0/net472 时需 polyfill。外部类型若无 AOT 安全序列化,可检查是否实现 IJsonModel<T>,否则写自定义 JsonConverter<T>。基于反射的序列化器(如 Newtonsoft.Json、XmlSerializer)通常不兼容 AOT,需迁移到源生成方案。