eval-performance

MSBuild の評価パフォーマンスの診断

評価とは、ターゲットが実行される前に MSBuild が行う作業です。プロジェクトファイルの読み込み、インポートの処理、グロブの展開などが含まれます。このスキルは、評価のボトルネックを特定して確認するのに役立ちます。まず測定し、測定結果から必要だと確認できた場合にのみ変更を提案してください。

変更を加える前に問題を確認する

評価が測定可能な形でボトルネックになっている場合にのみ対応してください。次の場合は対応しないでください。

• 遅いのが評価ではなく、コンパイル中またはターゲットの実行中である場合。 これは評価の問題ではありません。代わりに build-perf-diagnostics を使用してください。
• 「再ビルドが多すぎる」／インクリメンタルビルドに関する不満の場合。 代わりに incremental-build を使用してください。
• 測定結果がない場合。 binlog またはタイミングの概要で評価が遅いと確認できない場合は、まず測定してください（以下を参照）。プロジェクトファイルを読んだだけで推測しないでください。
• 以下のパターンが見られても、評価がすでに高速な場合。 広範囲のグロブ、深いインポート、EnableDefaultItems は、実際に時間がかかっていると測定結果で確認できた場合にのみ、指摘する価値があります。評価がすばやく完了するプロジェクトに変更は必要ありません。

パターンが見られても測定されていない場合は、所見として報告し、判断はユーザーに委ねてください。測定可能な評価時間の増加につながる証拠がないのに、「ベストプラクティス」に合わせて動作中の構成を書き換えないでください。変更はできるだけ小さく、対象を絞ってください。最初の手段として SDK の既定値を無効にしてはいけません。

MSBuild の評価フェーズ

MSBuild の評価モデルと実行モデルの包括的な概要については、ビルドプロセスの概要を参照してください。

1. 初期プロパティ：環境変数、グローバルプロパティ、予約済みプロパティ
2. インポートとプロパティの評価：<Import> を処理し、<PropertyGroup> を上から順に評価
3. 項目定義の評価：<ItemDefinitionGroup> のメタデータの既定値
4. 項目の評価：Include、Remove、Update を含む <ItemGroup>、グロブの展開
5. UsingTask の評価：カスタムタスクを登録

重要な点：評価は、ターゲットが実行される前に行われます。評価が遅いと、コンパイルが必要ない場合でもビルドの開始が遅くなります。

評価パフォーマンスの診断

主な方法：binlog MCP（推奨）

binlog MCP サーバー（Microsoft.AITools.BinlogMcp。binlog MCP 名前空間で公開）を使用して、評価パフォーマンスを分析します。

1. evaluations ツールを使用して、すべての評価と所要時間を一覧表示します
2. evaluation_global_properties を使用して、グローバルプロパティが異なる複数の評価があるか確認します
3. evaluation_properties を使用して、特定のプロジェクトと TFM の評価済みプロパティを調べます
4. imports ツールを使用して、インポートチェーンの深さと構造を分析します
5. properties ツールを使用して、コストの高いプロパティ関数の評価があるか確認します

代替方法：テキストログの再生と前処理（MCP が利用できない場合）

binlog の使用

1. binlog を再生します：dotnet msbuild build.binlog -noconlog -fl "-flp:v=diag;logfile=full.log"
2. 評価イベントを検索します：grep -i 'Evaluation started\|Evaluation finished' full.log
3. 同じプロジェクトに対する複数の評価は、過剰ビルドを示します
4. 「Project evaluation started/finished」メッセージと、そのタイムスタンプを確認します

/pp（前処理）の使用

• dotnet msbuild -pp:full.xml MyProject.csproj
• すべてのインポートをインライン化した、完全に展開済みのプロジェクトを表示します
• インポート内容、インポートの深さ、コンテンツ全体の量を把握するために使用します
• 前処理後の出力が大きい（1 万行超）場合、評価の負荷が高いことを示します

/clp:PerformanceSummary の使用

• タイミングの内訳を確認するため、ビルドコマンドに追加します
• ターゲットやタスクの実行とは別に、評価時間を表示します

コストの高い Glob パターン

項目の評価が遅く、その原因が Glob だと測定で判明した場合にのみ、これらの対策を検討してください。大規模なツリーを走査しないカスタム Glob であれば問題ありません。

• **/*.cs のような Glob はディレクトリツリー全体を走査します
• SDK の既定の Glob は最適化されていますが、カスタム Glob は最適化されていない場合があります
• 問題となる例：node_modules/、.git/、bin/、obj/ に対する Glob — 数百万のファイルが対象になります
• 対策：<DefaultItemExcludes> を使って大規模なディレクトリを除外します
• 対策：Glob のパスを具体的に指定します。**/*.cs ではなく src/**/*.cs を使用します
• 対策：<EnableDefaultItems>false</EnableDefaultItems> の使用は最後の手段にします（SDK の既定値が失われます）。まずは上記の 2 つの方法を優先してください
• 確認方法：診断ログで Compile 項目を検索します → Compile 項目に想定外のファイルが含まれている場合、Glob の範囲が広すぎます

Import チェーンの分析

• 深い Import チェーン（20 レベル超）は評価を遅くします
• 各 Import でファイル I/O、解析、評価が行われます
• よくある原因：.props／.targets を追加する NuGet パッケージ、フレームワーク SDK の Import、Directory.Build チェーン
• 診断方法：/pp の出力で <!-- Importing コメントを検索し、Import ツリーを確認します
• 対策（チェーンに測定可能なコストがある場合のみ）：可能であれば推移的なパッケージの Import を減らし、Import を統合します

複数回の評価

• プロジェクトが複数回評価されると、作業が無駄になります
• よくある原因：異なるグローバルプロパティを持つ複数の別プロジェクトから参照されていること
• グローバルプロパティの組み合わせが異なるたびに、個別の評価が行われます
• 診断方法：grep 'Evaluation started.*ProjectName' full.log → 件数が 1 を超える場合は、グローバルプロパティに違いがないか確認します
• 修正方法：グローバルプロパティを統一し、グラフビルド（/graph）を使用します

TreatAsLocalProperty

• MSBuild タスクを介して、プロパティ値が子プロジェクトに引き継がれるのを防ぎます
• 過剰な使用：TreatAsLocalProperty の項目を多数宣言すると、評価のオーバーヘッドが増加します
• 適切な使用方法：継承されたプロパティを本当に上書きする必要がある場合にのみ使用します

プロパティ関数のコスト

• プロパティ関数は評価中に実行されます
• 多くは低コストです（文字列操作など）
• 高コストな例：評価中の $([System.IO.File]::ReadAllText(...)) — 評価のたびにファイルを読み込みます
• 高コストな例：ネットワーク呼び出し、複雑な計算
• 原則：プロパティ関数は高速で、副作用がないものにします

最適化チェックリスト

• 前処理済みの出力サイズを確認します：dotnet msbuild -pp:full.xml
• 評価回数を確認します：TFM ごとにプロジェクトあたり 1 回であること
• Glob から大規模なディレクトリを除外します
• 評価中のプロパティ関数でのファイル I/O を避けます
• Import の深さを最小限にします
• グラフビルドを使用して重複した評価を減らします
• 不要な UsingTask 宣言がないか確認します