AGENT SKILL

eval-performance

Diagnose measured MSBuild evaluation costs in globs, imports and properties; not compilation, target-execution or incremental-build problems.

License 许可
MIT
所属仓库
microsoft/testfx
最近更新
2026-11-14
Stars
★ 1.1k
Forks
315

01 前言 Front Matter

name
eval-performance
license
MIT
description
Diagnose measured MSBuild evaluation costs in globs, imports and properties; not compilation, target-execution or incremental-build problems.

03 SKILL.md 正文

Diagnosing MSBuild Evaluation Performance

Scope and routing

Guide for diagnosing and improving MSBuild project evaluation performance. USE FOR: builds slow before any compilation starts, high evaluation time in binlog analysis, expensive glob patterns walking large directories (node_modules, .git, bin/obj), deep import chains (>20 levels), preprocessed output >10K lines indicating heavy evaluation, property functions with file I/O ($([System.IO.File]::ReadAllText(...))), multiple evaluations per project. Covers the 5 MSBuild evaluation phases, glob optimization via DefaultItemExcludes, import chain analysis with /pp preprocessing. DO NOT USE FOR: compilation-time slowness (use build-perf-diagnostics), incremental build issues (use incremental-build), non-MSBuild build systems.

Evaluation is the work MSBuild does before any target runs — reading project files, processing imports, expanding globs. This skill helps you find and confirm evaluation bottlenecks. Measure first; recommend a change only when a measurement proves it is warranted.

Confirm the problem before changing anything

Engage only when evaluation is measurably the bottleneck. Do NOT act when:

  • The slowness is during compilation or target execution, not evaluation. That is not an evaluation problem — use build-perf-diagnostics instead.
  • The complaint is "rebuilds too much" / incremental build. Use incremental-build instead.
  • You have no measurement. If no binlog or timing summary shows evaluation is slow, gather one first (see below). Do not guess from reading project files.
  • A pattern below appears but evaluation is already fast. Broad globs, deep imports, or EnableDefaultItems are only worth flagging when the numbers show they cost real time. A project that evaluates quickly needs no change.

When a pattern is present but unmeasured, report it as an observation and let the user decide — do not rewrite working configuration to match a "best practice" without evidence it costs measurable evaluation time. Prefer the smallest, most targeted change; never disable SDK defaults as a first move.

MSBuild Evaluation Phases

For a comprehensive overview of MSBuild's evaluation and execution model, see Build process overview.

  1. Initial properties: environment variables, global properties, reserved properties
  2. Imports and property evaluation: process <Import>, evaluate <PropertyGroup> top-to-bottom
  3. Item definition evaluation: <ItemDefinitionGroup> metadata defaults
  4. Item evaluation: <ItemGroup> with Include, Remove, Update, glob expansion
  5. UsingTask evaluation: register custom tasks

Key insight: evaluation happens BEFORE any targets run. Slow evaluation = slow build start even when nothing needs compiling.

Diagnosing Evaluation Performance

Primary: binlog MCP (preferred)

Use the binlog MCP server (Microsoft.AITools.BinlogMcp, exposed under the binlog MCP namespace) to analyze evaluation performance:

  1. Use the evaluations tool to list all evaluations and their durations
  2. Use evaluation_global_properties to check for multiple evaluations with differing global properties
  3. Use evaluation_properties to inspect evaluated properties for a specific project+TFM
  4. Use imports tool to analyze the import chain depth and structure
  5. Use properties tool to check for expensive property function evaluations

Fallback: text-log replay and preprocessing (when MCP is unavailable)

Using binlog

  1. Replay the binlog: dotnet msbuild build.binlog -noconlog -fl "-flp:v=diag;logfile=full.log"
  2. Search for evaluation events: grep -i 'Evaluation started\|Evaluation finished' full.log
  3. Multiple evaluations for the same project = overbuilding
  4. Look for "Project evaluation started/finished" messages and their timestamps

Using /pp (preprocess)

  • dotnet msbuild -pp:full.xml MyProject.csproj
  • Shows the fully expanded project with ALL imports inlined
  • Use to understand: what's imported, import depth, total content volume
  • Large preprocessed output (>10K lines) = heavy evaluation

Using /clp:PerformanceSummary

  • Add to build command for timing breakdown
  • Shows evaluation time separately from target/task execution

Expensive Glob Patterns

Only pursue these remedies once a measurement shows item evaluation is slow and the globs are the cause; a custom glob that isn't walking large trees is fine.

  • Globs like **/*.cs walk the entire directory tree
  • Default SDK globs are optimized, but custom globs may not be
  • Problem: globbing over node_modules/, .git/, bin/, obj/ — millions of files
  • Remedy: use <DefaultItemExcludes> to exclude large directories
  • Remedy: be specific with glob paths: src/**/*.cs instead of **/*.cs
  • Remedy: use <EnableDefaultItems>false</EnableDefaultItems> only as a last resort (loses SDK defaults) — prefer the two options above first
  • Check: grep for Compile items in the diagnostic log → if Compile items include unexpected files, globs are too broad

Import Chain Analysis

  • Deep import chains (>20 levels) slow evaluation
  • Each import: file I/O + parse + evaluate
  • Common causes: NuGet packages adding .props/.targets, framework SDK imports, Directory.Build chains
  • Diagnosis: /pp output → search for <!-- Importing comments to see import tree
  • Remedy (only if the chain is measurably costly): reduce transitive package imports where possible, consolidate imports

Multiple Evaluations

  • A project evaluated multiple times = wasted work
  • Common causes: referenced from multiple other projects with different global properties
  • Each unique set of global properties = separate evaluation
  • Diagnosis: grep 'Evaluation started.*ProjectName' full.log → if count > 1, check for differing global properties
  • Fix: normalize global properties, use graph build (/graph)

TreatAsLocalProperty

  • Prevents property values from flowing to child projects via MSBuild task
  • Overuse: declaring many TreatAsLocalProperty entries adds evaluation overhead
  • Correct use: only when you genuinely need to override an inherited property

Property Function Cost

  • Property functions execute during evaluation
  • Most are cheap (string operations)
  • Expensive: $([System.IO.File]::ReadAllText(...)) during evaluation — reads file on every evaluation
  • Expensive: network calls, heavy computation
  • Rule: property functions should be fast and side-effect-free

Optimization Checklist

  • [ ] Check preprocessed output size: dotnet msbuild -pp:full.xml
  • [ ] Verify evaluation count: should be 1 per project per TFM
  • [ ] Exclude large directories from globs
  • [ ] Avoid file I/O in property functions during evaluation
  • [ ] Minimize import depth
  • [ ] Use graph build to reduce redundant evaluations
  • [ ] Check for unnecessary UsingTask declarations

04 同仓库更多 Skills

microsoft
microsoft/testfx

dotnet-breaking-changes

Use before changing .NET/C# code whose callers you do not control: a NuGet library, or a repo with PublicAPI.Shipped/Unshipped.txt, ApiCompat, multiple TargetFrameworks, InternalsVisibleTo, or generated (.g.cs) partials. Green builds miss silent breaks from optional parameters, parameter names, sealing, const values, nullability, and #if. USE FOR: "without breaking existing callers"; adding a public method, overload, optional parameter, or interface member to a shipped library; renaming a public method or an internal helper a friend assembly uses; consolidating duplicated logic; changing a signature, nullability, default, or attribute; adding a target framework; RS0016/RS0017 or ApiCompat errors; "is this PR breaking?". For a rename, extract, or merge, also invoke csharp-refactoring. DO NOT USE FOR: an executable whose callers all live in one project; renaming a local variable or private member, even in a shipped library; formatting; framework/SDK/NuGet upgrades (use dotnet-upgrade).

★ 1.1k
microsoft
microsoft/testfx

testfx-test-value-evidence

Apply the vendored test-value-evidence skill with TestFx toolchain, assertion, parallel-safety, packed-consumer, and review conventions. Use when implementing or reviewing behavior-changing TestFx PRs or commits, including source-only changes.

测试与质量
★ 1.1k
microsoft
microsoft/testfx

testfx-parallel-safety-preflight

Check concurrency and isolation before implementing or refactoring TestFx tests, lifecycle code, helpers, shared-state declarations, or production paths those tests exercise. Use before narrowing DoNotParallelize or ResourceLock, changing parallelization settings, or introducing asynchronous workers; repeat against the final diff.

★ 1.1k
microsoft
microsoft/testfx

testfx-localization-validation

Validate generated TestFx localization catalogs, resource IDs, placeholders and locked tokens. Use for RESX/XLF changes, OneLoc PRs, localization build failures, duplicate targets or units, and orphaned translation entries.

★ 1.1k
microsoft
microsoft/testfx

testfx-acceptance-validation

Validate TestFx shipping paths and capable CI execution using packed consumers, package/cache provenance, exact exits and artifacts, and selected-versus-executed test evidence. Use for acceptance regressions, package/MSBuild/launcher/protocol changes, or skipped-only CI results; not for unrelated unit-only or documentation changes.

测试与质量
★ 1.1k
microsoft
microsoft/testfx

session-delivery-hygiene

Gate local-session scope, persistent delivery, live PR state, integration provenance, and owned cleanup. Use before implementing guidance changes, changing or pushing PR work, diagnosing package/output mismatches, or handing off implementation.

★ 1.1k