msbuild

MSBuild のトラブルシューティング

これはエントリースキルです。トラブルシューティング、パフォーマンス、作成内容のレビューのいずれかを選び、関連するローカルのリファレンスだけを読みます。リファレンスには、正確性に関する修正を加えた元の MSBuild スキルの内容と識別情報が保持されています。別途有効化するスキルではありません。

タスクと証拠から始める

チェックアウトが必要なタスクでは、現在のワークスペースから、関連するプロジェクト／ソリューション、共有ビルドファイル、SDK の選択方法、リポジトリのビルド手順を確認します。元のコマンド、作業ディレクトリ、構成、ターゲットフレームワーク、ランタイム識別子、グローバルプロパティ、ターゲットを維持します。確認できない情報のうち、重大な影響があるものだけを質問します。

既存の .binlog だけが利用可能なアーティファクトの場合もあります。新たなビルドを依頼する前に分析してください。ログ内のパスが、ローカルにチェックアウトが存在する証拠になるわけではありません。自己完結型の静的レビューやアドバイザリーの質問では、提供された XML と関連するリファレンスを使用し、チェックアウト、復元、ビルド、binlog を必須としないでください。

複合的な依頼では、ビルドの成功を測定する前に正確性の問題を修正し、作成内容のレビューとパフォーマンス実験は分けて行います。ビルド成功後のテストアサーションの失敗は、MSBuild の失敗ではありません。

1. ビルドの問題をトラブルシューティングする

目標： 広範囲な整理ではなく、独立した根本原因を特定し、最小限の修正を行います。

状況	読むもの	対応
ビルドが失敗し、バイナリログがある	binlog-failure-analysis	MSBuild でログを再生し、エラーを該当するプロジェクトインスタンス、ターゲット、タスクに関連付けます。根本原因と連鎖的な失敗を切り分けます。
失敗の証拠が必要で、一致するログがない	binlog-generation、続いて failure analysis	元の呼び出しを一度だけ記録し、アーティファクトを検証してから分析します。
プロジェクト／ビルドファイルの条件、項目、プロパティ、出力パスが正しくない	msbuild-antipatterns	該当するカタログの項目を選び、変更する前に例外を確認します。
インポートやビルドフックが欠落、上書き、または誤った順序で実行されている	extension-points	必須の失敗を隠すのではなく、インポートの契約、検出順序、パッケージ化された NuGet のレイアウトを調査します。
出力が古い、または必要な処理がスキップされる	incremental-build	判断を誤らせている入力、出力、タイムスタンプ、項目、条件を明らかにします。速度より正確性を優先します。

修正後は、元の失敗シナリオを再実行し、影響を受ける依存先を確認します。ログしか利用できない場合は、証拠に基づく修正案を提示し、適用も再ビルドもしていないことを明記します。対象を絞った失敗調査を、ソリューション全体の作成内容の整理に広げないでください。

2. ビルドパフォーマンスを診断して改善する

目標： 報告されたシナリオを測定し、ボトルネックを特定して、原因を1つ変更し、必要な動作を損なわずに同等のビルドを比較します。

1. 条件が一致する測定値を再利用します。測定値がない場合は、設定を編集する前に関連するベースラインを確立します。失敗したビルドを成功したベースラインとして計測してはいけません。
2. 評価とターゲット／タスクの実行を分類します。依存関係の待機時間を含むターゲット合計は、壁時計時間に加算できるものではなく、CPU 使用率の証明にもなりません。
3. 測定結果に応じて、以下の該当する項目を確認します。すべてのリファレンスに記載された最適化を一律に適用してはいけません。
4. 同じシナリオ、コマンド、入力変更、計測方法を使って繰り返します。ばらつき／ノイズと正当性のチェック結果を報告します。単発で速くなっただけでは、改善の証拠になりません。

状況	確認先	区別して扱うこと
信頼できる変更前／変更後の測定値がない、またはベースライン／制御された最適化が求められている	build-perf-baseline	クリーンな出力でのビルド、入力変更後のウォームビルド、変更なしのビルド。復元／キャッシュの状態。通常の Build と強制的な Rebuild。
コストの大きい処理がまだ特定されていない、またはコンパイラー／アナライザー／参照／復元の時間が支配的	build-perf-diagnostics	実際のタスクコストとオーケストレーションの待機時間、重複する所要時間、計測の不足。
ターゲット実行前、グロブ、インポート、プロパティ評価に時間がかかっている	eval-performance	評価と実行。正当なプロジェクトインスタンスと偶発的なプロジェクトインスタンス。
コンテンツのコピーや出力 I/O が支配的	copy-to-output-directory	コピー モード／バージョンのサポート、変更のないコピー、変更されたコピー先の意図した処理。
2回目の変更なしのビルドで再コンパイル／再生成される、またはインクリメンタル動作に問題がある	incremental-build	想定される無効化と追跡漏れ。変更／追加／削除された入力と、欠落した出力。

疑われるボトルネックが証拠で裏付けられない場合、結果がノイズの範囲内の場合、または正当性が損なわれた場合は、そこで終了します。完全なベースラインを捏造せず、測定値が不足していることを報告します。

3. ビルドファイルの記述を見直す

目標： 動作を維持しながら、プロジェクト／ビルドファイルの構成と拡張ポイントの契約を改善します。この手順は MSBuild の記述を整理するものであり、フレームワーク、パッケージ、言語、レガシーなプロジェクトシステムを暗黙に移行するものではありません。

依頼された変更	確認先	維持すること
プロジェクトファイル、共有プロパティ、項目宣言、カスタムターゲットを見直す／整理する	msbuild-antipatterns	意図的なオーバーライド、F# のソース順序、必須のインポート、パッケージアセット、実際の入力／出力の契約。
フック、インポート、共有ファイルの検出、NuGet ビルド拡張を見直す／改善する	extension-points	既存のフック、評価順序、直接／推移的な利用者の動作、パッケージ化されたレイアウト。
整理の一環として生成またはコピーを再構成する	該当する場合、incremental-build と copy-to-output-directory	初回ビルドと変更なしのビルドの動作、無効化、生成項目の登録、出力の完全性。

編集前に、既存の契約を記録します。関連するカタログ項目のみを確認します。テキストパターンが一致しても、不具合の証明にはなりません。すでに正しいパターンは変更しません。元の構成、関連する利用者、影響を受けるインクリメンタルビルド／パッケージ化／発行の動作を検証します。

共有される証拠と安全性

• キャプチャのみを求められた場合は、binlog-generation を使用し、新しい成果物と元の終了コードを報告して終了します。分析には MSBuild replay を使用し、バイナリファイルのテキスト解析は決して行わないでください。リプレイの成功と所要時間は、記録されたビルドの結果や所要時間ではありません。
• これらのファイルは、このスキルを基準にした相対パスで解決します。元のプラグインのスキルを読み込んだり、他のインストール先やチェックアウト先を検索したりしないでください。バンドルされた参照ファイルが見つからない場合は、references の一覧表示を一度だけ行い、不足を報告して、そのガイダンスに従ったかのように装わないでください。
• 出力やキャッシュのクリーンアップ、共有ビルドサーバーの停止、診断の無効化、SDK の変更、または汎用的な修正としてのビルドの直列化は行わないでください。破壊的な実験が必要な場合は、承認済みの所有出力に限定してください。共有が許可されていない限り、バイナリログとリプレイしたログはローカルに保管してください。
• 記録された事実と仮説を区別してください。ソース、ログの詳細、ツール、またはプラットフォームのサポートが不足している場合は、推測した値や捏造した検証で補わず、明示的に報告してください。

完了

選択したタスク、原因／ボトルネックまたは作成方針、裏付けとなる証拠、実施または提案した最小限の変更を示してください。変更が不要な場合は、その旨を伝えてください。成功、失敗、未実施のチェックを区別して、正確な検証内容と結果を示してください。パフォーマンス改善の場合は、比較可能な測定値と不確実性も必要です。回答の詳しさはタスクに見合ったものにしてください。