binlog-generation

バイナリログの生成

MSBuild ベースのコマンドを実行するときは、必ず /bl スイッチを指定してください。 これは、すべての .NET ビルドで必須です。

/bl が必要なコマンド

次のコマンドには、必ず /bl:{} フラグを追加してください。

• dotnet build
• dotnet test
• dotnet pack
• dotnet publish
• dotnet restore
• msbuild または msbuild.exe
• MSBuild を呼び出すその他すべてのコマンド

推奨：自動で一意の名前を付けるには {} を使用する

注： {} プレースホルダーには、MSBuild 17.8+ / .NET 8 SDK 以降が必要です。

binlog のファイル名に含まれる {} プレースホルダーは、MSBuild によって一意の識別子に置き換えられます。これにより、既存ファイルの確認や追跡をしなくても、ビルド同士が互いに上書きされることはありません。

# Every invocation produces a distinct file automatically
dotnet build /bl:{}
dotnet test /bl:{}
dotnet build --configuration Release /bl:{}

PowerShell では、スイッチ全体を引用符で囲む必要があります。

# Keep the literal {} placeholder in one argument
dotnet build '-bl:{}'
dotnet test '-bl:{}'

重要な理由

1. 一意の名前で上書きを防止 - いつでも以前のビルドに戻って分析できます
2. 失敗の分析 - ビルドが失敗した場合、すぐに分析できるよう binlog がすでに生成されています
3. 比較 - 変更前後のビルドを比較できます
4. ビルドの再実行が不要 - binlog を生成するためだけに、失敗したビルドを再実行する必要はありません

例

# ✅ CORRECT - {} generates a unique name automatically (bash/cmd)
dotnet build /bl:{}
dotnet test /bl:{}

# ✅ CORRECT - quote the complete PowerShell argument
dotnet build '-bl:{}'
dotnet test '-bl:{}'

# ❌ WRONG - Missing /bl flag entirely
dotnet build
dotnet test

# ❌ WRONG - No filename (overwrites the same msbuild.binlog every time)
dotnet build /bl
dotnet build /bl

ビルド 1 回につき binlog 1 つ

MSBuild の呼び出しごとに、個別に /bl:{} を追加してください。名前を使い回したり、/bl のみを指定したりしないでください。

• 複数の構成やプロジェクトをビルドする場合、または失敗したビルドを再試行する場合も、各コマンドに独自の /bl:{} を指定して、ログが互いに上書きされないようにしてください。

dotnet build -c Debug   /bl:{}   # unique file
dotnet build -c Release /bl:{}   # another unique file

binlog の存在を確認する

分析に進む前に、ビルド後に .binlog が実際に生成されたことを確認してください。MSBuild の起動前に失敗したビルド（例：引数の誤り）では、binlog は生成されません。

ls -1 *.binlog       # bash
dir /b *.binlog      # Windows cmd

Get-ChildItem *.binlog   # PowerShell

生成されたパスを控えておくと、binlog-failure-analysis または build-perf-diagnostics で使用できます。

特定のファイル名が必要な場合

binlog のファイル名を事前に決めておく必要がある場合（例：CI アーティファクトのアップロード用）、またはインストールされている MSBuild のバージョンで {} が使用できない場合は、既存ファイルと重複しない名前を選んでください。

1. ディレクトリ内に既存の *.binlog ファイルがないか確認します
2. すでに使われていない名前を選びます（例：既存の最大番号からカウンターを増やします）

# Example: directory contains 3.binlog — use 4.binlog
dotnet build /bl:4.binlog

リポジトリのクリーンアップ

git clean でリポジトリをクリーンアップするときは、ビルド履歴を保持するため、必ず binlog ファイルを除外してください。

# ✅ CORRECT - Exclude binlog files from cleaning
git clean -fdx -e "*.binlog"

# ❌ WRONG - This deletes binlog files (they're usually in .gitignore)
git clean -fdx

ビルドの修正を繰り返し行う際は、特に重要です。ビルド間の変更点を分析するには、binlog が必要です。