SuperAPI AI 工具集

dotnet-aot-compat

编程与开发

查看项目

更新于 11-01 00:28

技能介绍

用途

dotnet-aot-compat 用于让 .NET 项目兼容 Native AOT 与 IL 裁剪,具体做法是系统性地解决 IL 裁剪/AOT 分析器产生的全部警告。典型使用场景包括:让项目 AOT 兼容、修复裁剪警告或 IL 警告、处理 IL2070/IL2067/IL2072/IL2026/IL3050 等警告码、添加 DynamicallyAccessedMembers 注解、在 .csproj 中启用 IsAotCompatible、升级到 net8.0 后处理裁剪分析器警告、为裁剪器注解反射代码。

适用前提与不适用情况

需要已有 .NET 项目,目标框架为 net8.0 或更高,或采用多目标且至少一个 TFM 为 net8.0+,并安装相应 .NET SDK。若项目仅面向 .NET Framework(net4x),则不支持裁剪/AOT 分析器,不应使用本技能。

背景原理

Native AOT 与 IL 裁剪器通过静态分析确定哪些代码可达。反射会破坏这种分析,因为裁剪器无法看到运行时访问了哪些类型和成员。IsAotCompatible 属性会启用分析器,把这些问题作为构建警告(ILXXXX 代码)暴露出来。注解流是关键:裁剪器会沿着赋值、参数传递和返回值追踪 [DynamicallyAccessedMembers] 注解;一旦流被打断(例如把 Type 装箱进 object、存入无类型集合或经接口转换),裁剪器就会丢失追踪并报警。正确做法是保持注解流,而不是压制警告。

关键规则

不得对 IL 警告使用 #pragma warning disable:它只在构建期对 Roslyn 分析器隐藏警告,IL 链接器和 AOT 编译器仍能看到问题,代码会在裁剪/发布时失败。不得使用 [UnconditionalSuppressMessage],因为它同时让分析器和链接器忽略警告,使裁剪器无法验证安全性。优先使用 [DynamicallyAccessedMembers] 注解把类型信息沿调用链传递;优先重构以消除破坏注解流的模式(例如通过 object[] 装箱 Type);使用 [RequiresUnreferencedCode]、[RequiresDynamicCode]、[RequiresAssemblyFiles] 标记本质上不兼容裁剪的方法,把要求传播给调用方,让调用方显式确认不兼容性。

使用方式(步骤)

不要预先浏览代码库,构建警告会直接指出需要修改的文件和行。遵循紧凑循环:构建 → 选一个警告 → 打开对应文件行 → 应用修复方案 → 重新构建。第一步在 .csproj 中启用 AOT 分析:若项目并非仅面向 net8.0+,需加 TFM 条件,示例属性组为 <PropertyGroup> <IsAotCompatible Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">true</IsAotCompatible> </PropertyGroup>,它会为兼容 TFM 自动设置 EnableTrimAnalyzer 与 EnableAotAnalyzer,多目标项目可避免旧 TFM 上出现 NETSDK1210 警告。

第二步构建并收集警告,例如执行 dotnet build <project.csproj> -f <net8.0-or-later-tfm> --no-incremental 2>&1 | grep 'IL[0-9]{4}',然后排序去重。常见警告码包括:IL2070(对缺少 DynamicallyAccessedMembers 的 Type 参数做反射调用)、IL2067(把未注解的 Type 传给需要注解的方法)、IL2072(返回值或提取值缺少注解,常来自拆箱)、IL2057(Type.GetType(string) 使用非常量参数)、IL2026(调用标记了 RequiresUnreferencedCode 的方法)、IL2050(带 COM 封送参数的 P/invoke)、IL2075(返回值流入反射却无注解)、IL2091(泛型实参缺少约束要求的 DynamicallyAccessedMembers)、IL3000(单文件/AOT 应用中 Assembly.Location 返回空字符串)、IL3050(调用标记了 RequiresDynamicCode 的方法)。

第三步按警告码分类并统计数量,暂不打开单个文件,找出数量最多的 1–2 种模式来制定修复策略。多数真实项目中来自 JsonSerializer 的 IL2026/IL3050 占主导,此时应优先采用源生成 JSON 的批量修复策略,再处理其余警告。

第四步由内向外迭代修复:只打开编译器报告的文件与行,识别模式并应用对应方案,每次修一小批(5–10 个)后立即重建检查进度。若可启动子代理,可并行编辑不同文件,主循环负责构建、解析警告和分派。策略 A:为使用反射的 Type 参数添加 [DynamicallyAccessedMembers],例如 void Process([DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicMethods)] Type t),注解会向外级联,调用方的注解必须至少覆盖被调用方要求的成员类型。策略 B:重构以保持注解流,例如把装箱在 object[] 中的 Type 提取为独立的已注解参数,或改用带注解的强类型字段替代 Dictionary/List 存储、给接口方法参数加注解、为装箱的属性返回类型加注解。策略 C:改用源生成 JSON 序列化,收集所有 JsonSerializer.Serialize/Deserialize 调用点涉及的类型,创建带 [JsonSerializable] 的 JsonSerializerContext(不加入不归你所有的外部包类型),再批量把调用点改为传入上下文,如 JsonSerializer.Serialize(obj, MyProjectJsonContext.Default.TypeName) 与 JsonSerializer.Deserialize(json, MyProjectJsonContext.Default.TypeName);不要用 sed 处理 C# 代码,因泛型尖括号与嵌套括号会被破坏。策略 D:对本质上需要任意反射、无法静态描述的方法使用 [RequiresUnreferencedCode("说明")],该要求会传播给调用方,应谨慎使用。

第五步每修一小批即用 --no-incremental 重建,修复会级联产生新警告,重复直到 0 Warning(s)。第六步验证所有 TFM:net8.0+ 上 0 个 IL 警告、无 NETSDK1210 警告、旧 TFM(netstandard2.0、net472 等)构建干净,可执行 dotnet build <project.csproj> 构建全部 TFM。多目标项目若包含 netstandard2.0 或 net472,需要为 DynamicallyAccessedMembersAttribute 及相关类型提供 polyfill。

停止信号

每种警告模式最多分析 2–3 个代表性文件,确定修复后批量套用而不再逐个阅读;一次构建后即开始修复,不做第二轮分析;net8.0+ TFM 达到 0 IL 警告即停止,不再优化已干净的注解;若某警告需要超出注解流的架构级重构(如替换整个序列化层),记录后停止,不重写大型子系统;单个警告最多 3 轮构建-修复,仍未解决则升级为 [RequiresUnreferencedCode];不追查无法修改的第三方依赖中的警告;用户问题若有范围限制则不扩大到整个项目。

常见注意事项

不带 AOT 安全序列化的外部类型:若依赖中的类型(如 Azure.Core 的 ResponseError)缺少源生成序列化器,Options.GetConverter<T>() 基于反射会产生 IL 警告。先检查是否实现 IJsonModel<T>,若是则绕过 JsonSerializer,例如序列化改用 ((IJsonModel<ResponseError>)errorValue).Write(writer, ModelReaderWriterOptions.Json),反序列化改用 ((IJsonModel<ResponseError>)new ResponseError()).Create(ref reader, ModelReaderWriterOptions.Json);不要把外部类型加入自己的 JsonSerializerContext;若不实现 IJsonModel<T>,则编写使用 Utf8JsonReader/Utf8JsonWriter 的自定义 JsonConverter<T> 并在上下文上通过 [JsonSourceGenerationOptions] 注册。序列化库方面,多数基于反射的序列化器(如 Newtonsoft.Json、XmlSerializer)不兼容 AOT,应迁移到基于源生成的序列化器(如带 JsonSerializerContext 的 System.Text.Json),无法迁移时用 [RequiresUnreferencedCode] 标记调用点。共享项目/projitems 中,通过 <Import> 共享的源码所加的注解会影响所有引用项目,需验证所有使用者仍构建干净。

限制

资料仅给出以上流程与注意事项,未提供该技能的安装方式、运行环境、收费模式、版本支持范围或效果保证等事实,暂未提供。