binlog-failure-analysis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Analyzing MSBuild Failures with Binary Logs

借助二进制日志分析MSBuild构建失败问题

Use MSBuild's built-in binlog replay to convert binary logs into searchable text logs, then analyze with standard tools (

grep

cat

head

tail

find

使用MSBuild内置的binlog重放功能将二进制日志转换为可搜索的文本日志，然后通过标准工具（

grep

、

cat

、

head

、

tail

、

find

）进行分析。

Build Error Investigation (Primary Workflow)

构建错误排查（主要流程）

Step 1: Replay the binlog to text logs

步骤1：将binlog重放为文本日志

Replay produces multiple focused log files in one pass:

bash

dotnet msbuild build.binlog -noconlog \
  -fl  -flp:v=diag;logfile=full.log;performancesummary \
  -fl1 -flp1:errorsonly;logfile=errors.log \
  -fl2 -flp2:warningsonly;logfile=warnings.log

PowerShell note: Use
-flp:"v=diag;logfile=full.log;performancesummary"
(quoted semicolons).

一次重放操作会生成多个针对性的日志文件：

bash

dotnet msbuild build.binlog -noconlog \
  -fl  -flp:v=diag;logfile=full.log;performancesummary \
  -fl1 -flp1:errorsonly;logfile=errors.log \
  -fl2 -flp2:warningsonly;logfile=warnings.log

PowerShell注意事项： 使用
-flp:"v=diag;logfile=full.log;performancesummary"
（分号需加引号）。

Step 2: Read the errors

步骤2：查看错误信息

bash

cat errors.log

This gives all errors with file paths, line numbers, error codes, and project context.

bash

cat errors.log

此命令会输出所有错误的文件路径、行号、错误代码以及项目上下文信息。

Step 3: Search for context around specific errors

步骤3：搜索特定错误的上下文信息

bash

undefined

bash

undefined

Find all occurrences of a specific error code with surrounding context

查找特定错误代码的所有出现位置及前后上下文

grep -n -B2 -A2 "CS0246" full.log

Find which projects failed to compile

查找哪些项目编译失败

grep -i "CoreCompile.*FAILED|Build FAILED|error MSB" full.log

Find project build order and results

查找项目构建顺序及结果

grep "done building project|Building with" full.log | head -50

undefined

grep "done building project|Building with" full.log | head -50

undefined

Step 4: Detect cascading failures

步骤4：检测连锁失败问题

Projects that never reached

CoreCompile

failed because a dependency failed, not their own code:

bash

undefined

若项目从未执行到

CoreCompile

环节，则说明失败原因是依赖项出错，而非自身代码问题：

bash

undefined

List all projects that ran CoreCompile

列出所有执行过CoreCompile的项目

grep 'Target "CoreCompile"' full.log | grep -oP 'project "[^"]*"'

Compare against projects that had errors to identify cascading failures

对比出现错误的项目，识别连锁失败问题

grep "project.*FAILED" full.log

undefined

grep "project.*FAILED" full.log

undefined

Step 5: Examine project files for root causes

步骤5：检查项目文件以定位根本原因

bash

undefined

bash

undefined

Read the .csproj of the failing project

读取失败项目的.csproj文件

cat path/to/Services/Services.csproj

Check PackageReference and ProjectReference entries

检查PackageReference和ProjectReference条目

grep -n "PackageReference|ProjectReference" path/to/Services/Services.csproj


**Write your diagnosis as soon as you have enough information.** Do not over-investigate.

grep -n "PackageReference|ProjectReference" path/to/Services/Services.csproj


**一旦获取足够信息，请立即记录诊断结果，不要过度排查。**

Additional Workflows

其他流程

Performance Investigation

性能排查

bash

undefined

bash

undefined

The PerformanceSummary is at the end of full.log

性能摘要位于full.log的末尾

tail -100 full.log # shows target/task timing summary grep "Target Performance Summary|Task Performance Summary" -A 50 full.log

undefined

tail -100 full.log # 显示目标/任务的时间摘要 grep "Target Performance Summary|Task Performance Summary" -A 50 full.log

undefined

Dependency/Evaluation Issues

依赖项/评估问题排查

bash

undefined

bash

undefined

Check evaluation properties

检查评估属性

grep -i "OutputPath|IntermediateOutputPath|TargetFramework" full.log | head -30

Check item groups

检查项组

grep "PackageReference|ProjectReference" full.log | head -30

undefined

grep "PackageReference|ProjectReference" full.log | head -30

undefined

Replay reference

重放命令参考

Command	Purpose
`dotnet msbuild X.binlog -noconlog -fl -flp:v=diag;logfile=full.log;performancesummary`	Full diagnostic log with perf summary
`dotnet msbuild X.binlog -noconlog -fl -flp:errorsonly;logfile=errors.log`	Errors only
`dotnet msbuild X.binlog -noconlog -fl -flp:warningsonly;logfile=warnings.log`	Warnings only
`grep -n "PATTERN" full.log`	Search for patterns in the replayed log
`dotnet msbuild -pp:preprocessed.xml Proj.csproj`	Preprocess — inline all imports into one file

命令	用途
`dotnet msbuild X.binlog -noconlog -fl -flp:v=diag;logfile=full.log;performancesummary`	生成包含性能摘要的完整诊断日志
`dotnet msbuild X.binlog -noconlog -fl -flp:errorsonly;logfile=errors.log`	仅生成错误日志
`dotnet msbuild X.binlog -noconlog -fl -flp:warningsonly;logfile=warnings.log`	仅生成警告日志
`grep -n "PATTERN" full.log`	在重放后的日志中搜索指定模式
`dotnet msbuild -pp:preprocessed.xml Proj.csproj`	预处理——将所有导入内容内联到单个文件中

Generating a binlog (only if none exists)

生成binlog（仅当无现有binlog时使用）

bash

dotnet build /bl:build.binlog

bash

dotnet build /bl:build.binlog

Common error patterns

常见错误模式

CS0246 / "type not found" → Missing PackageReference — check the .csproj
MSB4019 / "imported project not found" → SDK install or global.json issue
NU1605 / "package downgrade" → Version conflict in package graph
MSB3277 / "version conflicts" → Binding redirect or version alignment issue
Project failed at ResolveProjectReferences → Cascading failure from a dependency

CS0246 / "类型未找到" → 缺少PackageReference——检查.csproj文件
MSB4019 / "导入的项目未找到" → SDK安装或global.json配置问题
NU1605 / "包降级" → 包依赖图中的版本冲突
MSB3277 / "版本冲突" → 绑定重定向或版本对齐问题
项目在ResolveProjectReferences环节失败 → 依赖项导致的连锁失败