Adding Custom Events to MSBuild

MSBuild has many built-in event types, but often you may need to add a new custom one.

Steps for Binary Logger Compatibility

This guide outlines the steps to ensure the BinaryLogger can work with your new event.

Changes in MSBuild

1. Add the NewEventArgs to src/Framework folder
2. Update BinaryLogRecordKind.cs
   • Append the new event to the enum
3. Modify BinaryLogger.cs
   • Update FileFormatVersion
4. Update BuildEventArgsReader.cs
   • Add a new case in the ReadBuildEventArgs switch
   • Implement a method for the added event (imitate other ReadXYZEventArgs methods)
5. Modify BuildEventArgsWriter.cs
   • Add a new case in WriteCore
   • Document the change above the method
6. Update LogMessagePacketBase.cs
   • Add to LoggingEventType
   • Add case in GetBuildEventArgFromId and GetLoggingEventId
7. Create a new test file
   • Add Framework.UnitTests/NewEventArgs_Tests.cs
   • Use BuildSubmissionStartedEventArgs_Tests.cs as a reference
8. Update NodePackets_Tests.cs
   • Add relevant test cases

Changes in MSBuildStructuredLog

1. Update BinaryLogRecordKind.cs

   • Append the new event to the enum

2. Modify BinaryLogger.cs

   • Increment version
   • Document the change

3. Create src/StructuredLogger/BinaryLogger/XXXEventArgs.cs

   • Implement the class for the new event (copy from MSBuild)

4. Update BuildEventArgsReader.cs

   • Add a new case in ReadBuildEventArgs

5. Modify BuildEventArgsWriter.cs

   • Add a new case in WriteCore

Example Pull Requests adding and serializing events

1. Add Buildcheck events support + BuildSubmissionStarted (MSBuildStructuredLog)

   • Corresponding MSBuild PR

2. Add Binary Logger Support for BuildCanceled (MSBuild)

   • Corresponding MSBuildStructuredLog PR