binlog-generation

Generate Binary Logs

Cratis rules in .cratis/ai/rules/ (including csharp.md, specs.csharp.md, and orleans.md) and the cratis-* skills win where they differ. Binlogs embed project and imported file contents: keep them local and task-scoped.

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.12+ / .NET 9.0.100 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

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