maintaining-binary-log-compatibility

name	maintaining-binary-log-compatibility
description	Guides changes to MSBuild binary log infrastructure. Consult when modifying BinaryLogger or BinaryLogReplayEventSource, adding new BuildEventArgs types, changing event serialization/deserialization, modifying ProjectImportsCollector, adjusting message importance levels, or making changes that affect .binlog content. Also applies when verifying that behavioral changes are properly reflected in binary log output.
argument-hint	Describe the binary log change or event serialization concern.

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

1. The binlog captures everything. All meaningful build events must be represented. If your change alters build behavior, it must be observable in the binlog.
2. 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.
3. 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)

Replay:
  .binlog file
    → BinaryLogReplayEventSource (deserializes)
      → Any ILogger (console, structured log viewer, analyzers)