AGENT SKILL

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):

  1. 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. Every dotnet CLI command built on the SDK's MSBuild-forwarding path (build, msbuild, test, pack, publish, etc.) enables /maxcpucount (multiple nodes) by default; -m:1 forces a single node. A direct MSBuild.exe invocation is sequential by default, so pass -m explicitly to enable parallel worker nodes there.
  2. 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.
  3. Name the chain explicitly, e.g. Core → Api → Web → Tests. A long serial chain stays serial no matter how large -m is, because each project waits on its predecessor.
  4. Look for unnecessary ProjectReference edges that lengthen the chain — a reference that only needs build order (not the output assembly), or one that could be a PackageReference, forces serialization it doesn't need.
  5. Recommend flattening: break false dependencies so independent projects build concurrently, and consider /graph for better scheduling.

MSBuild Parallelism Model

  • /maxcpucount (or -m): number of worker nodes (processes)
  • Every dotnet CLI command (build, msbuild, test, pack, publish, etc.) passes /maxcpucount by default via the SDK's shared MSBuild-forwarding path; -m:1 overrides it with one node
  • A direct MSBuild.exe invocation is sequential by default and requires an explicit -m
  • Recommended: -m without 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 performancesummary and check Project Performance Summary — shows per-project time; grep for node.*assigned to check scheduling
  • Wide graphs (many independent projects) parallelize well; deep graphs (long chains) don't

Graph Build Mode (/graph)

  • dotnet build /graph or msbuild /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 IMultiThreadableTask can 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):

  1. Use expensive_projects tool → find the slowest projects and compare individual vs total build time
  2. Use expensive_targets tool → find bottleneck targets
  3. Use project_target_times tool → drill into a specific project's target-level timing
  4. Ideal: build time should be much less than sum of project times (parallelism)
  5. 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:

  1. Replay the binlog: dotnet msbuild build.binlog -noconlog -fl "-flp:v=diag;logfile=full.log;performancesummary"
  2. Check Project Performance Summary at the end of full.log
  3. Ideal: build time should be much less than sum of project times (parallelism)
  4. If build time ≈ sum of project times: too many serial dependencies, or one slow project blocking others
  5. grep 'Target Performance Summary' -A 30 full.log → find the bottleneck targets
  6. Consider splitting large projects or optimizing the critical path

CI/CD Parallelism Tips

  • Use -m in 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 /graph works well with structured CI pipelines

04 同仓库更多 Skills

Blind-Striker
Blind-Striker/agent-skills-and-plugins

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.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

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.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

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.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

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.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

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.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

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.

★ 1