Analyzing MSBuild Failures with Binary Logs

CRITICAL: Mandatory Invocation Rules

This skill is a BLOCKING REQUIREMENT when any .NET build fails. You MUST invoke this skill when:

• •dotnet build, dotnet test, msbuild, or any MSBuild-based command exits with non-zero code
• •Console output contains "Build failed", "error CS", "error MSB", or similar build errors
• •Any .NET compilation or restore operation fails

What you MUST NOT do:

• •Do NOT report build errors directly from console output to the user
• •Do NOT attempt to fix errors based on console output alone
• •Do NOT skip this skill because "the errors look simple"

Correct behavior: Invoke this skill → analyze with binlog-mcp tools → then report findings and suggest fixes.

Fallback: Only if the binlog-mcp tools fail to provide useful information (e.g., binlog not generated, tools return errors, or analysis is inconclusive), you may fall back to analyzing console output directly. Always attempt binlog analysis first.

When an MSBuild build fails, use the binlog-mcp tool to deeply analyze the failure. This skill guides you through generating a binary log and using the MCP tools to diagnose issues.

Step 1: Generate a Binary Log

Re-run the failed build command with the /bl flag to generate a binary log file:

# For dotnet builds
dotnet build /bl

# For msbuild directly
msbuild /bl

# Custom binlog filename
dotnet build /bl:build.binlog

The /bl flag tells MSBuild to generate a msbuild.binlog file (or the specified filename) in the current directory.

Step 2: Load the Binary Log

Use the load_binlog tool to load the generated binlog file:

load_binlog with path: "<absolute-path-to-binlog>"

This must be called before using any other binlog analysis tools. Returns InterestingBuildData containing total duration in milliseconds and node count.

Step 3: Analyze the Failure

Get Diagnostics (Errors and Warnings)

Use get_diagnostics to extract all errors and warnings:

get_diagnostics with:
  - binlog_file: "<path>"
  - includeErrors: true
  - includeWarnings: true
  - includeDetails: true
  - projectIds: [optional array of project IDs to filter]
  - targetIds: [optional array of target IDs to filter]
  - taskIds: [optional array of task IDs to filter]
  - maxResults: [optional max number of diagnostics]

Returns DiagnosticAnalysisResult with severity classification (Error, Warning, Info), source locations, file paths, line numbers, and context information.

Search for Specific Issues

Use search_binlog with the powerful query language to find specific issues:

search_binlog with:
  - binlog_file: "<path>"
  - query: "error CS1234"        # Find specific error codes
  - query: "$task Csc"           # Find all C# compilation tasks
  - query: "under($project MyProject)"  # Find nodes under a specific project
  - maxResults: 300              # Default limit
  - includeDuration: true        # Include timing info
  - includeContext: true         # Include project/target/task IDs

Investigate Expensive Operations

If the build is slow or timing out:

get_expensive_targets with binlog_file and top_number: 10
get_expensive_tasks with binlog_file and top_number: 10
get_expensive_projects with binlog_file, top_number: 10, sortByExclusive: true

The get_expensive_projects tool supports:

• •excludeTargets: Array of target names to exclude (e.g., ['Copy', 'CopyFilesToOutputDirectory'])
• •sortByExclusive: Sort by exclusive time (true) or inclusive time (false)

Analyze Roslyn Analyzers

If compilation is slow, check analyzer performance:

get_expensive_analyzers with binlog_file and top_number: 10

Returns aggregated analyzer data with execution count, total/average/min/max durations.

For specific Csc task analyzer details:

get_task_analyzers with binlog_file, projectId, targetId, taskId

Available Tools Reference

Binlog Loading

Diagnostic Analysis

Search Analysis

Project Analysis

Target Analysis

Task Analysis

Analyzer Analysis

Evaluation Analysis

File Analysis

Timeline Analysis

Common Analysis Workflows

Build Error Investigation

1. •load_binlog - Load the binlog
2. •get_diagnostics with includeErrors: true - Get all errors
3. •search_binlog with the error code - Find context around the error
4. •list_projects - Identify which projects are involved
5. •get_file_from_binlog - View source files embedded in the binlog

Performance Investigation

1. •load_binlog - Load the binlog
2. •get_expensive_targets - Find slow targets
3. •get_expensive_tasks - Find slow tasks
4. •get_expensive_analyzers - Check if analyzers are slow
5. •search_targets_by_name - Find all executions of a specific target
6. •get_node_timeline - Analyze parallelism and node utilization

Dependency/Evaluation Issues

1. •load_binlog - Load the binlog
2. •list_projects - See all projects in the build
3. •list_evaluations - Check for multiple evaluations (indicates overbuilding)
4. •get_evaluation_global_properties - Compare properties between evaluations
5. •get_evaluation_items_by_name - Inspect PackageReference, Compile items

Query Language Reference

The search_binlog tool supports powerful query syntax from MSBuild Structured Log Viewer:

Basic Search

Node Type Filtering

Property Matching

Hierarchical Search

Time-based Filtering

Special Properties

Result Enhancement

Tips

• •The binlog contains embedded source files - use list_files_from_binlog and get_file_from_binlog to view them
• •Use maxResults parameter to limit large result sets
• •Use get_target_info_by_id instead of get_target_info_by_name when you have the ID for better performance
• •Use get_project_target_times to get all target times in one call instead of querying individually
• •Results from get_expensive_projects and get_project_build_time are cached for performance
• •The binlog captures the complete build state, making it ideal for reproducing and diagnosing issues