MENU

VS CodeのMSBuild Binlog Analyzerでビルド失敗・遅延を調査する方法

Visual Studio

MSBuildのビルドが突然失敗したり、数秒だった処理が数十秒に伸びたりした場合、コンソール出力を上から追うだけでは原因の特定に時間がかかります。そこで役立つのが、VS Code向け拡張機能「MSBuild Binlog Analyzer」です。

MSBuildの詳細な実行記録である.binlogを読み込み、GitHub Copilot Chatで@binlog /errors、@binlog /perf、@binlog /compare、@binlog /incrementalなどを実行すると、エラーの発生元、時間を消費しているターゲット、変更前後の差分、不要な再ビルドの理由を調査できます。利用には、基本的にVS Code 1.99以降、GitHub Copilot Chat、.NET SDKが必要です。(Microsoft for Developers)

この記事では、.binlogの収集からVS Codeへの読み込み、ビルド失敗・遅延・性能劣化・インクリメンタルビルド不良の調査まで、実務で使える手順を解説します。

目次

MSBuild Binlog Analyzerとは

MSBuild Binlog Analyzer for VS Codeは、MSBuildのバイナリログをVS Code内で分析するための拡張機能です。現在はプレビュー版として提供されています。

拡張機能の内部では、.NETのグローバルツールであるMicrosoft.AITools.BinlogMcpが解析を担当します。このMCPサーバーが実際のビルドログを検索・集計し、その結果をGitHub Copilot Chatが自然な文章で説明する仕組みです。初回利用時には、MCPサーバーが自動的にインストールされます。(Microsoft for Developers)

従来のように、膨大な診断ログから文字列を検索するだけではありません。次のような調査をVS Code内で進められます。

調べたいこと主に使うコマンド確認できる内容
ビルドが失敗した理由@binlog /errorsエラー、関連プロジェクト、ターゲット、タスク
ビルドが遅い理由@binlog /perf遅いプロジェクト、ターゲット、タスク、クリティカルパス
変更前後の違い@binlog /compare所要時間、診断、プロパティ、パッケージの差分
変更していないのに再ビルドされる理由@binlog /incremental再実行されたターゲットと、その判定理由
ビルド全体の概要@binlog /summary成否、総時間、エラー数、警告数

Binlog Explorerには、プロジェクト、エラー、警告、遅いターゲット、遅いタスク、再ビルド理由、アナライザーの実行時間などがツリー表示されます。ビルド診断はVS Codeの「問題」パネルにも連携されます。(Microsoft for Developers)

利用前に必要な環境を確認する

必要なソフトウェア

Microsoftの発表時点で案内されている主な要件は次のとおりです。

項目必要な環境
VS Code1.99以降。原則として最新の安定版を推奨
GitHub CopilotGitHub Copilot Chatを利用できる状態
.NET SDKdotnetコマンドを実行できる状態
VS Code拡張機能MSBuild Binlog Analyzer for VS Code

基本的な.binlog分析については、特定の.NET SDKメジャーバージョンは明記されていません。ただし、Binlog AnalyzerのBuildCheck自動実行機能には.NET SDK 9.0.100以降が必要です。(Microsoft for Developers)

.NET SDKが認識されているかは、VS Codeのターミナルで確認できます。

dotnet --info

コマンドが見つからない場合は、先に.NET SDKをインストールしてください。Visual Studioを入れていなくても、.NET SDKがあればdotnet buildとMSBuildを利用できます。(Microsoft Learn)

公式拡張機能を選ぶ

VS Codeの拡張機能画面で、次の名前を検索します。

MSBuild Binlog Analyzer for VS Code

公式拡張機能の識別子は次のとおりです。

ms-dotnettools.msbuild-binlog-analyzer

以前公開されていたdotutils.binlog-analyzerは非推奨となり、Microsoft公式版へ移行しています。似た名前の拡張機能が表示された場合は、拡張機能IDを確認してからインストールしてください。(Visual Studio Marketplace)

.binlogを収集する方法

MSBuild Binlog Analyzerで調査するには、問題が発生したビルドの.binlogが必要です。

VS Codeからビルドと収集を同時に行う

最も簡単なのは、コマンドパレットからビルドを実行する方法です。

  1. VS Codeで対象のソリューションまたはプロジェクトを開く
  2. Ctrl＋Shift＋Pを押す
  3. Binlog: Build & Collect Binlogを選択する
  4. 対象プロジェクトやビルド条件を選択する
  5. ビルド終了後、収集されたログをBinlog Explorerで確認する

「Build & Collect Binlog」は、ビルドとログ収集を一度に実行します。普段のローカルビルドを調べる場合に向いています。(Microsoft for Developers)

dotnet buildで収集する

既存のターミナル操作やCIで問題を再現できる場合は、-blオプションを追加します。

dotnet build MySolution.sln -bl:build.binlog

プロジェクト単位なら、次のように実行できます。

dotnet build MyApp.csproj -bl:build.binlog

ファイル名を指定しない場合は、現在のフォルダーにmsbuild.binlogが作成されます。

dotnet build MySolution.sln -bl

ログを上書きしたくない場合は、ファイル名に{}を入れると、一意な日時やプロセスIDなどを含む名前が生成されます。

dotnet build MySolution.sln -bl:build-{}.binlog

.NET CLIのdotnet buildやdotnet msbuildはMSBuildのロガーオプションを渡せるため、-blまたは/blを使用できます。(Microsoft Learn)

msbuild.exeで収集する

Visual StudioやBuild ToolsのMSBuildを直接使っている環境では、次のように実行します。

msbuild MySolution.sln -bl:build.binlog

Release構成など、普段のビルド条件もそのまま指定してください。

msbuild MySolution.sln -p:Configuration=Release -bl:release.binlog

調査時に重要なのは、問題が発生したときと同じコマンド、同じ構成、同じプロパティでログを採取することです。DebugビルドのログでReleaseビルドの遅延を調べても、正しい比較にはなりません。

.binlogをVS Codeで読み込む

すでに取得済みの.binlogは、次の手順で開けます。

  1. Ctrl＋Shift＋Pでコマンドパレットを開く
  2. Binlog: Load Fileを実行する
  3. 調査する.binlogを選択する
  4. アクティビティバーのBinlog Explorerを開く
  5. Copilot Chatで@binlogを使用する

MSBuild Structured Log Viewerを利用している場合は、同ツールの「Open in VS Code」から渡す方法もあります。(Microsoft for Developers)

読み込み後は、最初に次のコマンドを実行すると状況をつかみやすくなります。

@binlog /summary

より具体的に質問しても構いません。

@binlog このビルドの成否、総所要時間、エラー数、最も時間のかかったプロジェクトを説明して

@binlogは一般的なプログラミング知識だけで回答するのではなく、MCPツールを通じて読み込んだログのデータを参照します。(Microsoft for Developers)

@binlog /errorsでビルド失敗を調査する

ビルドが失敗した場合は、まず/errorsを実行します。

@binlog /errors

これにより、ログに記録されたエラーと、関連するプロジェクトやビルド処理を確認できます。単にエラーコードを一覧表示するだけでなく、エラーに至る前後のイベントを含めてCopilotに質問できる点が特徴です。(Microsoft for Developers)

原因を絞り込む質問例

エラー一覧が表示されたら、次のように質問を具体化します。

@binlog 最初に発生したエラーは何ですか。後続エラーとの因果関係も説明して
@binlog NU1102が発生したプロジェクトとPackageReferenceを特定して
@binlog このMSBエラーを発生させたターゲットとタスクを説明して
@binlog ローカルでは成功し、CIだけ失敗する可能性があるプロパティやパスの違いを探して

大量のエラーが出ている場合は、最初の根本エラーから確認することが重要です。例えば、パッケージ復元の失敗によって参照が解決できず、その後に多数のコンパイルエラーが発生しているケースがあります。後続エラーを一つずつ修正するより、最初の復元エラーを直す方が効率的です。

自動修正を使うときの注意点

拡張機能には、次の修正支援機能があります。

  • エラーを右クリックして「Auto-fix with Copilot」を実行する
  • 「Fix All Issues」で複数の問題を修正する
  • 修正後に再ビルドし、変更前後のbinlogを比較する

Microsoftの説明では、「Fix All Issues」は対象プロジェクトを読み、修正を適用し、再ビルドしたうえで前後のログを読み込む流れになっています。(Microsoft for Developers)

ただし、自動修正は無条件で確定せず、次の順番で確認してください。

  1. Gitの作業ツリーをクリーンな状態にする
  2. 自動修正を実行する
  3. git diffで変更内容を確認する
  4. 通常のビルドとテストを実行する
  5. 修正前後の.binlogを比較する

特に、パッケージバージョン、ターゲットフレームワーク、共通のDirectory.Build.propsを変更した場合は、他プロジェクトへの影響も確認が必要です。

@binlog /perfでビルド遅延を調査する

ビルドが成功していても遅い場合は、次のコマンドを実行します。

@binlog /perf

/perfでは、時間を消費しているプロジェクト、ターゲット、タスクなどを確認できます。Binlog ExplorerやBuild Timelineでは処理時間を視覚的に確認でき、クリティカルパスを基準に「ビルド全体の完了を実際に遅らせている処理」を調べられます。(Microsoft for Developers)

プロジェクト・ターゲット・タスクの違い

単位意味調査時の見方
Project.csprojなどのプロジェクトどのプロジェクトが全体を遅らせているか
Target複数のタスクをまとめたビルド工程Restore、CoreCompileなど、どの工程が重いか
Taskターゲット内で実行される個別処理コンパイル、コピー、参照解決などの詳細
Critical path全体終了時刻を決める依存経路単純な累計時間ではなく、完了を妨げる処理を確認

単に「最も累計時間が長いタスク」を短縮しても、並列で実行されていてクリティカルパス上にない場合、全体時間がほとんど変わらないことがあります。そのため、ランキングだけでなく依存関係とクリティカルパスまで確認するのがポイントです。

遅延原因を深掘りする質問例

@binlog /perf
@binlog 最も遅いターゲットを5件、対象プロジェクトと所要時間付きで示して
@binlog ビルドのクリティカルパスを説明して
@binlog CoreCompileの時間が長い理由を、コンパイラとアナライザーに分けて調べて
@binlog Copyタスクが多すぎないか確認して
@binlog Restoreが毎回実行されている理由を調べて

拡張機能では、遅いターゲットやタスクだけでなく、アナライザーの実行時間なども確認できます。(Microsoft for Developers)

コールドビルドとウォームビルドを混同しない

性能比較でよくある失敗は、次のような条件の異なるログを比べることです。

  • dotnet clean直後のビルドと、2回目のビルド
  • NuGetキャッシュが空の環境と、復元済みの環境
  • Debug構成とRelease構成
  • ローカルPCと性能の異なるCIエージェント
  • ウイルス対策ソフトの除外条件が異なる環境
  • SDKやパッケージバージョンが異なる状態

Microsoftが紹介している比較例でも、CoreCompileの大幅な増加がコードの問題ではなく、初回コンパイルのコストだったケースがあります。(Microsoft for Developers)

性能を測るときは、「クリーンビルド同士」「変更なしの2回目ビルド同士」のように条件をそろえてください。

@binlog /compareで変更前後を比較する

SDK更新、NuGetパッケージ更新、ブランチ変更、ビルド設定変更の後に遅くなった場合は、変更前後の.binlogを比較します。

基本的な流れは次のとおりです。

  1. 問題がなかったビルドの.binlogを読み込む
  2. そのログをベースラインに設定する
  3. 変更後のビルドを実行して、新しい.binlogを読み込む
  4. @binlog /compareを実行する
  5. 所要時間、診断、プロパティ、パッケージの差分を確認する
@binlog /compare

より明確な回答が必要な場合は、比較の目的も書きます。

@binlog 変更前後で500ミリ秒以上遅くなったターゲットを示して
@binlog 2つのビルドで変わったMSBuildプロパティを調べて
@binlog NuGetパッケージのバージョン差分と、ビルド時間への影響を説明して

Build Comparisonでは、2つのログをターゲット単位で並べ、時間差を確認できます。比較対象には、ターゲットの時間、追加・削除された診断、MSBuildプロパティ、NuGetパッケージのバージョンなどが含まれます。(Microsoft for Developers)

ベースラインを設定する方法

Binlog Explorerで正常時の.binlogを右クリックし、次を選択します。

Set This Binlog as Baseline

または、コマンドパレットから次を実行します。

Binlog: Set This Binlog as Baseline

ベースライン設定後に新しいログを読み込むと、自動的に比較されます。ステータスバーの「Build」表示や、Binlog Explorerの「Regressions」から性能劣化を確認できます。(Visual Studio Marketplace)

既定では、ターゲットの所要時間が200ミリ秒以上かつ15％以上増加した場合に、回帰として検出する設定が用意されています。必要に応じて次の設定を変更できます。(Visual Studio Marketplace)

{
  "binlogAnalyzer.regression.minDeltaMs": 200,
  "binlogAnalyzer.regression.minDeltaPct": 15
}

小規模プロジェクトでは200ミリ秒が大きすぎる場合があります。一方、大規模なCIビルドでは小さすぎてノイズが増えることがあります。通常時のばらつきを測定してから、検出基準を調整してください。

@binlog /incrementalで不要な再ビルドを調査する

ソースコードを変更していないのにコンパイルが走る、毎回同じ生成処理が実行される、といった問題には/incrementalを使います。

インクリメンタルビルドの調査では、連続する2回のビルドを同じ条件で記録することが重要です。

dotnet restore MySolution.sln

dotnet build MySolution.sln --no-restore -bl:first.binlog
dotnet build MySolution.sln --no-restore -bl:second.binlog

1回目は必要な成果物を作るビルドです。ファイルを変更せずに実行した2回目が、インクリメンタルビルドとして適切にスキップされているかを調べる対象になります。

2つのログを読み込み、次を実行します。

@binlog /incremental

質問を追加すると、再実行理由を絞り込めます。

@binlog 2回目のビルドで実行されたターゲットと、スキップされなかった理由を示して
@binlog 入力ファイルが出力ファイルより新しいと判定された箇所を探して
@binlog カスタムターゲットのInputsとOutputsに問題がないか確認して

MSBuildでは、入力と出力のタイムスタンプやInputs、Outputsなどを基に、ターゲットを実行するかスキップするか判断します。カスタムターゲットに入出力指定がない、ビルドのたびに変わる値を出力パスへ含めている、生成ファイルが適切に追跡されていない、といった状態では、変更がなくても処理が再実行されることがあります。(GitHub)

インクリメンタルビルド調査で避ける操作

2回のビルドの間に、次の操作を行うと正しく比較できません。

  • dotnet cleanを実行する
  • binやobjを削除する
  • ソースファイルを保存し直す
  • パッケージバージョンを変更する
  • SDKや環境変数を変更する
  • 生成ファイルのタイムスタンプを書き換える

「何も変更していない2回目のビルド」を採取することが、不要な再ビルドを見つける基本です。

CIのビルド失敗や遅延を調査する

MSBuild Binlog Analyzerは、ローカルで採取したログだけでなく、Azure DevOps PipelinesやGitHub ActionsのbinlogをVS Codeへ取り込む機能も備えています。ブランチやプルリクエストで絞り込み、CIの失敗ログを分析できます。(Microsoft for Developers)

CI側では、通常のビルドコマンドに-blを追加し、生成された.binlogを成果物として保存します。

dotnet build MySolution.sln `
  --configuration Release `
  -bl:ci-build.binlog

CIの性能を比較する場合は、次の条件をそろえてください。

比較条件確認する内容
エージェントCPU、メモリ、OS、仮想マシンの種類
SDKglobal.jsonと実際に選択されたSDK
構成Debug、Release、独自プロパティ
キャッシュNuGetやビルドキャッシュの有無
コマンド--no-restore、-mなどのオプション
ブランチ同じコミットまたは差分が明確な状態

ローカルとCIのログを比較すると、パス、SDK、環境依存プロパティ、パッケージソースなどの違いを見つけやすくなります。ただし、マシン性能が違う場合は、単純な総時間ではなく「どのターゲットの割合が増えたか」を見る方が有効です。

MCPサーバーをインストールできない場合の対処法

初回利用時にはMicrosoft.AITools.BinlogMcpが自動インストールされますが、企業ネットワークではNuGetフィードの制限によって失敗することがあります。

まず、VS Codeの「表示」から「出力」を開き、次の出力チャンネルを確認します。

Binlog Analyzer
MCP: Microsoft.AITools.BinlogMcp

利用可能なパッケージソースも確認してください。

dotnet nuget list source

公式Marketplaceでは、制限された環境向けの手動インストール方法として、次のコマンドが案内されています。(Visual Studio Marketplace)

dotnet tool install -g Microsoft.AITools.BinlogMcp `
  --prerelease `
  --add-source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public/nuget/v3/index.json

インストール結果は次のコマンドで確認できます。

dotnet tool list -g |
  Select-String Microsoft.AITools.BinlogMcp
binlog-mcp --help

それでも失敗する場合は、次の点を確認します。

  • 認証が必要な社内NuGetフィードだけが有効になっていないか
  • Package Source Mappingで対象パッケージが除外されていないか
  • プロキシやファイアウォールがAzure DevOpsのフィードを遮断していないか
  • グローバルツールの保存先がPATHに含まれているか
  • VS Codeを再起動またはウィンドウ再読み込みしたか

.binlogを共有するときは機密情報に注意する

.binlogは、通常のコンソールログより詳細な情報を保持します。標準設定では、ビルドで使用したプロジェクトファイルやインポートされた.props、.targetsなどがログへ埋め込まれます。

C#やC++のソースコード自体は標準では収集されませんが、プロジェクトファイル、プロパティ、ビルドに影響した環境変数、ファイルパスなどに機密情報が含まれる可能性があります。(GitHub)

外部へ共有する可能性がある場合は、プロジェクトファイルの埋め込みを無効にして収集できます。

dotnet build MySolution.sln `
  "-bl:build.binlog;ProjectImports=None"

セミコロンがシェルに解釈されないように、オプション全体を引用符で囲むのが安全です。

ただし、ProjectImports=Noneにしても、プロパティや環境由来の値がすべて消えるわけではありません。公開前には次を確認してください。

  • アクセストークン
  • 接続文字列
  • パスワード
  • 社内サーバー名
  • ユーザー名やホームディレクトリ
  • 非公開パッケージソース
  • 署名鍵や証明書のパス

Microsoftの案内でも、ログを公開する前に機密値を削除し、必要に応じてMSBuild Structured Log Viewerのシークレット編集機能を利用するよう推奨されています。(Visual Studio Marketplace)

なお、拡張機能のMarketplace説明では、拡張機能のテレメトリとして.binlogの内容、ファイルパス、ソースコード断片、Copilot Chatの会話本文は送信しないとされています。ただし、組織で定められたGitHub Copilotや生成AIの利用ルールは別途確認してください。(Visual Studio Marketplace)

効率よく原因を特定するための実践フロー

ビルド問題を調査するときは、最初から複雑な質問をするより、次の順番で進めると整理しやすくなります。

ビルドが失敗している場合

  1. 問題が発生したコマンドに-blを追加する
  2. .binlogをVS Codeへ読み込む
  3. @binlog /summaryで全体を確認する
  4. @binlog /errorsで最初の根本エラーを探す
  5. 関連するプロジェクト、ターゲット、タスクを確認する
  6. 最小限の修正を行う
  7. 同じ条件で再ビルドする
  8. 修正前後を@binlog /compareで確認する

ビルドが遅い場合

  1. 遅い状態の.binlogを収集する
  2. @binlog /perfで遅い処理を確認する
  3. クリティカルパス上のターゲットを優先する
  4. 正常時のログをベースラインに設定する
  5. @binlog /compareで増加した処理を確認する
  6. SDK、パッケージ、プロパティ、キャッシュ条件の差を調べる
  7. 修正後も同条件で測定する

変更していないのに再ビルドされる場合

  1. 明示的にdotnet restoreを実行する
  2. --no-restore付きで1回目のログを収集する
  3. ファイルを変更せず2回目のログを収集する
  4. @binlog /incrementalを実行する
  5. スキップされなかったターゲットを確認する
  6. Inputs、Outputs、生成ファイル、タイムスタンプを修正する
  7. 同じ手順で再測定する

MSBuild Binlog Analyzerの強みは、Copilotに「なぜ失敗したのか」「どこが遅くなったのか」と質問できるだけではありません。実際の.binlogを根拠に、プロジェクト、ターゲット、タスク、プロパティの順に原因を掘り下げられることです。

まずは問題が再現するビルドで.binlogを収集し、@binlog /summaryから始めてください。失敗なら/errors、遅延なら/perf、変更前後の調査なら/compare、不要な再ビルドなら/incrementalへ進むと、調査の目的を見失いにくくなります。

Visual Studio
.NET VS Code MSBuild GitHub Copilot Binlog

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次