OpenParable
Skip to content
← Back to skills

Binlog Generation

Testing & Quality
binlog-generation

Binlog Generation is an Agent Skill for testing & quality published in the dotnet/skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Generate MSBuild binary logs (binlogs) for build diagnostics and analysis. USE FOR: adding /bl:{} to any dotnet build, test, pack, publish, or restore command to capture a full build execution trace, prerequisite for binlog-failure-analysis and build-perf-diagnostics skills, enabling post-build investigation of errors or performance. Requires MSBuild 17.8+ / .NET 8 SDK+ for {} placeholder; PowerShell needs -bl:{{}}. DO NOT USE FOR: non-MSBuild build systems (npm, Maven, CMake), analyzing an existing binlog (use binlog-failure-analysis instead).

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/dotnet/skills/blob/HEAD/plugins/dotnet-msbuild/skills/binlog-generation/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/binlog-generation, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Generate Binary Logs

Pass the /bl switch when running any MSBuild-based command. This is a non-negotiable requirement for all .NET builds.

Commands That Require /bl

You MUST add the /bl:{} flag to:

  • dotnet build
  • dotnet test
  • dotnet pack
  • dotnet publish
  • dotnet restore
  • msbuild or msbuild.exe
  • Any other command that invokes MSBuild

Preferred: Use {} for Automatic Unique Names

Note: The {} placeholder requires MSBuild 17.8+ / .NET 8 SDK or later.

The {} placeholder in the binlog filename is replaced by MSBuild with a unique identifier, guaranteeing no two builds ever overwrite each other — without needing to track or check existing files.

# Every invocation produces a distinct file automatically
dotnet build /bl:{}
dotnet test /bl:{}
dotnet build --configuration Release /bl:{}

PowerShell requires escaping the braces:

# PowerShell: escape { } as {{ }}
dotnet build -bl:{{}}
dotnet test -bl:{{}}

Why This Matters

  1. Unique names prevent overwrites - You can always go back and analyze previous builds
  2. Failure analysis - When a build fails, the binlog is already there for immediate analysis
  3. Comparison - You can compare builds before and after changes
  4. No re-running builds - You never need to re-run a failed build just to generate a binlog

Examples

# ✅ CORRECT - {} generates a unique name automatically (bash/cmd)
dotnet build /bl:{}
dotnet test /bl:{}

# ✅ CORRECT - PowerShell escaping
dotnet build -bl:{{}}
dotnet test -bl:{{}}

# ❌ WRONG - Missing /bl flag entirely
dotnet build
dotnet test

# ❌ WRONG - No filename (overwrites the same msbuild.binlog every time)
dotnet build /bl
dotnet build /bl

When a Specific Filename Is Required

If the binlog filename needs to be known upfront (e.g., for CI artifact upload), or if {} is not available in the installed MSBuild version, pick a name that won't collide with existing files:

  1. Check for existing *.binlog files in the directory
  2. Choose a name not already taken (e.g., by incrementing a counter from the highest existing number)
# Example: directory contains 3.binlog — use 4.binlog
dotnet build /bl:4.binlog

Cleaning the Repository

When cleaning the repository with git clean, always exclude binlog files to preserve your build history:

# ✅ CORRECT - Exclude binlog files from cleaning
git clean -fdx -e "*.binlog"

# ❌ WRONG - This deletes binlog files (they're usually in .gitignore)
git clean -fdx

This is especially important when iterating on build fixes - you need the binlogs to analyze what changed between builds.