deniz-dotnet-general.build-parallelism
Analyze MSBuild scheduling across at least two distinct projects in a solution/filter/Build.proj. USE FOR: measured idle workers, -m not scaling, serial ProjectReference critical paths, graph builds, MSBuild Projects-list scheduling. DO NOT USE FOR: duplicate executions or invariant-generation races (find-repeated-work-within-one-build), non-MSBuild systems.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- deniz-dotnet-general.build-parallelism
- description
- Analyze MSBuild scheduling across at least two distinct projects in a solution/filter/Build.proj. USE FOR: measured idle workers, -m not scaling, serial ProjectReference critical paths, graph builds, MSBuild Projects-list scheduling. DO NOT USE FOR: duplicate executions or invariant-generation races (find-repeated-work-within-one-build), non-MSBuild 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):
- Check how many worker nodes actually built the solution. Capture a
binlog with
dotnet build /bl:{}(PowerShell:dotnet build '-bl:{}') and inspect the node timeline to see whether more than one node ran. EverydotnetCLI command built on the SDK's MSBuild-forwarding path (build,msbuild,test,pack,publish, etc.) enables/maxcpucount(multiple nodes) by default;-m:1forces a single node. A directMSBuild.exeinvocation is sequential by default, so pass-mexplicitly to enable parallel worker nodes there. - 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)- Every
dotnetCLI command (build,msbuild,test,pack,publish, etc.) passes/maxcpucountby default via the SDK's shared MSBuild-forwarding path;-m:1overrides it with one node - A direct
MSBuild.exeinvocation is sequential by default and requires an explicit-m - 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 a
<ProjectReference>only after proving it is unnecessary; a slow but valid dependency must stay in the graph - 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
writing-tunit-tests
Write tests in TUnit — the attributes, the async assertion model, data-driven cases, lifecycle hooks, and the parallelism rules. USE FOR writing or fixing a test in a TUnit project, translating a test idea into TUnit syntax, or reviewing TUnit test code for API mistakes. DO NOT USE FOR deciding what to test, judging whether a test is any good, or running tests.
dotnet-walls
Walls for a .NET change in a repository without its own quality gates — pinned, ephemeral analyzer, format, clone and scanner commands for the verify step, their identity ratchet, and the build traps. Use during a walls preflight, or when a worker's verify step needs .NET quality gates.
csharp-15
Write, review and modernize C# 15 (.NET 11) code correctly. Covers every C# 15 feature - collection expression arguments (`[with(...), ...]`), union types (`union`, `[Union]`, `IUnion`, custom unions), closed class hierarchies (`closed`), extension indexers, labeled `break`/`continue`, non-virtual static interface members on runtimes without default interface methods, and the preview memory-safety model (`unsafe(expr)`, `safe`, requires-unsafe members). Use when code targets net11.0 or LangVersion 15/preview, when the user mentions any of these features, when replacing marker interfaces, OneOf-style results, `goto`/flag loop exits or capacity/comparer boilerplate, or when the build reports CS8121, CS8509, CS8655, CS8510, CS0121/CS0411 on a `with(...)` element, CS9370, CS9380 or CS9363.
verified-waves
Run one task as verified multi-agent waves. Plans the fan-out, sends findings to fresh skeptics, keeps a ledger, and reports N of M done; small tasks stay solo.
harness
The bundled dispatch harness, which runs a task file on worker models through OpenCode or Codex, fences their writes, escalates their asks to the operator, settles each result from git and its verify commands, and records every step in a ledger. Its commands, task file, modes and write fence, configuration, runs and their recovery, ledger and exit codes.
delegating-to-worker-models
Use when you hand off implementation, a plan, research a decision will rely on, or a review, and you brief the worker and check what comes back. A subagent that searches, reads in parallel, or keeps your context small is ordinary tool use. Covers what stays with you, the mechanism, assigning work by strength, the walls preflight, prompts without contradictions, the worker contract and model profiles, evidence from your own run, review, and the fix-up loop.