skills/dotnet__skills
1
0
Fork 0
mirror of https://github.com/dotnet/skills.git synced 2026-09-20 09:49:54 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add binlog MCP usage to other msbuild skills/agents (#683)

Browse Source 
* Add binlog MCP usage to other msbuild skills/agents

* Apply suggestions from code review

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
Jan Krivanek
2026-05-22 15:32:31 +02:00
committed by GitHub
parent 5f1170152b
commit 1a6e78c9c6
6 changed files with 120 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/dotnet-msbuild/agents/build-perf.agent.md
+25 -10
View File
@@ -18,16 +18,29 @@ Before starting any analysis, verify the context is MSBuild-related. If the work
### Step 1: Establish Baseline
- Run the build with binlog: `dotnet build /bl:perf-baseline.binlog -m`
- Replay to diagnostic log: `dotnet msbuild perf-baseline.binlog -noconlog -fl -flp:v=diag;logfile=full.log;performancesummary`
- Record total build duration (from build output) and node count
- Record total build duration from build output
### Step 2: Top-down Analysis
Analyze the replayed diagnostic log:
1. `grep 'Target Performance Summary' -A 50 full.log` → find dominant targets and their cumulative time
2. `grep 'Task Performance Summary' -A 50 full.log` → find dominant tasks
3. `grep 'Project Performance Summary' -A 50 full.log` → find time-heavy projects
4. `grep -i 'Total analyzer execution time\|analyzer.*elapsed' full.log` → check analyzer overhead
5. `grep -i 'node.*assigned\|Building with' full.log | head -30` → assess parallelism
### Step 2: Top-down Analysis — binlog MCP (preferred)
Use the **binlog MCP server** (`AITools.BinlogMcp`, exposed under the `binlog` MCP namespace) which is bundled with this plugin. Call `tools/list` for the MCP first if you are unsure which tools are available.
1. Use overview tool → understand build status and duration
2. Use expensive_projects tool → find the slowest projects
3. Use expensive_targets tool → find dominant targets and their cumulative time
4. Use expensive_tasks tool → find dominant tasks
5. Use expensive_analyzers tool → check analyzer overhead
6. Drill into specific projects with project_target_times tool
**Important:** The `.binlog` file is a binary format — do NOT try to `cat`, `head`, `strings`, or read it directly. Use only the MCP tools to query it.
### Alternate flow — text-log replay (when MCP is unavailable)
1. Replay to diagnostic log: `dotnet msbuild perf-baseline.binlog -noconlog -fl -flp:v=diag;logfile=full.log;performancesummary`
2. `grep 'Target Performance Summary' -A 50 full.log` → find dominant targets and their cumulative time
3. `grep 'Task Performance Summary' -A 50 full.log` → find dominant tasks
4. `grep 'Project Performance Summary' -A 50 full.log` → find time-heavy projects
5. `grep -i 'Total analyzer execution time\|analyzer.*elapsed' full.log` → check analyzer overhead
6. `grep -i 'node.*assigned\|Building with' full.log | head -30` → assess parallelism
### Step 3: Bottleneck Classification
Classify findings into categories:
@@ -39,7 +52,9 @@ Classify findings into categories:
- **Analyzers**: disproportionate analyzer time → specific analyzer is expensive
### Step 4: Deep Dive
For each identified bottleneck:
For each identified bottleneck, use MCP tools (task_details, search, properties, items) to drill into specifics.
When MCP is unavailable, fall back to text-log grep:
- `grep 'Target "TargetName"' full.log` → find specific target execution across projects
- `grep -i 'Csc.*elapsed\|Csc.*duration' full.log` → check compilation times
- `grep 'specific pattern' full.log` → search for specific issues
plugins/dotnet-msbuild/skills/build-parallelism/SKILL.md
+13 -1
View File
@@ -1,6 +1,6 @@
---
name: build-parallelism
description: "Guide for optimizing MSBuild build parallelism and multi-project scheduling. Only activate in MSBuild/.NET build context. USE FOR: builds not utilizing all CPU cores, speeding up multi-project solutions, evaluating graph build mode (/graph), build time not improving with -m flag, understanding project dependency topology. Note: /maxcpucount default is 1 (sequential) — always use -m for parallel builds. Covers /maxcpucount, graph build for better scheduling and isolation, BuildInParallel on MSBuild task, reducing unnecessary ProjectReferences, solution filters (.slnf) for building subsets. DO NOT USE FOR: single-project builds, incremental build issues (use incremental-build), compilation slowness within a project (use build-perf-diagnostics), non-MSBuild build systems. INVOKES: dotnet build -m, dotnet build /graph, binlog analysis."
description: "Guide for optimizing MSBuild build parallelism and multi-project scheduling. Only activate in MSBuild/.NET build context. USE FOR: builds not utilizing all CPU cores, speeding up multi-project solutions, evaluating graph build mode (/graph), build time not improving with -m flag, understanding project dependency topology. Note: /maxcpucount default is 1 (sequential) — always use -m for parallel builds. Covers /maxcpucount, graph build for better scheduling and isolation, BuildInParallel on MSBuild task, reducing unnecessary ProjectReferences, solution filters (.slnf) for building subsets. DO NOT USE FOR: single-project builds, incremental build issues (use incremental-build), compilation slowness within a project (use build-perf-diagnostics), non-MSBuild build systems. INVOKES: binlog MCP server tools (expensive_projects, expensive_targets, project_target_times); falls back to dotnet build -m, dotnet build /graph, binlog replay + grep."
license: MIT
---
@@ -51,6 +51,18 @@ license: MIT
## Analyzing Parallelism with Binlog
### Primary: binlog MCP (preferred)
Use the **binlog MCP server** (`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`
plugins/dotnet-msbuild/skills/check-bin-obj-clash/SKILL.md
+49 -9
View File
@@ -1,6 +1,6 @@
---
name: check-bin-obj-clash
description: "Detects MSBuild projects with conflicting OutputPath or IntermediateOutputPath. Only activate in MSBuild/.NET build context. USE FOR: builds failing with 'Cannot create a file when that file already exists', 'The process cannot access the file because it is being used by another process', intermittent build failures that succeed on retry, missing outputs in multi-project builds, multi-targeting builds where project.assets.json conflicts. Diagnoses when multiple projects or TFMs write to the same bin/obj directories due to shared OutputPath, missing AppendTargetFrameworkToOutputPath, or extra global properties like PublishReadyToRun creating redundant evaluations. DO NOT USE FOR: file access errors unrelated to MSBuild (OS-level locking), single-project single-TFM builds, non-MSBuild build systems. INVOKES: dotnet msbuild binlog replay, grep for output path analysis."
description: "Detects MSBuild projects with conflicting OutputPath or IntermediateOutputPath. Only activate in MSBuild/.NET build context. USE FOR: builds failing with 'Cannot create a file when that file already exists', 'The process cannot access the file because it is being used by another process', intermittent build failures that succeed on retry, missing outputs in multi-project builds, multi-targeting builds where project.assets.json conflicts. Diagnoses when multiple projects or TFMs write to the same bin/obj directories due to shared OutputPath, missing AppendTargetFrameworkToOutputPath, or extra global properties like PublishReadyToRun creating redundant evaluations. DO NOT USE FOR: file access errors unrelated to MSBuild (OS-level locking), single-project single-TFM builds, non-MSBuild build systems. INVOKES: binlog MCP server tools (overview, projects, evaluations, properties, double_writes); falls back to dotnet msbuild binlog replay + grep when the MCP is unavailable."
license: MIT
---
@@ -35,13 +35,53 @@ Clashes can occur between:
Use the `binlog-generation` skill to generate a binary log with the correct naming convention.
## Step 2: Replay the Binary Log to Text
## Primary workflow — binlog MCP
The MCP server exposes structured tools for inspecting a `.binlog` without
parsing text logs. Call them directly instead of replaying the binlog to a text
file. Call `tools/list` for the MCP first if you are unsure which tools are available.
**Important constraints:**
- The `.binlog` file is a **binary format** — do NOT try to `cat`, `head`, `strings`, or read it directly. Use only the MCP tools to query it.
- **Synthesize findings as you go.** Do not spend all available time investigating — once you have enough evidence, present your conclusions.
### Step 2: Get an overview and list projects
Use the MCP overview and projects tools to understand the build and list all projects that participated.
### Step 3: Check evaluations and global properties
Use the MCP `evaluations` and `evaluation_global_properties` tools to find all evaluations per project. Look for:
- Multiple evaluations for the same project (indicates multi-targeting or multiple build configurations)
- Differing global properties between evaluations (`TargetFramework`, `Configuration`, `RuntimeIdentifier`, `SolutionFileName`, `PublishReadyToRun`, etc.)
### Step 4: Get output paths for each evaluation
Use the MCP properties tool to query `OutputPath`, `IntermediateOutputPath`, `BaseOutputPath`, and `BaseIntermediateOutputPath` for each project evaluation.
### Step 5: Check for double writes
Use the MCP double_writes tool if available — it directly detects files written by multiple project instances.
### Step 6: Identify clashes
Compare the `OutputPath` and `IntermediateOutputPath` values across all evaluations:
1. **Normalize paths** - Convert to absolute paths and normalize separators
2. **Group by path** - Find evaluations that share the same OutputPath or IntermediateOutputPath
3. **Filter out non-build evaluations** - Exclude `BuildProjectReferences=false` instances (P2P queries)
4. **Report clashes** - Any group with more than one evaluation indicates a clash
## Fallback workflow — text-log replay (when MCP is unavailable)
Use this only when the MCP server cannot be started.
### Step 2: Replay the Binary Log to Text
```bash
dotnet msbuild build.binlog -noconlog -fl -flp:v=diag;logfile=full.log
```
## Step 3: List All Projects
### Step 3: List All Projects
```bash
grep -i 'done building project\|Building project' full.log | grep -oP '"[^"]+\.csproj"' | sort -u
@@ -49,7 +89,7 @@ grep -i 'done building project\|Building project' full.log | grep -oP '"[^"]+\.c
This lists all project files that participated in the build.
## Step 4: Check for Multiple Evaluations per Project
### Step 4: Check for Multiple Evaluations per Project
Multiple evaluations for the same project indicate multi-targeting or multiple build configurations:
@@ -59,7 +99,7 @@ grep -c 'Evaluation started' full.log
grep 'Evaluation started.*\.csproj' full.log
```
## Step 5: Check Global Properties for Each Evaluation
### Step 5: Check Global Properties for Each Evaluation
For each project, query the build properties to understand the build configuration:
@@ -88,7 +128,7 @@ When analyzing clashes, filter evaluations based on the type of clash you're inv
3. **Always exclude `BuildProjectReferences=false`**: These are P2P metadata queries, not actual builds that write files.
## Step 6: Get Output Paths for Each Project
### Step 6: Get Output Paths for Each Project
Query each project's output path properties:
@@ -103,7 +143,7 @@ dotnet msbuild MyProject.csproj -getProperty:BaseOutputPath
dotnet msbuild MyProject.csproj -getProperty:BaseIntermediateOutputPath
```
## Step 7: Identify Clashes
### Step 7: Identify Clashes
Compare the `OutputPath` and `IntermediateOutputPath` values across all evaluations:
@@ -111,7 +151,7 @@ Compare the `OutputPath` and `IntermediateOutputPath` values across all evaluati
2. **Group by path** - Find evaluations that share the same OutputPath or IntermediateOutputPath
3. **Report clashes** - Any group with more than one evaluation indicates a clash
## Step 8: Verify Clashes via CopyFilesToOutputDirectory (Optional)
### Step 8: Verify Clashes via CopyFilesToOutputDirectory (Optional)
As additional evidence for OutputPath clashes, check if multiple project builds execute the `CopyFilesToOutputDirectory` target to the same path. Note that not all clashes manifest here - compilation outputs and other targets may also conflict.
@@ -129,7 +169,7 @@ Look for evidence of clashes in the messages:
The `SkipUnchangedFiles` skip message often masks clashes - the build succeeds but is vulnerable to race conditions in parallel builds.
## Step 9: Check CoreCompile Execution Patterns (Optional)
### Step 9: Check CoreCompile Execution Patterns (Optional)
To understand which project instance did the actual compilation vs redundant work, check `CoreCompile`:
plugins/dotnet-msbuild/skills/eval-performance/SKILL.md
+13 -1
View File
@@ -1,6 +1,6 @@
---
name: eval-performance
description: "Guide for diagnosing and improving MSBuild project evaluation performance. Only activate in MSBuild/.NET build context. 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. INVOKES: dotnet msbuild -pp:full.xml for preprocessing, /clp:PerformanceSummary."
description: "Guide for diagnosing and improving MSBuild project evaluation performance. Only activate in MSBuild/.NET build context. 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. INVOKES: binlog MCP server tools (evaluations, evaluation_global_properties, evaluation_properties, imports, properties); falls back to dotnet msbuild -pp:full.xml for preprocessing, /clp:PerformanceSummary."
license: MIT
---
@@ -18,6 +18,18 @@ Key insight: evaluation happens BEFORE any targets run. Slow evaluation = slow b
## Diagnosing Evaluation Performance
### Primary: binlog MCP (preferred)
Use the **binlog MCP server** (`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`
plugins/dotnet-msbuild/skills/incremental-build/SKILL.md
+13 -1
View File
@@ -1,6 +1,6 @@
---
name: incremental-build
description: "Guide for optimizing MSBuild incremental builds. Only activate in MSBuild/.NET build context. 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. INVOKES: dotnet build /bl, binlog replay with diagnostic verbosity."
description: "Guide for optimizing MSBuild incremental builds. Only activate in MSBuild/.NET build context. 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. INVOKES: binlog MCP server tools (overview, search, target details); falls back to dotnet build /bl, binlog replay with diagnostic verbosity."
license: MIT
---
@@ -58,6 +58,18 @@ Use binary logs (binlogs) to understand exactly why targets ran instead of being
```
The first build establishes the baseline. The second build is the one you want to be incremental. Analyze `second.binlog`.
### Primary: binlog MCP (preferred)
Use the **binlog MCP server** (`AITools.BinlogMcp`, exposed under the `binlog` MCP namespace) to analyze the second binlog:
1. Use the overview tool to check overall build status and duration
2. Use the search tool to find targets that executed vs were skipped — search for "Building target completely", "Building target incrementally", "Skipping target"
3. Use the search tool to find "is newer than output" messages that reveal which input file triggered a rebuild
4. Use target-related tools (target_reasons, project_targets) to inspect why specific targets ran
5. Use the expensive_targets tool to find targets that consumed the most time in the second build — these are your optimization targets
### Fallback: text-log replay (when MCP is unavailable)
2. **Replay the second binlog** to a diagnostic text log:
```shell
dotnet msbuild second.binlog -noconlog -fl -flp:v=diag;logfile=second-full.log;performancesummary
plugins/dotnet-msbuild/skills/resolve-project-references/SKILL.md
+7 -1
View File
@@ -38,7 +38,13 @@ The reported time includes **waiting for dependent projects to build** while the
### Step 3: Redirect to task self-time
Guide the user to use the **Task** Performance Summary instead:
Use the **Task** Performance Summary to identify the real bottleneck.
#### Primary: binlog MCP (preferred)
Use the **binlog MCP server** expensive_tasks tool to get task self-time rankings directly from the binlog.
#### Fallback: text-log replay (when MCP is unavailable)
```bash
dotnet msbuild build.binlog -noconlog -fl "-flp:v=diag;logfile=full.log;performancesummary"