Do you use binlogs to diagnose build issues?

Some build failures are easy - the error tells you exactly what to fix. Then there are the others: a property that mysteriously has the wrong value, a stale DLL being copied from who-knows-where, a build that works locally but fails in CI, or a multi-targeted project that behaves differently per framework. Staring at console output (or a 200 MB diagnostic text log) is a slow way to solve these.

MSBuild binary logs (binlogs) capture everything the build did - every project, property, item, task, and environment variable - in a compact, searchable file.

Capturing a binlog

Add -bl to any build-related command:

dotnet build -bl
dotnet restore -bl:restore.binlog
dotnet publish -bl:publish.binlog

This produces an msbuild.binlog file (or the name you specified) in the current directory.

For builds started inside Visual Studio, install the Project System Tools extension to capture binlogs from IDE builds.

Analyzing it with the Structured Log Viewer

Open the file in the free MSBuild Structured Log Viewer - it turns the log into a navigable tree with full-text search.

Things that are painful with console output and trivial in the viewer:

• "Where did this property value come from?" - search $property TargetFramework and see every assignment, including which .props file set it. Invaluable when debugging Directory.Build.props inheritance and multi-targeting conditions
• NuGet version conflicts - capture a restore binlog to see exactly how a NU1605 downgrade or version conflict was resolved
• Double writes - the viewer flags 2 different source files being copied to the same output path (the classic cause of "stale DLL" bugs)
• Slow builds - the Timeline and "Top 10 most expensive tasks" views show where the time actually goes
• Why did this rebuild? - task inputs/outputs are recorded, so you can see which file triggered an incremental rebuild
• Preprocessed project view - see a project's XML with every import expanded inline, exactly as MSBuild evaluated it

Let AI analyze your binlogs

Binlogs aren't just for humans. The Microsoft Binlog MCP Server lets AI assistants (GitHub Copilot, Claude Code, etc.) query a binlog directly - it's built on the same engine as the Structured Log Viewer and exposes tools for exactly the investigations above: errors and warnings with full context, property tracing, the most expensive projects/targets/tasks, embedded file search, and comparing 2 builds.

The easiest setup is the dotnet-msbuild plugin from the .NET Agent Skills repo, which bundles the MCP server with curated skills for build investigation. You can also register the server manually:

{
  "servers": {
    "binlog-mcp": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["tool", "run", "Microsoft.AITools.BinlogMcp"]
    }
  }
}

✅ Good example - .vscode/mcp.json registering the Binlog MCP Server as a dotnet tool

Once connected, capture a binlog and ask questions like:

• "Why did this build fail?"
• "Where did TargetFramework get its value in MyProject?"
• "Compare local.binlog and ci.binlog - why is CI slower?"

This also works beyond the chat window - an agent in your pipeline can pick up the binlog from a failed build and post a diagnosis, see MCP Beyond the Chat Window: Build Diagnostics in CI.

Use binlogs instead of diagnostic text logs

dotnet build -v:diag > build.log

❌ Bad example - Diagnostic verbosity dumps hundreds of MB of unsearchable text and still misses structure

dotnet build -bl

✅ Good example - A binlog is smaller, complete, and opens in a purpose-built viewer

Capture binlogs in CI

The worst place to debug a build is a CI agent you can't touch. Produce a binlog in your pipeline and upload it as an artifact when the build fails:

- name: Build
  run: dotnet build -bl:build.binlog

- name: Upload binlog
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: binlog
    path: build.binlog

✅ Good example - GitHub Actions publishing a binlog on failure, so "works on my machine" arguments end with evidence

⚠️ Binlogs contain secrets

A binlog embeds environment variables, command lines, and the full content of your project and targets files. Treat it like a memory dump:

• ❌ Never attach a binlog to a public GitHub issue
• ⚠️ The same caution applies to AI tooling - an assistant connected to the Binlog MCP Server can read everything in the log, including environment variables
• ✅ Share via private channels, and rotate any secrets that were in environment variables if one leaks