Binlog generation

Skill dotnet/skills/plugins/dotnet-msbuild/skills/binlog-generation

Repository for skills to assist AI coding agents with .NET and C#

Install

npx -y skills add dotnet/skills --skill binlog-generation

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its author says it does

Copied from the file, not written here

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).

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

4.1 KB, as published. Nobody here has run it

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

Unique names prevent overwrites - You can always go back and analyze previous builds
Failure analysis - When a build fails, the binlog is already there for immediate analysis
Comparison - You can compare builds before and after changes
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

One build = one binlog

Add /bl:{} to every MSBuild invocation separately — never reuse a name and never rely on bare /bl:

Building several configurations, projects, or retrying a failed build? Each command still gets its own /bl:{} so the logs never overwrite each other.

dotnet build -c Debug   /bl:{}   # unique file
dotnet build -c Release /bl:{}   # another unique file

Verify the binlog exists

After the build, confirm a .binlog was actually produced before moving on to analysis — a build that fails before MSBuild starts (e.g. a bad argument) writes no binlog:

ls -1 *.binlog       # bash
dir /b *.binlog      # Windows cmd

Get-ChildItem *.binlog   # PowerShell

Note the resulting path so binlog-failure-analysis or build-perf-diagnostics can consume it.

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:

Check for existing *.binlog files in the directory
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.