用途:验证并跟踪 .NET 库的公共 API 表面,在 CI 中拦截未声明的 API 变更与破坏性改动。
主要能力:
- PublicApiAnalyzers:用提交到源码管理的文本文件跟踪每个公共 API 成员,强制新 API 先进入 unshipped 阶段再标记 shipped。安装方式为在 ItemGroup 中添加 PackageReference Include="Microsoft.CodeAnalysis.PublicApiAnalyzers" Version="3.3.*" PrivateAssets="all"。需在项目根目录创建 PublicAPI.Shipped.txt 与 PublicAPI.Unshipped.txt,两者必须存在且含 #nullable enable 头。常见诊断:RS0016(成员未声明)、RS0017(已移除但仍在跟踪文件)、RS0024、RS0025、RS0026、RS0036、RS0037。发布时将 Unshipped 条目移入 Shipped 并清空 Unshipped。多 TFM 项目可设 RoslynPublicApiPerTfm 为 true,使用 PublicAPI.Shipped.net8.0.txt 等按 TFM 文件。CI 中可将 RS0016;RS0017;RS0036;RS0037 加入 WarningsAsErrors 实现门禁。
- Verify 快照:通过反射枚举程序集全部公共类型与成员,生成可读快照并提交,任何 API 变化都会导致测试失败,需显式批准。失败时对比 .received.txt 与 .verified.txt,确认后用 verify accept 接受。
- ApiCompat CI 门禁:可设 EnablePackageValidation 为 true 并指定 PackageValidationBaselineVersion,在 dotnet pack 时校验;或用独立工具 dotnet tool install --global Microsoft.DotNet.ApiCompat.Tool,以 apicompat --left-assembly 与 --right-assembly 比较程序集。可结合 PR 标签提示 API 变更;有意破坏性变更可用 dotnet pack /p:GenerateCompatibilitySuppressionFile=true 生成抑制文件,并通过 ApiCompatSuppressionFile 引用。
适用场景:.NET 8.0+ 库项目、多 TFM 与 monorepo 的 API 跟踪、PR 门禁与发布流程。
限制:二进制与源码兼容规则、类型转发、SemVer 影响、NuGet 打包、Verify 基础配置、通用 Roslyn 分析器配置、HTTP API 版本控制均不在本技能范围内,需参考其他技能。资料中 ApiCompatSuppressionFile 部分内容被截断,具体细节暂未提供。