dotnet/runtime项目：如何正确更新引用程序集源码

dotnet/runtime项目：如何正确更新引用程序集源码

runtime .NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps. 项目地址: https://gitcode.com/gh_mirrors/runtime6/runtime

前言

在dotnet/runtime项目中，当我们需要向实现程序集添加新的公共API时，必须同步更新对应的引用程序集。本文将从技术原理和实践操作两个维度，详细介绍这一过程的完整工作流程。

基本概念解析

在开始之前，我们需要明确几个关键概念：

1. 实现程序集：包含实际代码实现的程序集
2. 引用程序集：仅包含公共API定义的特殊程序集，用于编译时引用
3. GenAPI工具：自动生成引用程序集源码的工具

引用程序集的存在使得开发者可以在不依赖完整实现的情况下进行编译，这是.NET生态系统中的重要设计。

标准库程序集的更新流程

对于大多数库程序集，更新引用程序集的步骤如下：

第一步：实现API并构建源程序集

1. 在源程序集中实现新API
2. 执行构建命令：dotnet build /p:ApiCompatValidateAssemblies=false

技术细节：当添加新的公共类型时，可能会遇到TypeMustExist错误。这是因为API兼容性检查会在构建时验证类型存在性。通过设置ApiCompatValidateAssemblies=false可以暂时禁用这一检查。

第二步：使用GenAPI工具更新引用程序集

1. 从src目录运行命令：dotnet msbuild /t:GenerateReferenceAssemblySource
2. 检查生成的引用源码，通常需要手动修复一些差异

最佳实践：

• 避免完全手动编辑引用源码，这会导致与工具生成的代码产生偏差
• 如果API已添加到引用源中，重新生成会将其更新为完全限定形式并正确排序

第三步：构建引用程序集

1. 导航到ref目录
2. 执行构建命令验证引用程序集

第四步：添加并运行测试

完成上述步骤后，应当添加相应的测试用例来验证新API的功能。

特殊程序集的处理

System.Runtime程序集

System.Runtime是核心程序集，其更新流程稍有不同：

1. 从System.Runtime/src目录运行：dotnet build --no-incremental /t:GenerateReferenceAssemblySource
2. 过滤掉不相关的变更，只保留关心的修改

注意：这一步通常需要忽略某些被移除的属性，这是正常现象。

完整外观程序集

对于作为其他程序集"完整外观"的实现程序集（如System.Runtime.Serialization.Json），需要使用特殊命令：

dotnet msbuild /t:GenerateReferenceAssemblySource /p:GenAPIFollowTypeForwards=true

这个命令会考虑类型转发关系，确保生成的引用源码正确。

.NETFramework外观程序集

对于需要在.NETFramework上转发类型的程序集：

1. 必须手动为每个存在于.NETFramework中的类型添加类型转发(TypeForward)
2. 对于在.NETFramework引用中定义的类型，应该将其放入共享源文件中

常见问题与解决方案

1. GenAPI生成大量不匹配：这是正常现象，需要手动检查并修复关键差异
2. 类型顺序问题：重新生成引用源码通常会解决排序问题
3. 属性差异：某些属性可能在引用程序集中被有意省略

总结

更新引用程序集是dotnet/runtime项目中添加新API的关键步骤。通过理解不同类型程序集的处理方式，开发者可以高效完成这项工作。记住始终优先使用工具生成引用源码，仅在必要时进行手动调整，这样可以最大程度保持引用程序集与实现程序集的一致性。

掌握这些流程不仅能帮助开发者正确贡献代码，也有助于理解.NET运行时中程序集设计的精妙之处。

runtime .NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps. 项目地址: https://gitcode.com/gh_mirrors/runtime6/runtime