MSBuild 二进制日志（binlog）生成实战指南：用 /bl:{} 为每次 .NET 构建捕获完整执行轨迹

MSBuild 二进制日志（binlog）生成实战指南：用 /bl:{} 为每次 .NET 构建捕获完整执行轨迹

【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills

导读

在 dotnet-msbuild 插件体系中，binlog-generation技能定义了 MSBuild 二进制日志（.binlog）的生成规范：任何调用 MSBuild 的 .NET 命令都必须携带/bl:{}开关，借助{}占位符让每次构建自动生成唯一命名的日志文件，从而为后续的构建失败诊断与性能分析保留一手证据。读完本文，你将掌握为dotnet build/test/pack/publish/restore等命令正确添加 binlog 开关的完整姿势，包括 PowerShell 下的花括号转义、多配置构建的唯一文件名保证、binlog 存在性验证以及仓库清理时的保护策略。

为什么每个 .NET 构建都离不开/bl开关

/bl（binary log）是 MSBuild 内置的二进制日志开关。与文本日志不同，binlog 以紧凑的二进制格式记录了一次构建的完整执行轨迹——包括项目评估数据、目标（Target）执行顺序、任务（Task）调用、属性（Property）与项（Item）的最终值、编译诊断等。这一格式正是 binlog-failure-analysis 技能 进行构建故障诊断的数据前提。

在 binlog-generation 技能的元数据声明 中，该技能被定义为binlog-failure-analysis与构建性能诊断类技能的前置依赖，属于"所有 .NET 构建的强制要求（non-negotiable requirement）"。换句话说：没有 binlog，就没有可回溯的构建现场。当控制台输出信息不足以定位错误、多项目级联失败难以梳理、目标执行顺序需要追溯时，唯一的可靠手段就是打开 binlog。

从 msbuild agent 的路由表 可以看到，当用户报告"构建失败需要诊断"时，agent 的标准路径就是先检查是否存在可用的*.binlog，没有则调用本技能生成，再交给binlog-failure-analysis分析——binlog 生成是整条诊断链的第一环。

必须携带/bl:{}的命令清单

任何会触发 MSBuild 引擎的命令都要单独添加/bl:{}开关：

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

需要强调的是：dotnet restore同样会执行 MSBuild 的项目评估，评估阶段的错误（如属性解析失败）只有在 restore 阶段打开 binlog 才能捕获，因此它也被列入强制清单。

首选方案：用{}占位符自动生成唯一文件名

占位符的工作原理与版本前提

在 binlog 文件名中使用{}占位符，MSBuild 会在构建时将其替换为一个唯一标识符，从而保证任意两次构建都不会互相覆盖——你既不需要手动跟踪已有文件，也不必在每次构建前检查目录。这正是 eval.yaml 评估用例 所强调的核心验收标准：优先使用/bl:{}或-bl:{}自动生成唯一文件名。

版本前提：{}占位符需要 MSBuild 17.8+ / .NET 8 SDK 或更高版本。在当前仓库的评估夹具中，测试项目 SimpleApp.csproj 目标框架为net8.0，与这一版本要求一致。

bash / cmd 用法

# 每次调用都会自动产生一个不同的 binlog 文件 dotnet build /bl:{} dotnet test /bl:{} dotnet build --configuration Release /bl:{}

PowerShell 中的花括号转义

PowerShell 会把{}视为脚本块语法，因此必须转义为{{}}：

# PowerShell: 将 { } 转义为 {{ }} dotnet build -bl:{{}} dotnet test -bl:{{}}

这一转义规则在评估测试中同样被严格校验：PowerShell 场景的 输出匹配正则 只接受-bl:{{}}或/bl:{{}}这种双重花括号形式。

为什么必须用唯一文件名：四个核心理由

1. 唯一名称防止覆盖——随时可以回到过去的任意一次构建现场做分析，不会因为后续构建而丢失证据；
2. 失败分析就绪——构建失败的那一刻 binlog 已经落盘，可以直接进入诊断流程，无需任何补救动作；
3. 构建前后对比——同一代码变更前后的 binlog 可以并排比较目标执行差异、属性值变化与耗时分布；
4. 无需重跑构建——永远不必为了生成一个 binlog 而重跑一次已经失败的构建，节省时间且避免环境差异引入误导。

正误用法对照

# ✅ 正确 - {} 在 bash/cmd 下自动生成唯一名称 dotnet build /bl:{} dotnet test /bl:{} # ✅ 正确 - PowerShell 转义 dotnet build -bl:{{}} dotnet test -bl:{{}} # ❌ 错误 - 完全缺失 /bl 开关，构建无任何日志留存 dotnet build dotnet test # ❌ 错误 - 裸 /bl 不带文件名，每次都覆盖同一个 msbuild.binlog dotnet build /bl dotnet build /bl

最后一条尤其隐蔽：dotnet build /bl在语法上"合法"，但它每次都会写入并覆盖默认的msbuild.binlog，等于只有最后一次构建的现场，之前的证据全部丢失。这也是 eval.yaml 的验收红线：禁止在{}可用时使用裸/bl，也不得使用/bl:build.binlog这类硬编码文件名。

一次构建一个 binlog：逐条命令独立命名

把/bl:{}添加到每一次MSBuild 调用上，而不是复用同一个名称，也不要依赖裸/bl。尤其是构建多个配置、多个项目或重试失败构建时，每条命令仍然各自携带/bl:{}，日志之间互不覆盖：

dotnet build -c Debug /bl:{} # 唯一文件 dotnet build -c Release /bl:{} # 另一个唯一文件

多配置构建场景正是本技能的第三个 评估用例：Debug 与 Release 两次构建都必须分别使用{}占位符，两次调用不得共享同一个 binlog 文件——否则第二次构建会把第一次的日志覆盖掉，无法进行配置间的性能与行为对比。

验证 binlog 确实生成

构建结束后、进入分析之前，务必确认.binlog文件真的产生了。注意：如果构建在 MSBuild 启动之前就失败（例如参数错误），不会写入任何 binlog，此时应直接修复命令而非等待日志。

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

Get-ChildItem *.binlog # PowerShell

记录生成的 binlog 路径，后续的binlog-failure-analysis或构建性能诊断技能需要消费这个文件。在 binlog-failure-analysis 的备用流程 中可以看到，拿到.binlog后既可以通过插件捆绑的 binlog MCP 服务器（Microsoft.AITools.BinlogMcp，声明见 plugin.json）直接结构化查询，也可以用dotnet msbuild build.binlog -noconlog -fl ...重放为文本日志再检索错误——无论哪条路，前提都是 binlog 已正确生成。

需要指定文件名的情况

在以下两种场景下，{}占位符不适用，需要手动指定一个不会冲突的文件名：

• CI 制品上传需要预先知道文件名（如流水线中要显式引用build.binlog作为 artifact）；
• 当前 MSBuild 版本不支持{}占位符（低于 17.8 / .NET 8 SDK）。

此时遵循两步法：

1. 先检查目录中已有的*.binlog文件；
2. 选择未被占用的名称，例如在现有最高编号上递增。

# 示例：目录里已有 3.binlog —— 使用 4.binlog dotnet build /bl:4.binlog

清理仓库时必须保护 binlog

使用git clean清理仓库时，必须排除 binlog 文件，以保留构建历史。binlog 通常已在.gitignore中，一旦被git clean -fdx清掉将无法恢复：

# ✅ 正确 - 清理时排除 binlog 文件 git clean -fdx -e "*.binlog" # ❌ 错误 - 这会把 binlog 文件一并删除（它们通常在 .gitignore 中） git clean -fdx

这一点在反复迭代构建修复时尤其重要——你需要用 binlog 来对比每次改动前后构建行为的变化，丢失历史日志等于丢失对比基准。

总结：binlog 生成的黄金规则

1. 凡是 MSBuild 命令，一律加/bl:{}，dotnet build/test/pack/publish/restore、msbuild(.exe)无一例外；
2. 默认使用{}占位符（MSBuild 17.8+ / .NET 8 SDK+），让唯一文件名自动生成，杜绝覆盖；PowerShell 下转义为{{}}；
3. 绝不使用裸/bl，也不要在{}可用时硬编码文件名；
4. 每次构建后验证*.binlog确实生成并记录路径，供 binlog-failure-analysis 等下游技能消费；
5. 只有 CI 需要预知文件名或 MSBuild 版本过老时，才改用不冲突的显式文件名；
6. git clean时用-e "*.binlog"排除，保护构建历史。

遵循这些规则，你的每一次 .NET 构建都会自动留下一份完整、唯一、可回溯的执行快照——这正是快速定位构建失败、优化构建性能的坚实基础。

【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills