Generate MSBuild binary logs for build diagnostics and performance analysis by adding the /bl switch to .NET commands.
- GitHub stars
- 5,942
- Files
- 1
- Last commit
- Nov 11, 2026
- License
- MIT
- Allowed tools
- —
What does the binlog-generation skill do?
binlog-generation generates MSBuild binary logs for build diagnostics and performance analysis by adding the /bl switch to .NET commands.
Summary generated from the skill's SKILL.md.
About the binlog-generation skill
Capturing MSBuild execution traces for .NET developers is the primary function of this skill. It works by appending the /bl switch to standard .NET commands such as dotnet build, test, pack, publish, or restore. This process creates binary log files that serve as a necessary prerequisite for subsequent diagnostic tools like binlog-failure-analysis and build-perf-diagnostics.
Users with MSBuild 17.8 or .NET 8 SDK can utilize the {} placeholder to automatically generate unique filenames, which prevents different build runs from overwriting each other. When working in PowerShell, the complete switch must be quoted to ensure the placeholder is handled correctly. This skill is specifically designed for MSBuild-based systems and should not be used for npm, Maven, or CMake environments.
By generating these logs during the initial build attempt, developers can perform post-build investigations into errors or performance issues without needing to re-run failed processes. This approach allows for comparing builds before and after code changes to identify specific regressions.
What an agent can do with it
- 1Capture unique build tracesGenerate a unique binary log for a dotnet build command to prevent overwriting previous logs.
- 2Prepare for failure analysisAdd the binlog switch to a failing dotnet test command so the resulting file can be analyzed.
- 3Execute PowerShell build commandsRun a dotnet pack command in PowerShell while ensuring the binlog switch is properly quoted.
- 4Compare build performanceCreate separate binlogs for different configurations to compare build results.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the binlog-generation skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the binlog-generation skill in Plugin
/plugin marketplace add dotnet/skills /plugin install dotnet-msbuild@dotnet-agent-skills
Install the binlog-generation skill in Claude Code
~/.claude/skills/binlog-generation/SKILL.md
$ npx degit dotnet/skills/plugins/dotnet-msbuild/skills/binlog-generation ~/.claude/skills/binlog-generationInstall the binlog-generation skill in Claude Code (project)
.claude/skills/binlog-generation/SKILL.md
$ npx degit dotnet/skills/plugins/dotnet-msbuild/skills/binlog-generation .claude/skills/binlog-generationInstall the binlog-generation skill in Codex
~/.agents/skills/binlog-generation/SKILL.md
$ npx degit dotnet/skills/plugins/dotnet-msbuild/skills/binlog-generation ~/.agents/skills/binlog-generationInstall the binlog-generation skill in Gemini CLI
~/.gemini/skills/binlog-generation/SKILL.md
$ npx degit dotnet/skills/plugins/dotnet-msbuild/skills/binlog-generation ~/.gemini/skills/binlog-generationInstall the binlog-generation skill in Claude.ai
npx degit dotnet/skills/plugins/dotnet-msbuild/skills/binlog-generation binlog-generation && zip -r binlog-generation.zip binlog-generation # claude.ai → Customize → Skills → + → Create skill → Upload a skill → binlog-generation.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachabledotnet/skills/plugins/dotnet-msbuild/skills/binlog-generation is public and reachablegithub.com/dotnet/skills/tree/HEAD/plugins/dotnet-msbuild/sk ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-11github.com/dotnet/skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/dotnet/skills/blob/HEAD/plugins/dotnet-msbuild/sk ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/dotnet/skills/blob/HEAD/plugins/dotnet-msbuild/sk ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 126 linesgithub.com/dotnet/skills/blob/HEAD/plugins/dotnet-msbuild/sk ↗Pass
SKILL.md
View on GitHubGenerate 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 builddotnet testdotnet packdotnet publishdotnet restoremsbuildormsbuild.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 quoting the complete switch:
# Keep the literal {} placeholder in one argument
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 - quote the complete PowerShell argument
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
*.binlogfiles 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.
Files in this skill
1binlog-generation skill questions
How do I install the binlog-generation skill in Claude Code?
Run npx degit dotnet/skills/plugins/dotnet-msbuild/skills/binlog-generation ~/.claude/skills/binlog-generation. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the binlog-generation skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How do I ensure binlog filenames are unique and do not overwrite each other?
Use the {} placeholder in the /bl switch, which MSBuild replaces with a unique identifier. This requires MSBuild 17.8+ or .NET 8 SDK or later.