maintaining-binary-log-compatibility
Binary Log Considerations
The binary log (.binlog) is MSBuild's primary diagnostic format and source of truth for build analysis. It captures the complete build event stream with full fidelity. Format changes have strict compatibility requirements.
For general binary log usage, see Binary-Log.md.
Core Principles
- The binlog captures everything. All meaningful build events must be represented. If your change alters build behavior, it must be observable in the binlog.
- Format changes must be backward-compatible. Older versions of MSBuild Structured Log Viewer and other tools must be able to read binlogs produced by newer MSBuild, at minimum gracefully degrading.
- Forward compatibility matters too. Newer viewers should handle binlogs from older MSBuild without crashing, even if some events are unrecognized.
Architecture Overview
Build Engine
→ BuildEventArgs (structured events)
→ BinaryLogger (serializes to .binlog)
→ ProjectImportsCollector (embeds project/targets files)
More from dotnet/msbuild
multithreaded-task-migration
Guide for migrating MSBuild tasks to multithreaded mode support, including compatibility red-team review. Use this when converting tasks to thread-safe versions, implementing IMultiThreadableTask, adding TaskEnvironment support, or auditing migrations for behavioral compatibility.
36changewaves
Manage MSBuild Change Waves: create new waves, condition features behind opt-out flags, write tests for wave-gated features, document change waves in ChangeWaves.md, and retire expired waves. Use when adding changes that need an opt-out or rotating out old change waves. Changes that introduce a user-visible behavior change should consider whether to use a changewave.
2merge-dependency-updates
Review and merge open bot PRs: dependency updates from dotnet-maestro, codeflow from dotnet/dotnet, and OneLoc localization PRs. Produces a clickable dashboard with CI status, review state, and suspicious file flags. Use when you want to triage all open bot PRs in one pass.
2use-bootstrap-msbuild
Guide for testing bug reproductions against locally-built MSBuild. Use this when you have a repro project and want to verify a fix works before submitting a PR.
2deploy-msbuild-to-vs
Deploy locally-built MSBuild binaries into a Visual Studio installation for testing and debugging. Use when you need VS itself to use your local MSBuild changes, or when debugging MSBuild as invoked by VS.
2pipelines-health-check
Check health of MSBuild CI pipelines, VS repo PR insertion statuses, and VMR codeflow PRs. Use when asked about pipeline health, build failures, infrastructure issues, CI status, insertion PR status, VMR codeflow status, or for periodic health monitoring.
2