MSBuild Evaluation Phases
For a comprehensive overview of MSBuild's evaluation and execution model, see Build process overview.
- Initial properties: environment variables, global properties, reserved properties
- Imports and property evaluation: process
<Import>, evaluate <PropertyGroup> top-to-bottom
- Item definition evaluation:
<ItemDefinitionGroup> metadata defaults
- Item evaluation:
<ItemGroup> with Include, Remove, Update, glob expansion
- 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:
- Use the evaluations tool to list all evaluations and their durations
- Use evaluation_global_properties to check for multiple evaluations with differing global properties
- Use evaluation_properties to inspect evaluated properties for a specific project+TFM
- Use imports tool to analyze the import chain depth and structure
- Use properties tool to check for expensive property function evaluations
Fallback: text-log replay and preprocessing (when MCP is unavailable)
Using binlog
- Replay the binlog:
dotnet msbuild build.binlog -noconlog -fl -flp:v=diag;logfile=full.log
- Search for evaluation events:
grep -i 'Evaluation started\|Evaluation finished' full.log
- Multiple evaluations for the same project = overbuilding
- 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
- 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
- Fix: use
<DefaultItemExcludes> to exclude large directories
- Fix: be specific with glob paths:
src/**/*.cs instead of **/*.cs
- Fix: use
<EnableDefaultItems>false</EnableDefaultItems> only as last resort (lose SDK defaults)
- 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
- Fix: 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
1---2name: eval-performance3description: "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."4license: MIT5metadata:6 source: https://skillmd.com/skills/dotnet/eval-performance7---89## MSBuild Evaluation Phases1011For a comprehensive overview of MSBuild's evaluation and execution model, see [Build process overview](https://learn.microsoft.com/en-us/visualstudio/msbuild/build-process-overview).12131. **Initial properties**: environment variables, global properties, reserved properties142. **Imports and property evaluation**: process `<Import>`, evaluate `<PropertyGroup>` top-to-bottom153. **Item definition evaluation**: `<ItemDefinitionGroup>` metadata defaults164. **Item evaluation**: `<ItemGroup>` with `Include`, `Remove`, `Update`, glob expansion175. **UsingTask evaluation**: register custom tasks1819Key insight: evaluation happens BEFORE any targets run. Slow evaluation = slow build start even when nothing needs compiling.2021## Diagnosing Evaluation Performance2223### Primary: binlog MCP (preferred)2425Use the **binlog MCP server** (`Microsoft.AITools.BinlogMcp`, exposed under the `binlog` MCP namespace) to analyze evaluation performance:26271. Use the evaluations tool to list all evaluations and their durations282. Use evaluation_global_properties to check for multiple evaluations with differing global properties293. Use evaluation_properties to inspect evaluated properties for a specific project+TFM304. Use imports tool to analyze the import chain depth and structure315. Use properties tool to check for expensive property function evaluations3233### Fallback: text-log replay and preprocessing (when MCP is unavailable)3435### Using binlog36371. Replay the binlog: `dotnet msbuild build.binlog -noconlog -fl -flp:v=diag;logfile=full.log`382. Search for evaluation events: `grep -i 'Evaluation started\|Evaluation finished' full.log`393. Multiple evaluations for the same project = overbuilding404. Look for "Project evaluation started/finished" messages and their timestamps4142### Using /pp (preprocess)4344- `dotnet msbuild -pp:full.xml MyProject.csproj`45- Shows the fully expanded project with ALL imports inlined46- Use to understand: what's imported, import depth, total content volume47- Large preprocessed output (>10K lines) = heavy evaluation4849### Using /clp:PerformanceSummary5051- Add to build command for timing breakdown52- Shows evaluation time separately from target/task execution5354## Expensive Glob Patterns5556- Globs like `**/*.cs` walk the entire directory tree57- Default SDK globs are optimized, but custom globs may not be58- Problem: globbing over `node_modules/`, `.git/`, `bin/`, `obj/` — millions of files59- Fix: use `<DefaultItemExcludes>` to exclude large directories60- Fix: be specific with glob paths: `src/**/*.cs` instead of `**/*.cs`61- Fix: use `<EnableDefaultItems>false</EnableDefaultItems>` only as last resort (lose SDK defaults)62- Check: grep for Compile items in the diagnostic log → if Compile items include unexpected files, globs are too broad6364## Import Chain Analysis6566- Deep import chains (>20 levels) slow evaluation67- Each import: file I/O + parse + evaluate68- Common causes: NuGet packages adding .props/.targets, framework SDK imports, Directory.Build chains69- Diagnosis: `/pp` output → search for `<!-- Importing` comments to see import tree70- Fix: reduce transitive package imports where possible, consolidate imports7172## Multiple Evaluations7374- A project evaluated multiple times = wasted work75- Common causes: referenced from multiple other projects with different global properties76- Each unique set of global properties = separate evaluation77- Diagnosis: `grep 'Evaluation started.*ProjectName' full.log` → if count > 1, check for differing global properties78- Fix: normalize global properties, use graph build (`/graph`)7980## TreatAsLocalProperty8182- Prevents property values from flowing to child projects via MSBuild task83- Overuse: declaring many TreatAsLocalProperty entries adds evaluation overhead84- Correct use: only when you genuinely need to override an inherited property8586## Property Function Cost8788- Property functions execute during evaluation89- Most are cheap (string operations)90- Expensive: `$([System.IO.File]::ReadAllText(...))` during evaluation — reads file on every evaluation91- Expensive: network calls, heavy computation92- Rule: property functions should be fast and side-effect-free9394## Optimization Checklist9596- [ ] Check preprocessed output size: `dotnet msbuild -pp:full.xml`97- [ ] Verify evaluation count: should be 1 per project per TFM98- [ ] Exclude large directories from globs99- [ ] Avoid file I/O in property functions during evaluation100- [ ] Minimize import depth101- [ ] Use graph build to reduce redundant evaluations102- [ ] Check for unnecessary UsingTask declarations