企业官网建设流程全解析

如何使用 RunApiDiff.ps1 生成两个 .NET 版本之间的 API 差异报告

【免费下载链接】core.NET news, announcements, release notes, and more!项目地址: https://gitcode.com/GitHub_Trending/core82/core

如果你需要在 dotnet/core 仓库中发布某个 .NET 版本的 API 变更说明（即api-diff报告），手动从两个 runtime 包中比接口既不现实也容易漏项。仓库自带的 RunApiDiff.ps1 脚本可以自动完成这件事：它从 NuGet 源下载"之前"和"之后"两个版本的 SDK 包，调用apidiff工具生成符合 dotnet/core 发布格式的 API 对比报告。脚本位于 release-notes/RunApiDiff.md 说明的release-notes/目录下，运行环境要求 PowerShell 7.0 或更高版本。

准备条件

1. PowerShell 7.0+

文档明确的前提是 PowerShell 7.0 或更高版本，低版本无法运行该脚本。

2. 安装 ApiDiff 工具

脚本依赖Microsoft.DotNet.ApiDiff.Tool这个 .NET 全局工具，脚本运行时通过get-command "apidiff"检查它是否可用。有两种安装方式：

方式一：使用脚本自带的-InstallApiDiff开关，让脚本从当前版本的 transport feed 自动安装或更新该工具（feed 地址由脚本按CurrentMajorMinor的主版本号拼接）：

.\RunApiDiff.ps1 -InstallApiDiff <其他参数>

方式二：手动安装。{MAJOR}需要替换为当前版本的主版本号（例如11.0对应11）：

dotnet tool install --global Microsoft.DotNet.ApiDiff.Tool --source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet{MAJOR}-transport/nuget/v3/index.json --prerelease

如果跳过安装直接运行脚本且apidiff命令不存在，脚本会报错并停止，同时打印上面这条安装命令供你执行。

3. 本地仓库克隆

脚本默认以自身所在目录的 git 仓库根目录作为输出根（-CoreRepo参数）。如果你把脚本放在别的目录运行，或希望报告写到指定克隆里，显式传-CoreRepo：

.\RunApiDiff.ps1 -CoreRepo /path/to/dotnet-core-clone

其中/path/to/dotnet-core-clone替换为你本地 dotnet/core 仓库克隆的绝对路径。报告最终写入该仓库的release-notes/树中，因此这个仓库必须可写。

版本如何确定：不传参数的行为

不带任何参数运行时，脚本会扫描仓库中已有的api-diff文件夹，找到最新的版本，再按版本演进序列（preview.1 → preview.2 → … → preview.7 → rc.1 → rc.2 → GA → 下一个大版本的 preview.1）推断"当前版本"，并探测 dotnet-public feed 确认该版本包已发布。例如仓库中最新的 api-diff 是 .NET 10 GA 时，它会自动为 .NET 11 Preview 1 生成报告：

.\RunApiDiff.ps1

运行后留意脚本的输出：Latest existing api-diff: ...显示它识别到的最新版本，Discovered next version from feed: ...显示推断出的当前版本。如果 feed 上探测不到下一个版本，脚本会报错并提示显式指定-CurrentMajorMinor和-CurrentPrereleaseLabel。

显式指定两个要对比的版本

大多数情况下你会明确知道要比哪两个版本，直接传参数更可靠。参数分两类：

按主版本 + 预发布标签指定（GA 版本省略PrereleaseLabel参数）：

# 显式指定两个版本 .\RunApiDiff.ps1 ` -PreviousMajorMinor 10.0 -PreviousPrereleaseLabel preview.7 ` -CurrentMajorMinor 10.0 -CurrentPrereleaseLabel rc.1 # 对比 RC 与 GA；GA 侧省略 CurrentPrereleaseLabel .\RunApiDiff.ps1 ` -PreviousMajorMinor 10.0 -PreviousPrereleaseLabel rc.2 ` -CurrentMajorMinor 10.0

PrereleaseLabel支持alpha、beta、preview、rc四种标签（如preview.7、rc.1）。MajorMinor与PrereleaseLabel相同时脚本会直接报错终止，避免生成无意义的空对比。

只指定一侧，另一侧自动推断：例如只给当前版本，"之前"版本从已有 api-diff 推断：

.\RunApiDiff.ps1 -CurrentMajorMinor 11.0 -CurrentPrereleaseLabel preview.4

按精确 NuGet 包版本指定：MajorMinor和PrereleaseLabel会从版本字符串中自动解析：

.\RunApiDiff.ps1 ` -PreviousVersion "10.0.0-preview.7.25380.108" ` -CurrentVersion "10.0.0-rc.1.25451.107"

版本字符串需符合X.Y.Z或X.Y.Z-<label>.N格式（<label>为 alpha/beta/preview/rc 之一），可再跟构建元数据。

其他常用参数

NuGet 源：默认两个方向都从 dotnet-public feed 下载包（https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public/nuget/v3/index.json）。如果某个版本的包只发布在特定 feed 上，单独指定对应侧即可：

.\RunApiDiff.ps1 ` -CurrentNuGetFeed "https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet11/nuget/v3/index.json"

PreviousNuGetFeed同理，用于"之前"版本的包。

排除某个 SDK：脚本默认对比三个共享框架。按需加开关跳过：

其他路径参数：

排除清单文件如果传相对路径，脚本会相对脚本所在目录解析。

输出位置与结果验证

脚本会为每个参与对比的 SDK 依次执行"下载 before 包 → 下载 after 包 → 运行 apidiff → 写报告"，全部完成后生成一个README.md汇总页。报告写入以下位置之一：

• 预发布里程碑（preview/rc/alpha/beta）：release-notes/{MajorMinor}/preview/{里程碑文件夹}/api-diff，里程碑文件夹形如preview1、rc2、ga；
• 两个不同主版本的 GA 对比：release-notes/{MajorMinor}/{MajorMinor}.{序号}/api-diff（例如release-notes/10.0/10.0.0/api-diff）。

验证要点按运行顺序看：

1. 脚本先输出解析到的版本（Parsed from ...、Inferred previous version: ...、Discovered next version from feed: ...）与使用的 feed（Using default current feed: ...），确认对比的就是你想要的两个版本；
2. 新目录创建时会输出Creating new diff folder: <完整路径>，这是报告落盘位置；
3. 运行结束后到该api-diff目录检查：应有一个README.md和各 SDK 的报告文件。仓库里已有的 release-notes/10.0/api-diff/README.md 就是这类报告的形态，它按 SDK 列出入口链接，例如 10.0.0.md 这种按程序集分文件的明细报告；
4. 明细报告中+开头的行是新增 API，-开头的行是移除的 API（报告头部有说明）。

常见报错与限制

• apidiff命令未找到：脚本打印安装命令后停止。按"准备条件"中的方式安装后重跑即可。
• 前后版本相同：Previous and current versions are the same (...)错误。检查两个 feed 是否指向了同一版本，或显式传版本参数。
• 无法推断当前版本：Could not discover the next version from feed ...错误。说明 feed 上还没有下一个里程碑的包，显式指定-CurrentMajorMinor和-CurrentPrereleaseLabel，或等包发布后再运行。
• 版本字符串解析失败：ParseVersionString只接受X.Y.Z或X.Y.Z-<alpha|beta|preview|rc>.N形式，其他格式的 feed 版本会被跳过；若你显式传入的-PreviousVersion/-CurrentVersion不符合该格式会直接报错。

脚本只生成报告文件，不会替你提交到仓库；生成后的报告需要按 dotnet/core 的发布流程自行审阅并提交。参考文档中给出的实际产出示例是 .NET 10 GA 到 .NET 11 Preview 1 的 API diff PR，你可以对照仓库中已有的 release-notes/10.0/api-diff 目录了解最终成品的组织方式。

【免费下载链接】core.NET news, announcements, release notes, and more!项目地址: https://gitcode.com/GitHub_Trending/core82/core