build-parallelism
Diagnose and fix under-parallelized MSBuild builds. USE WHEN a multi-project solution build is slower than expected, doesn't speed up when you add cores, pegs a single core while others idle, or you want to know why `-m` isn't helping. Note: `/maxcpucount` default is 1 (sequential) — always pass `-m` for parallel builds. Covers finding the critical path (longest serial ProjectReference chain), graph build (`/graph`), BuildInParallel, and solution filters (`.slnf`). DO NOT USE FOR: single-project builds, incremental issues (use incremental-build), compilation slowness inside one project (use build-perf-diagnostics), non-MSBuild build systems.
- License 许可
- MIT
- 最近更新
- 2026-09-18
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- build-parallelism
- license
- MIT
- description
- Diagnose and fix under-parallelized MSBuild builds. USE WHEN a multi-project solution build is slower than expected, doesn't speed up when you add cores, pegs a single core while others idle, or you want to know why `-m` isn't helping. Note: `/maxcpucount` default is 1 (sequential) — always pass `-m` for parallel builds. Covers finding the critical path (longest serial ProjectReference chain), graph build (`/graph`), BuildInParallel, and solution filters (`.slnf`). DO NOT USE FOR: single-project builds, incremental issues (use incremental-build), compilation slowness inside one project (use build-perf-diagnostics), non-MSBuild build systems.
03 SKILL.md 正文
Diagnose a slow parallel build (start here)
Work this checklist in order — it targets the usual root cause (a serial dependency chain that no number of cores can parallelize):
- Confirm parallelism is even on. Rebuild with
dotnet build -m /bl:{}(PowerShell:dotnet build -m -bl:{{}}).-mwith no number uses all logical processors; without-mMSBuild runs a single node (sequential). - Find the critical path. From the binlog, read per-project timings and the node timeline. If total build time ≈ the sum of the projects on one dependency chain, that chain — not CPU count — is the bottleneck.
- Name the chain explicitly, e.g.
Core → Api → Web → Tests. A long serial chain stays serial no matter how large-mis, because each project waits on its predecessor. - Look for unnecessary
ProjectReferenceedges that lengthen the chain — a reference that only needs build order (not the output assembly), or one that could be aPackageReference, forces serialization it doesn't need. - Recommend flattening: break false dependencies so independent projects
build concurrently, and consider
/graphfor better scheduling.
MSBuild Parallelism Model
/maxcpucount(or-m): number of worker nodes (processes)- Default: 1 node (sequential!). Always use
-mfor parallel builds - Recommended:
-mwithout a number = use all logical processors - Each node builds one project at a time
- Projects are scheduled based on dependency graph
Project Dependency Graph
- MSBuild builds projects in dependency order (topological sort)
- Critical path: longest chain of dependent projects determines minimum build time
- Bottleneck: if project A depends on B, C, D and B takes 60s while C and D take 5s, B is the bottleneck
- Diagnosis: replay binlog to diagnostic log with
performancesummaryand check Project Performance Summary — shows per-project time; grep fornode.*assignedto check scheduling - Wide graphs (many independent projects) parallelize well; deep graphs (long chains) don't
Graph Build Mode (/graph)
dotnet build /graphormsbuild /graph- What it changes: MSBuild constructs the full project dependency graph BEFORE building
- Benefits: better scheduling, avoids redundant evaluations, enables isolated builds
- Limitations: all projects must use
<ProjectReference>(no programmatic MSBuild task references) - When to use: large solutions with many projects, CI builds
- When NOT to use: projects that dynamically discover references at build time
Optimizing Project References
- Reduce unnecessary
<ProjectReference>— each adds to the dependency chain - Use
<ProjectReference ... SkipGetTargetFrameworkProperties="true">to avoid extra evaluations <ProjectReference ... ReferenceOutputAssembly="false">for build-order-only dependencies- Consider if a ProjectReference should be a PackageReference instead (pre-built NuGet)
- Use
solution filters(.slnf) to build subsets of the solution
BuildInParallel
<MSBuild Projects="@(ProjectsToBuild)" BuildInParallel="true" />in custom targets- Without
BuildInParallel="true", MSBuild task batches projects sequentially - Ensure
/maxcpucount> 1 for this to have effect
Multi-threaded MSBuild Tasks
- Individual tasks can run multi-threaded within a single project build
- Tasks implementing
IMultiThreadableTaskcan run on multiple threads - Tasks must declare thread-safety via
[MSBuildMultiThreadableTask]
Analyzing Parallelism with Binlog
Primary: binlog MCP (preferred)
Use the binlog MCP server (Microsoft.AITools.BinlogMcp, exposed under the binlog MCP namespace):
- Use expensive_projects tool → find the slowest projects and compare individual vs total build time
- Use expensive_targets tool → find bottleneck targets
- Use project_target_times tool → drill into a specific project's target-level timing
- Ideal: build time should be much less than sum of project times (parallelism)
- If build time ≈ sum of project times: too many serial dependencies, or one slow project blocking others
Fallback: text-log replay (when MCP is unavailable)
Step-by-step:
- Replay the binlog:
dotnet msbuild build.binlog -noconlog -fl -flp:v=diag;logfile=full.log;performancesummary - Check Project Performance Summary at the end of
full.log - Ideal: build time should be much less than sum of project times (parallelism)
- If build time ≈ sum of project times: too many serial dependencies, or one slow project blocking others
grep 'Target Performance Summary' -A 30 full.log→ find the bottleneck targets- Consider splitting large projects or optimizing the critical path
CI/CD Parallelism Tips
- Use
-min CI (many CI runners have multiple cores) - Consider splitting solution into build stages for extreme parallelism
- Use build caching (NuGet lock files, deterministic builds) to avoid rebuilding unchanged projects
dotnet build /graphworks well with structured CI pipelines
04 同仓库更多 Skills
vectorization
Design, implement, optimize, and review SIMD code in .NET. USE FOR: vectorizing scalar loops with TensorPrimitives, Vector64/128/256/512, or platform hardware intrinsics; reviewing existing SIMD code, including Vector<T>, for contract equivalence, tail handling, memory safety, portability, fallbacks, and measured performance. DO NOT USE FOR: performance work unrelated to SIMD or vectorization.
resolve-project-references
Guide for interpreting ResolveProjectReferences time in MSBuild performance summaries. Activate when ResolveProjectReferences appears as the most expensive target and developers are trying to optimize it directly. Explains that the reported time includes wait time for dependent project builds and is misleading. Guides users to focus on task self-time instead. Do not activate for general build performance -- use build-perf-diagnostics instead.
optimizing-ef-core-queries
Optimize and improve the performance of slow Entity Framework Core (EF Core) queries: make them generate less SQL, make fewer database round-trips, and return results faster. Use whenever an EF Core or DbContext query or data-access path is slow or should be made faster — whether or not EF Core owns the database schema. For EF Core, not Dapper or raw ADO.NET.
microbenchmarking
Activate this skill when BenchmarkDotNet (BDN) is involved in the task — creating, running, configuring, or reviewing BDN benchmarks. Also activate when microbenchmarking .NET code would be useful and BenchmarkDotNet is the likely tool. Consider activating when answering a .NET performance question requires measurement and BenchmarkDotNet may be needed. Covers microbenchmark design, BDN configuration and project setup, how to run BDN microbenchmarks efficiently and effectively, and using BDN for side-by-side performance comparisons. Do NOT use for profiling/tracing .NET code (dotnet-trace, PerfView), production telemetry, or load/stress testing (Crank, k6).
incremental-build
Guide for optimizing MSBuild incremental builds. USE FOR: builds slower than expected on subsequent runs, 'nothing changed but it rebuilds anyway', diagnosing why targets re-execute unnecessarily, fixing broken no-op builds. Covers 8 common causes: missing Inputs/Outputs on custom targets, volatile properties in output paths (timestamps/GUIDs), file writes outside tracked Outputs, missing FileWrites registration, glob changes, Visual Studio Fast Up-to-Date Check (FUTDC) issues. Key diagnostic: look for 'Building target completely' vs 'Skipping target' in binlog. DO NOT USE FOR: first-time build slowness (use build-perf-baseline), parallelism issues (use build-parallelism), evaluation-phase slowness (use eval-performance), non-MSBuild build systems.
eval-performance
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.