在 .NET 项目中启用并修复 Native…

适用于需要让 .NET 项目（net8.0+）兼容 Native AOT 和裁剪，并系统修复 IL2026、IL2070 等分析器警告的场景。

适用场景

解决思路

1. 在 .csproj 中添加 `<IsAotCompatible>`；如果项目不是仅面向 net8.0+，使用 TFM 条件：`<IsAotCompatible Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">true</IsAotCompatible>`。这会自动为兼容 TFM 设置 `EnableTrimAnalyzer=true` 和 `EnableAotAnalyzer=true`；对于多目标项目，条件可避免旧 TFM 上的 `NETSDK1210` 警告。
2. 构建并收集警告：运行 `dotnet build <project.csproj> -f <net8.0-or-later-tfm> --no-incremental 2>&1 | grep 'IL[0-9]\{4\}'`，排序去重。常见警告代码：IL2070、IL2067、IL2072、IL2057、IL2026、IL2050、IL2075、IL2091、IL3000、IL3050。
3. 按警告代码分类：按警告代码分组并计数，不要打开文件。识别前 1-2 个模式。如果许多 IL2026 + IL3050 来自 `JsonSerializer`，直接转到 Strategy C 批量修复。IL2070/IL2087 在 `Type` 参数上，给最内层方法加 `[DynamicallyAccessedMembers]` 然后向外级联。IL2067 传递未注解的 `Type`，在源头注解参数。
4. 迭代修复警告（从最内层开始）：从最内层反射调用向外处理。每个修复可能给调用者带来新警告。保持警告驱动：只打开编译器报告的文件和行，识别模式，应用对应修复配方，然后继续。不要扫描整个代码库寻找类似模式。每修复 5-10 个警告后立即重建。如果可用子代理，并行派发多个子代理编辑不同文件；主循环专注于构建、解析警告和派发；批量 JSON 更新时，每个子代理处理 5-10 个文件；2 轮构建-修复后，剩余文件编辑全部派发给子代理并行处理，不要顺序修复。
5. Strategy A：添加 `[DynamicallyAccessedMembers]`（首选）。当方法对 `Type` 参数使用反射时，给参数注解，例如 `void Process([DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicMethods)] Type t)`。注解参数时，所有调用者必须传递正确注解的类型，并向外级联；调用者的注解必须包含至少与被调用者相同的成员类型（如被调用者需要 `PublicConstructors | NonPublicConstructors`，调用者需相同或超集，否则产生 IL2091）。
6. Strategy B：重构以保留注解流。当注解流被装箱破坏（将 `Type` 存入 `object`、`object[]` 或无类型集合），重构为直接传递 `Type`。常见模式：`object[]` 参数包，提取 `Type` 到专用注解参数；Dictionary/List 存储，使用带注解的类型化字段；接口间接，给接口方法参数添加注解；带装箱 getter 的属性，给属性返回类型添加注解。
7. Strategy C：源生成 JSON 序列化（批量修复）。当大部分警告是来自 `JsonSerializer.Serialize`/`Deserialize` 的 IL2026/IL3050 时，执行以下步骤：收集受影响类型：grep 所有 `JsonSerializer.Serialize` 和 `JsonSerializer.Deserialize` 调用点，提取序列化的类型（`Deserialize<T>` 的 `<T>`，或 `Serialize` 中对象的运行时类型）。创建一个 `JsonSerializerContext`，为每个找到的类型添加 `[JsonSerializable]`；跳过外部包的类型，不要添加你不拥有的类型。批量更新所有调用点：`JsonSerializer.Serialize(obj)` → `JsonSerializer.Serialize(obj, MyProjectJsonContext.Default.TypeName)`；`JsonSerializer.Deserialize<T>(json)` → `JsonSerializer.Deserialize(json, MyProjectJsonContext.Default.TypeName)`。用 `grep -rl 'JsonSerializer\.\(Serialize\|Deserialize\)' src/ --include='*.cs'` 查找所有文件，然后用顺序 `edit` 调用应用相同转换；不要用 `sed` 处理 C# 代码。构建一次验证。
8. Strategy D：`[RequiresUnreferencedCode]`（最后手段）。当方法从根本上需要无法静态描述的任意反射时，用 `[RequiresUnreferencedCode("原因")]` 标记，例如 `[RequiresUnreferencedCode("Loads plugins by name using Assembly.Load")]`。这会传播给调用者，它们也必须注解；谨慎使用，它将整个调用链标记为 trim 不兼容。
9. Step 5：重建并重复。每修复一小批（5-10 个警告）后，用 `--no-incremental` 重建并检查新警告。不要试图修复所有警告后再重建；重复直到 `0 Warning(s)`。
10. Step 6：验证所有 TFM。运行 `dotnet build <project.csproj>` 构建所有目标框架，确保：net8.0+ TFM 上 0 IL 警告；没有 `NETSDK1210` 警告（`IsAotCompatible` 条件已处理）；旧 TFM（netstandard2.0、net472 等）干净构建。
11. 遵循停止信号：不要为每个警告模式分析超过 2-3 个代表性文件，识别修复后应用到所有匹配文件而不先读取每个文件；一次构建后开始修复，不做第二次分析；达到 net8.0+ TFM 的 0 IL 警告后停止，不要优化或重构已经干净的注解；如果警告需要架构重构超出注解流修复，记录并停止；每个警告限制 3 次构建-修复迭代，如果 3 次尝试后未解决，升级到 `[RequiresUnreferencedCode]`；不要追查无法修改的第三方依赖中的警告，记录并继续；如果用户要求了范围问题，不要扩展到整个项目。
12. 为旧 TFM 提供 polyfills：对于包含 netstandard2.0 或 net472 的多目标项目，为 `DynamicallyAccessedMembersAttribute` 及相关类型提供 polyfills，参考 references/polyfills.md。
13. 处理外部类型缺少 AOT 安全序列化：检查类型是否实现 `IJsonModel<T>`（Azure SDK 常见），如果是，完全绕过 `JsonSerializer`：序列化用 `((IJsonModel<ResponseError>)errorValue).Write(writer, ModelReaderWriterOptions.Json)`，反序列化用 `var error = ((IJsonModel<ResponseError>)new ResponseError()).Create(ref reader, ModelReaderWriterOptions.Json)`。不要将外部类型添加到 `JsonSerializerContext`；如果未实现 `IJsonModel<T>`，编写自定义 `JsonConverter<T>` 并使用手动 `Utf8JsonReader`/`Utf8JsonWriter` 逻辑，通过 `[JsonSourceGenerationOptions]` 在上下文中注册。
14. 迁移序列化库：大多数基于反射的序列化器（如 `Newtonsoft.Json`、`XmlSerializer`）不兼容 AOT，迁移到基于源生成的序列化器，如带 `JsonSerializerContext` 的 `System.Text.Json`；如果迁移不可行，用 `[RequiresUnreferencedCode]` 标记序列化调用点。
15. 注意共享项目/projitems：当源代码通过 `<Import>` 在多个项目之间共享时，添加到共享代码的注解会影响所有消费项目；验证所有消费者仍然干净构建。
16. 禁止错误地抑制警告：绝不要使用 `#pragma warning disable` 处理 IL 警告——它隐藏 Roslyn 分析器警告，但 IL 链接器和 AOT 编译器仍看到问题，代码将在 trim/publish 时失败；绝不要使用 `[UnconditionalSuppressMessage]`——它告诉分析器和链接器都忽略警告，trimmer 无法验证安全性，构建时错误总是优于隐藏问题并在运行时静默破坏。
17. 优先使用正确方法：优先使用 `[DynamicallyAccessedMembers]` 注解将类型信息流经调用链；优先重构以消除破坏注解流的模式（例如通过 `object[]` 装箱 `Type`）；使用 `[RequiresUnreferencedCode]` / `[RequiresDynamicCode]` / `[RequiresAssemblyFiles]` 标记方法为从根本上不兼容 trim，将要求传播给调用者，调用者必须显式承认不兼容。
18. 保留注解流：trimmer 通过赋值、参数传递和返回值跟踪 `[DynamicallyAccessedMembers]` 注解；如果流被破坏（如将 `Type` 装箱到 `object`、存储在无类型集合中、或通过接口转换），trimmer 会失去跟踪并警告；修复是保留流，而不是抑制警告。
19. 不要预先探索代码库：不要运行 `find`、`ls` 或 `grep` 来理解项目结构；不要读 README、docs 或架构文件；第一个动作应该是 Step 1（启用 AOT 分析），然后构建；跟随紧密循环：build → pick a warning → open that file at that line → apply the fix recipe → rebuild。

适用边界 · 注意事项

• 项目专门面向 .NET Framework (net4x) 时，不支持 trim/AOT 分析器，不要使用。
• 不用于发布 native AOT 二进制、优化二进制大小、或用替代方案替换反射密集型库。