skills.rest
dotnet
dotnetOFFICIAL
Explore all skills by this author →
Website𝕏@dotnetfdnGitHub

maintaining-binary-log-compatibility

Guides backward-compatible changes to MSBuild binary log serialization and event types.

1.2k|337|Updated Oct 13, 2022
Search Tags:#backward compatibility#serialization#Diagnostics#msbuild#binlog#binary log#build events
One-click install
npx skills add https://github.com/dotnet/dotnet --skill maintaining-binary-log-compatibility
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: maintaining-binary-log-compatibility
Source: https://github.com/dotnet/dotnet/tree/main/src/msbuild/.github/skills/maintaining-binary-log-compatibility
Command: npx skills add https://github.com/dotnet/dotnet --skill maintaining-binary-log-compatibility

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Changes to MSBuild's BinaryLogger, BuildEventArgs types, or event serialization can silently break the .binlog format, causing older log viewers to crash or lose diagnostic data. This Skill provides the rules and checklist needed to keep binary log output backward- and forward-compatible.

Core Features & Use Cases

  • Serialization Compatibility Rules: Enforces append-only field additions, version-gated reads/writes, and graceful handling of unknown record types so older MSBuild Structured Log Viewer versions keep working.
  • New Event Type Guidance: Walks through adding BuildEventArgs subclasses with WriteToStream/CreateFromStream implementations, record type constants, and format version increments.
  • Importance Levels & ProjectImportsCollector: Clarifies message importance semantics and how imported .props/.targets files are embedded into binlogs.
  • Use Case: When adding a new build warning event to MSBuild, follow the checklist to implement serialization, bump the binlog version, and add a round-trip test verifying replay through BinaryLogReplayEventSource.

Quick Start

Ask the AI to review your BinaryLogger or BuildEventArgs change for binary log compatibility and generate the required serialization and test updates.

Frequently Asked Questions about maintaining-binary-log-compatibility

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new BuildEventArgs type to the MSBuild binary log?▼

Create the event class inheriting from the appropriate base, implement WriteToStream and CreateFromStream, add a record type constant, increment the binary log version if the format changed, and ensure older replay sources skip the unknown type gracefully.

How do I keep .binlog files backward compatible when changing serialization?▼

Never remove existing fields, append new fields at the end of the stream, and gate reads and writes on the log version so older data uses default values. Older viewers must degrade gracefully rather than crash.

Does message importance affect what gets written to the binary log?▼

No, importance only controls console verbosity. Everything is written to the binlog regardless of importance level, so use Low for noisy diagnostics instead of skipping logging entirely.

How do I test that binary log changes work correctly?▼

Write a binlog, replay it with BinaryLogReplayEventSource, and verify all events round-trip correctly. Also test that older replay sources handle new events gracefully and assert behavioral changes produce observable events.

What does ProjectImportsCollector capture in a binlog?▼

It embeds all imported .props, .targets, and project files into the binlog at evaluation time, enabling the preprocessed view in log viewers. Note that sensitive content in imported files will be embedded.

Related Skills

Explore More Software Engineering Skills→
sayedihashimisayedihashimi
2

binlog-generation

Generate MSBuild binary logs with the /bl: switch for .NET build diagnostics.

Community
Intermediate
dotnetdotnet
5.1k

build-perf-diagnostics

Diagnose MSBuild performance bottlenecks by analyzing binlog files.

Official
Intermediate
dotnetdotnet
5.1k

incremental-build

Analyze MSBuild binlogs to diagnose and fix incremental build issues.

Official
Intermediate
outfitter-devoutfitter-dev
6

outfitter-logging

Configure @outfitter/logging loggers with custom levels, sinks, and redaction.

Official
Intermediate