run-apichief

Run ApiChief

Use the ApiChief tool to inspect or refresh EF Core public API baselines for projects under src/.

ApiChief can run against either a compiled assembly or a previously emitted baseline JSON file. Prefer the repo-local .dotnet SDK and the checked-in build scripts in this repo.

Commands

Default to emit baseline if the user only asks to "run ApiChief".

Workflow

1. Identify the target project(s)

• Match user intent against project folders under src/.
• Ask for clarification only if the target is ambiguous.
• The checked-in baseline path convention in this repo is src/<ProjectName>/<ProjectName>.baseline.json.
• If asked just to update the baselines, run EFCore.ApiBaseline.Tests tests and skip the rest of the steps below.

2. Prepare the environment

Always initialize the repo environment before building or running the tool:

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

On Bash:

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

3. Ensure the target binaries exist

ApiChief operates on built assemblies. If the target project has not been built yet, build it first.

Preferred options:

# 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

Use the highest available net* TFM under artifacts/bin/<ProjectName>/<Configuration>/ by default. Avoid netstandard* and net4* targets unless the user explicitly asks for them.

4. Locate the built ApiChief binary and target assembly

$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+
#x27; } |
    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"

Before running, report the selected TFM if it matters for the task.

5. Run the requested ApiChief command

# 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 also supports passing a .json file as the current input instead of a DLL.

6. Review or clean up baseline changes

After emit baseline:

• preserve the original BOM and trailing newline behavior of the committed file
• revert version-only diffs in the "Name" field
• inspect removed // instruction comments in previous baselines and carry forward any still-needed manual edits
• if those comments reference GitHub issues, check whether the underlying issue is still open before reapplying the workaround

7. Report results clearly

• list the processed project(s)
• show the chosen TFM(s)
• report the output path(s)
• for check breaking, state pass/fail
• for emit delta and emit delta --diff, mention that exit code 0 means changes, 2 means no changes, and -1 means an error
• prefer emit delta --diff output because it generates ready-to-post ```diff fenced markdown split across per-type .md files