binlog-generation

生成二进制日志

运行任何基于 MSBuild 的命令时，都要传入 /bl 开关。 这是所有 .NET 构建都必须遵守的要求。

需要使用 /bl 的命令

必须为以下命令添加 /bl:{} 标志：

• dotnet build
• dotnet test
• dotnet pack
• dotnet publish
• dotnet restore
• msbuild 或 msbuild.exe
• 任何其他会调用 MSBuild 的命令

首选：使用 {} 自动生成唯一名称

注意： {} 占位符要求使用 MSBuild 17.8+ / .NET 8 SDK 或更高版本。

MSBuild 会将 binlog 文件名中的 {} 占位符替换为唯一标识符，确保任意两次构建都不会互相覆盖，无需跟踪或检查现有文件。

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

PowerShell 要求为整个开关加引号：

# Keep the literal {} placeholder in one argument
dotnet build '-bl:{}'
dotnet test '-bl:{}'

这样做的重要性

1. 唯一名称可防止覆盖 - 你可以随时回头分析之前的构建
2. 故障分析 - 构建失败时，binlog 已经生成，可立即用于分析
3. 对比 - 你可以对比更改前后的构建
4. 无需重新运行构建 - 你不必为了生成 binlog 而重新运行失败的构建

示例

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

一次构建 = 一个 binlog

每次调用 MSBuild 时，都要分别添加 /bl:{} —— 绝不要重复使用名称，也不要依赖不带参数的 /bl：

• 构建多个配置、项目，或重试失败的构建？每条命令仍然都要使用自己的 /bl:{}，这样日志就不会互相覆盖。

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

确认 binlog 文件存在

构建完成后，在继续分析之前，请确认确实生成了 .binlog 文件——如果构建在 MSBuild 启动前就失败（例如参数错误），则不会生成 binlog：

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

Get-ChildItem *.binlog   # PowerShell

记下生成的路径，以便 binlog-failure-analysis 或 build-perf-diagnostics 使用。

需要指定文件名时

如果需要预先确定 binlog 文件名（例如用于 CI 构件上传），或者已安装的 MSBuild 版本不支持 {}，请选择一个不会与现有文件冲突的名称：

1. 检查目录中是否存在 *.binlog 文件
2. 选择一个尚未使用的名称（例如，从现有最大编号开始递增计数器）

# Example: directory contains 3.binlog — use 4.binlog
dotnet build /bl:4.binlog

清理仓库

使用 git clean 清理仓库时，始终排除 binlog 文件，以保留构建历史：

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

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

在反复修复构建问题时，这一点尤其重要——你需要 binlog 来分析各次构建之间的变化。