Back to Details

binlog-generation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Generate Binary Logs

生成二进制日志

Pass the 
/bl
switch when running any MSBuild-based command. This is a non-negotiable requirement for all .NET builds.
**在运行任何基于MSBuild的命令时，必须传递
/bl
参数。**这是所有.NET构建的硬性要求。

Commands That Require /bl

需要使用/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
你必须为以下命令添加
/bl:{}
参数：
  • dotnet build
  • dotnet test
  • dotnet pack
  • dotnet publish
  • dotnet restore
  • msbuild
    或
    msbuild.exe
  • 任何其他调用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.
bash
undefined
注意：
{}
占位符需要MSBuild 17.8+ / .NET 8 SDK或更高版本。
binlog文件名中的
{}
占位符会被MSBuild替换为唯一标识符，确保两次构建的日志不会互相覆盖——无需手动跟踪或检查现有文件。
bash
undefined

Every invocation produces a distinct file automatically

每次执行都会自动生成一个唯一的文件

dotnet build /bl:{} dotnet test /bl:{} dotnet build --configuration Release /bl:{}

**PowerShell requires escaping the braces:**

```powershell
dotnet build /bl:{} dotnet test /bl:{} dotnet build --configuration Release /bl:{}

**PowerShell中需要对大括号进行转义：**

```powershell

PowerShell: escape { } as {{ }}

PowerShell：将{ }转义为{{ }}

dotnet build -bl:{{}} dotnet test -bl:{{}}
undefined
dotnet build -bl:{{}} dotnet test -bl:{{}}
undefined

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
  1. 唯一名称避免覆盖 - 你可以随时回溯并分析之前的构建记录
  2. 故障排查 - 当构建失败时，binlog已准备好供立即分析
  3. 对比分析 - 你可以对比变更前后的构建情况
  4. 无需重新构建 - 永远不需要为了生成binlog而重新运行失败的构建

Examples

示例

bash
undefined
bash
undefined

✅ CORRECT - {} generates a unique name automatically (bash/cmd)

✅ 正确用法 - {}会自动生成唯一名称（bash/cmd环境）

dotnet build /bl:{} dotnet test /bl:{}
dotnet build /bl:{} dotnet test /bl:{}

✅ CORRECT - PowerShell escaping

✅ 正确用法 - PowerShell中的转义写法

dotnet build -bl:{{}} dotnet test -bl:{{}}
dotnet build -bl:{{}} dotnet test -bl:{{}}

❌ WRONG - Missing /bl flag entirely

❌ 错误用法 - 完全缺少/bl参数

dotnet build dotnet test
dotnet build dotnet test

❌ WRONG - No filename (overwrites the same msbuild.binlog every time)

❌ 错误用法 - 未指定文件名（每次构建都会覆盖同一个msbuild.binlog文件）

dotnet build /bl dotnet build /bl
undefined
dotnet build /bl dotnet build /bl
undefined

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)
bash
undefined
如果需要预先确定binlog文件名（例如用于CI制品上传），或者当前安装的MSBuild版本不支持
{}
占位符，请选择一个不会与现有文件冲突的名称：
  1. 检查目录中已有的
    *.binlog
    文件
  2. 选择一个未被使用的名称（例如，在现有最高编号基础上加1）
bash
undefined

Example: directory contains 3.binlog — use 4.binlog

示例：目录中已有3.binlog —— 使用4.binlog

dotnet build /bl:4.binlog
undefined
dotnet build /bl:4.binlog
undefined

Cleaning the Repository

清理仓库

When cleaning the repository with 
git clean
, always exclude binlog files to preserve your build history:
bash
undefined
使用
git clean
清理仓库时，务必排除binlog文件以保留构建历史：
bash
undefined

✅ CORRECT - Exclude binlog files from cleaning

✅ 正确用法 - 清理时排除binlog文件

git clean -fdx -e "*.binlog"
git clean -fdx -e "*.binlog"

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

❌ 错误用法 - 会删除binlog文件（它们通常已被加入.gitignore）

git clean -fdx

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

这在迭代修复构建问题时尤为重要——你需要binlog来分析不同构建之间的变化。