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 では、現在の入力として DLL の代わりに .json ファイルを渡すこともできます。

6. ベースラインの変更を確認する、または整理する

emit baseline の実行後：

• コミット済みファイルの元の BOM と末尾の改行の扱いを維持します
• "Name" フィールドのバージョンのみの差分を元に戻します
• 以前のベースラインから削除された // の指示コメントを確認し、引き続き必要な手動編集を引き継ぎます
• これらのコメントが GitHub の Issue を参照している場合は、回避策を再適用する前に、該当する Issue がまだオープンかどうかを確認します

7. 結果を明確に報告する

• 処理したプロジェクトを列挙します
• 選択した TFM を示します
• 出力パスを報告します
• check breaking の場合は、成功または失敗を明記します
• emit delta および emit delta --diff の場合は、終了コード 0 が変更あり、2 が変更なし、-1 がエラーを意味することを説明します
• 投稿可能な ```diff 形式のフェンス付き Markdown を型ごとの .md ファイルに分割して生成するため、emit delta --diff の出力を優先します