How the dotnet-msbuild Plugin Optimizes Builds and Diagnoses Failures

The dotnet-msbuild plugin reduces build times through incremental build validation and performance diagnostics while providing deep failure diagnosis via binary log interrogation and MSBuild antipattern detection.

The dotnet-msbuild plugin in the dotnet/skills repository provides a self-contained collection of MSBuild-focused skills that analyze build logs and project structures. It combines modular skill files with a dedicated MCP server to deliver both optimization guidance and root-cause analysis for failing builds.

Build Optimization Capabilities

The dotnet-msbuild plugin targets build acceleration through five specialized skills that examine binary logs and project configurations.

Incremental Build Validation

The incremental-build skill located at plugins/dotnet-msbuild/skills/incremental-build/SKILL.md detects why "no-change" rebuilds still recompile targets. It identifies missing Inputs/Outputs declarations, volatile output paths, unregistered FileWrites, and FAST-UP-TO-DATE check failures.

The typical workflow requires generating two binary logs:

dotnet build /bl:first.binlog
dotnet build /bl:second.binlog

The skill examines the second log through the MCP server, comparing "Building target completely" versus "Skipping target" entries to pinpoint exactly which targets failed incremental checks.

Performance Diagnostics and Baseline Establishment

The build-perf-diagnostics skill analyzes binary-log performance summaries to find expensive targets, low node utilization, heavy ResolveAssemblyReferences (RAR) costs, analyzer overhead, and excessive copy operations. According to plugins/dotnet-msbuild/skills/build-perf-diagnostics/SKILL.md, it surfaces the Target Performance Summary and highlights any target consuming greater than 50 percent of total build time.

The build-perf-baseline skill establishes reference build durations by recording a full build with /bl:baseline.binlog, creating a measurable benchmark for subsequent optimization efforts.

Parallelism and Directory Structure Optimization

The build-parallelism skill reveals why parallelism is not being exploited, detecting missing BuildInParallel metadata and deep dependency chains that constrain node assignment. After building with /m, the skill inspects node-assignment logs and suggests graph-shape refactors.

The directory-build-organization skill guides project-layout decisions between single-solution and multi-repository structures to improve graph scheduling. It references helper documentation like common-patterns.md to address TargetFramework props placement and cross-project reference optimization.

Failure Diagnosis Features

When builds fail, the dotnet-msbuild plugin provides structured investigation capabilities through binary log analysis and static project examination.

Binary Log Failure Analysis

The binlog-failure-analysis skill extracts exact errors, warnings, and target-execution chains from .binlog files when console output is noisy. As implemented in plugins/dotnet-msbuild/skills/binlog-failure-analysis/SKILL.md, it calls the MCP tools/list endpoint to enumerate available tools, then queries for errors, properties, items, and the offending target without replaying the build.

MSBuild Antipattern Detection

The msbuild-antipatterns skill audits project directories for classic MSBuild mistakes including unguarded <Import> elements, missing Inputs/Outputs attributes, and volatile property usage. It walks .csproj files and cross-checks against *.nuspec packages to report violations that cause cache misses or unnecessary rebuilds.

Generated File Tracking

The including-generated-files skill advises on correctly registering generated files with FileWrites and FileWritesShareable item groups. This prevents "file not found" errors and stale-file rebuilds by ensuring MSBuild's incremental system tracks all outputs.

Architecture and MCP Server Integration

The dotnet-msbuild plugin leverages a modular architecture centered on a binary-log MCP server that provides programmatic access to build data.

Plugin Manifest and Skill Structure

The plugin.json file at plugins/dotnet-msbuild/plugin.json declares the plugin version, description, and the mcpServers.binlog configuration. Each skill resides as a standalone SKILL.md file under plugins/dotnet-msbuild/skills/*, containing YAML front-matter with name, description, and license fields followed by concrete guidance and command-line snippets.

Agent files like agents/msbuild.agent.md provide the glue layer that wires MCP tooling to the skill-validator runtime, allowing invocation from both CI pipelines and local command-line interfaces.

Binary Log MCP Server

The plugin ships the Microsoft.AITools.BinlogMcp server, started via:

dotnet dnx Microsoft.AITools.BinlogMcp --yes

This server exposes structured commands including tools/list, targets/expensive, and items/query that skills call programmatically. By querying the binary log's in-memory representation rather than parsing text output, the server provides deterministic results with significantly faster response times. If the server cannot start (e.g., on offline machines), skills gracefully fall back to text-log replay.

Practical Implementation Examples

Diagnosing Incremental Build Issues

Generate two binary logs and invoke the incremental-build skill:

dotnet build /bl:first.binlog
dotnet build /bl:second.binlog

dotnet run --project eng/skill-validator/src/SkillValidator.csproj \
    -- evaluate --tests-dir tests/dotnet-msbuild \
    --skill incremental-build \
    --input second.binlog

The output identifies specific targets that rebuilt unnecessarily due to missing incremental metadata.

Analyzing Build Failures

Capture the failure in a binary log and run the failure analysis:

dotnet build /bl:failure.binlog

dotnet run --project eng/skill-validator/src/SkillValidator.csproj \
    -- evaluate --tests-dir tests/dotnet-msbuild \
    --skill binlog-failure-analysis \
    --input failure.binlog

Results include the first error, the chain of dependent targets, and any missing files that caused the cascade.

Identifying Performance Bottlenecks

Enable parallel builds and analyze performance:

dotnet build /bl:perf.binlog -m

dotnet run --project eng/skill-validator/src/SkillValidator.csproj \
    -- evaluate --tests-dir tests/dotnet-msbuild \
    --skill build-perf-diagnostics \
    --input perf.binlog

The skill reports targets exceeding 50 percent of total build time and recommends optimizations like project splitting or dependency restructuring.

Authoring Incremental-Friendly Targets

Implement proper incremental support in custom targets:

<Target Name="GenerateConfig"
        Inputs="$(MSBuildProjectFile);@(ConfigInput)"
        Outputs="$(IntermediateOutputPath)config.generated.cs"
        BeforeTargets="CoreCompile">
  <WriteLinesToFile File="$(IntermediateOutputPath)config.generated.cs"
                    Lines="..." />
  <ItemGroup>
    <FileWrites Include="$(IntermediateOutputPath)config.generated.cs" />
    <Compile Include="$(IntermediateOutputPath)config.generated.cs" />
  </ItemGroup>
</Target>

This pattern ensures the target runs only when inputs change, matching the incremental-build skill's recommended "GoodTarget" structure.

Summary

• The dotnet-msbuild plugin combines modular skill files with a binary-log MCP server to optimize builds and diagnose failures.
• Optimization skills include incremental-build validation, performance diagnostics, parallelism analysis, and directory structure guidance.
• Failure diagnosis leverages binary-log interrogation, antipattern detection, and generated-file tracking without requiring build replay.
• The Microsoft.AITools.BinlogMcp server provides fast, programmatic access to build data through endpoints like tools/list and targets/expensive.
• All skills follow a binary-log-first workflow where users generate /bl:*.binlog files that the plugin analyzes structurally.

Frequently Asked Questions

What is the dotnet-msbuild plugin and how does it differ from standard MSBuild logging?

The dotnet-msbuild plugin is a specialized component within the dotnet/skills repository that provides structured, skill-based analysis of MSBuild binary logs. Unlike standard text logging, which requires manual parsing or replay, the plugin uses the Microsoft.AITools.BinlogMcp server to query binary logs programmatically, delivering specific answers about incremental build failures, performance bottlenecks, and error chains without rebuilding the project.

How does the binary log MCP server improve diagnosis speed?

The MCP server maintains an in-memory representation of the binary log, exposing endpoints like tools/list, errors, and targets/expensive that return structured data immediately. This eliminates the overhead of parsing text logs or replaying builds, allowing skills to query specific properties, items, or target execution times in milliseconds rather than seconds or minutes.

Can the dotnet-msbuild plugin be used in CI/CD pipelines?

Yes. The plugin's agent files, such as agents/msbuild.agent.md, provide integration bindings for the skill-validator runtime, enabling automated execution in CI pipelines. Skills can be invoked via command-line tools like dotnet run --project eng/skill-validator/src/SkillValidator.csproj, making them suitable for automated build verification and regression detection in continuous integration environments.

What are the most common incremental build issues detected by the plugin?

The incremental-build skill most frequently identifies missing Inputs or Outputs attributes on targets, volatile output paths that change between builds, and unregistered FileWrites that cause the FAST-UP-TO-DATE check to fail. These issues force MSBuild to rebuild targets unnecessarily even when source files have not changed, significantly increasing build times in large solutions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}