如何使用 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对应11dotnet 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 与 GAGA 侧省略 CurrentPrereleaseLabel .\RunApiDiff.ps1 -PreviousMajorMinor 10.0 -PreviousPrereleaseLabel rc.2 -CurrentMajorMinor 10.0PrereleaseLabel支持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.jsonPreviousNuGetFeed同理用于之前版本的包。排除某个 SDK脚本默认对比三个共享框架。按需加开关跳过开关作用-ExcludeNetCore跳过 Microsoft.NETCore.App 的对比-ExcludeAspNetCore跳过 Microsoft.AspNetCore.App 的对比-ExcludeWindowsDesktop跳过 Microsoft.WindowsDesktop.App 的对比其他路径参数参数默认值用途-TmpFolder自动创建的临时目录下载和解压包的中间目录-AttributesToExcludeFilePath脚本同目录的ApiDiffAttributesToExclude.txt属性排除清单见 ApiDiffAttributesToExclude.txt-AssembliesToExcludeFilePath脚本同目录的ApiDiffAssembliesToExclude.txt程序集排除清单见 ApiDiffAssembliesToExclude.txt排除清单文件如果传相对路径脚本会相对脚本所在目录解析。输出位置与结果验证脚本会为每个参与对比的 SDK 依次执行下载 before 包 → 下载 after 包 → 运行 apidiff → 写报告全部完成后生成一个README.md汇总页。报告写入以下位置之一预发布里程碑preview/rc/alpha/betarelease-notes/{MajorMinor}/preview/{里程碑文件夹}/api-diff里程碑文件夹形如preview1、rc2、ga两个不同主版本的 GA 对比release-notes/{MajorMinor}/{MajorMinor}.{序号}/api-diff例如release-notes/10.0/10.0.0/api-diff。验证要点按运行顺序看脚本先输出解析到的版本Parsed from ...、Inferred previous version: ...、Discovered next version from feed: ...与使用的 feedUsing default current feed: ...确认对比的就是你想要的两个版本新目录创建时会输出Creating new diff folder: 完整路径这是报告落盘位置运行结束后到该api-diff目录检查应有一个README.md和各 SDK 的报告文件。仓库里已有的 release-notes/10.0/api-diff/README.md 就是这类报告的形态它按 SDK 列出入口链接例如 10.0.0.md 这种按程序集分文件的明细报告明细报告中开头的行是新增 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考