# How the dotnet-msbuild Plugin Optimizes Builds and Diagnoses Failures > Learn how the dotnet msbuild plugin optimizes builds with incremental validation and diagnostics. Easily diagnose failures using binary log interrogation and antipattern detection. - Repository: [.NET Platform/skills](https://github.com/dotnet/skills) - Tags: deep-dive - Published: 2026-07-06 --- **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`](https://github.com/dotnet/skills/blob/main/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: ```bash 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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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 `` 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`](https://github.com/dotnet/skills/blob/main/plugin.json) file at [`plugins/dotnet-msbuild/plugin.json`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-msbuild/plugin.json) declares the plugin version, description, and the `mcpServers.binlog` configuration. Each skill resides as a standalone [`SKILL.md`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```xml ``` 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`](https://github.com/dotnet/skills/blob/main/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.