run-apichief

运行 ApiChief

使用 eng/Tools/ApiChief/README.md 中记录的 ApiChief 工具，检查或刷新 src/ 下项目的 EF Core 公共 API 基线。

ApiChief 可以针对已编译的程序集或先前生成的基线 JSON 文件运行。优先使用仓库本地的 .dotnet SDK 和仓库中已提交的构建脚本。

命令

命令	说明	额外参数
emit baseline	生成 JSON API 基线	-o <file>
emit summary	生成便于阅读的 API 摘要	-o <file>、-x
emit review	生成 API 审查文件	-o <dir>、-n
emit delta	根据现有基线生成差异，或生成 Markdown 差异审查文件	<baseline-path>、-o <file-or-dir>、--diff
check breaking	如果与基线相比存在破坏性更改，则失败	<baseline-path>

如果用户只要求“运行 ApiChief”，默认执行 emit baseline。

工作流

1. 确定目标项目

• 根据用户意图匹配 src/ 下的项目文件夹。
• 只有目标不明确时才请求澄清。
• 此仓库中已提交基线的路径约定为 src/<ProjectName>/<ProjectName>.baseline.json。
• 如果用户只要求更新基线，则运行 EFCore.ApiBaseline.Tests 测试，并跳过以下其余步骤。

2. 准备环境

在构建或运行工具之前，始终先初始化仓库环境：

.\restore.cmd
. .\activate.ps1
dotnet build .\eng\Tools\ApiChief\ApiChief.csproj --nologo --verbosity q

在 Bash 上：

./restore.sh
. ./activate.sh
dotnet build ./eng/Tools/ApiChief/ApiChief.csproj --nologo --verbosity q

3. 确保目标二进制文件存在

ApiChief 需要处理已构建的程序集。如果目标项目尚未构建，请先构建。

优先使用以下选项：

# Refreshes checked-in baselines after the normal build
.\build.cmd -c Debug

# Or build a single project when working narrowly
dotnet build .\src\<ProjectName>\<ProjectName>.csproj --nologo --verbosity q

默认使用 artifacts/bin/<ProjectName>/<Configuration>/ 下最高版本的 net* TFM。除非用户明确要求，否则避免使用 netstandard* 和 net4* 目标。

4. 定位已构建的 ApiChief 二进制文件和目标程序集

$dotnet = ".\\.dotnet\\dotnet"
$apiChiefProject = ".\\eng\\Tools\\ApiChief\\ApiChief.csproj"
$apiChief = (& $dotnet msbuild $apiChiefProject --getProperty:TargetPath -p:Configuration=Debug --nologo).Trim()

$name = "<ProjectName>"
$tfm = Get-ChildItem ".\\artifacts\\bin\\$name\\Debug" -Directory |
    Where-Object { $_.Name -match '^net\d+\.\d+$' } |
    Sort-Object { [version]($_.Name -replace '^net', '') } -Descending |
    Select-Object -First 1 -ExpandProperty Name

$assemblyName = (& $dotnet msbuild ".\\src\\$name\\$name.csproj" --getProperty:AssemblyName -p:Configuration=Debug --nologo).Trim()
if ([string]::IsNullOrWhiteSpace($assemblyName))
{
    $assemblyName = $name
}

$assemblyPath = ".\\artifacts\\bin\\$name\\Debug\\$tfm\\$assemblyName.dll"

运行前，如果所选 TFM 对任务有影响，请先报告。

5. 运行所需的 ApiChief 命令

# Emit a baseline
& $dotnet $apiChief $assemblyPath emit baseline -o ".\\src\\$name\\$name.baseline.json"

# Emit a summary
& $dotnet $apiChief $assemblyPath emit summary

# Emit a delta
& $dotnet $apiChief $assemblyPath emit delta ".\\src\\$name\\$name.baseline.json" -o ".\\artifacts\\tmp\\$name.delta.json"

# Check for breaking changes
& $dotnet $apiChief $assemblyPath check breaking ".\\src\\$name\\$name.baseline.json"

# Emit API review artifacts
& $dotnet $apiChief $assemblyPath emit review -o ".\\artifacts\\tmp\\API.$name"

# Emit GitHub-friendly markdown diff files against a baseline
& $dotnet $apiChief $assemblyPath emit delta ".\\src\\$name\\$name.baseline.json" --diff -o ".\\artifacts\\tmp\\API.$name.Diff"

emit delta 也支持将 .json 文件作为当前输入传入，而不是 DLL。

6. 审查或清理基线更改

执行 emit baseline 后：

• 保留已提交文件原有的 BOM 和尾随换行行为
• 还原 "Name" 字段中仅涉及版本的差异
• 检查先前基线中已移除的 // 指令注释，并保留仍需的手动修改
• 如果这些注释引用了 GitHub issue，请在重新应用变通方案之前确认相关 issue 是否仍处于开启状态

7. 清晰地报告结果

• 列出已处理的项目
• 显示所选的 TFM
• 报告输出路径
• 对于 check breaking，说明通过或失败
• 对于 emit delta 和 emit delta --diff，说明退出码 0 表示存在更改，2 表示没有更改，-1 表示出错
• 优先采用 emit delta --diff 的输出，因为它会生成可直接发布的 ```diff 围栏 Markdown，并按类型拆分到各个 .md 文件中