[Breaking change]: Document MSBuild deprecation of custom derived BuildEventArgs

[JanKrivanek]

Description

The document should be very visibly linked from https://learn.microsoft.com/en-us/dotnet/api/microsoft.build.framework.custombuildeventargs (or it should be made part of that document).

dotnet/msbuild#8917 introduces deprecation of custom derived build events of any subclass of BuildEventArgs by any build extensibility (mainly custom tasks).
From net8 - if any such event is used when building with NET8 version of msbuild (means from commandline) - a build error will be issued:

Usage of unsecure BinaryFormatter during serialization of custom event type 'MyCustomBuildEventArgs'. This will be deprecated soon. Please use Extended*EventArgs instead. More info: https://aka.ms/msbuild/eventargs

The behavior can be opted out via explicitly setting env. var MSBUILDCUSTOMBUILDEVENTWARNING to something else then 1.
The warning might be given a MSB code - then another way of suppressing would be usage of MSBuildWarningsAsMessages

When building on Full Framework version of MSBuild (Visual Studio case), then this behavior is not on by default. It'll be introduced in VS17.8 and will be explicit opt-in by setting MSBUILDCUSTOMBUILDEVENTWARNING to 1. When opted in, it will introduce a build warning (as opposed to build error in NET8+) with the same wording as above.

Version

.NET 8 RC 1

Previous behavior

It was allowed to derive from any subclass of BuildEventArgs and use those freely in custom Tasks and other build extensibility points

New behavior

A build error or a build warning will be issued

	Building your MSBuild extensibility	Build leveraging the MSBuild extensibility with custom build events (regardless how that one was built)	Previous scenario with MSBUILDCUSTOMBUILDEVENTWARNING=1 in environment	Previous scenario with MSBUILDCUSTOMBUILDEVENTWARNING=0 in environment
.NET 8+	No change	Build error,  Custom event dropped	Build error,  Custom event dropped	Build crashes  (unless EnableUnsafeBinaryFormatterSerialization explicitly enabled in MSBuild runtimeconfig)
.NET Framework 17.8+	No change	No change	Build warning,  Custom event transferred	No change

Type of breaking change

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code may require source changes to compile successfully.
• Behavioral change: Existing binaries may behave differently at run time.

Reason for change

Unsecure BinaryFormatter is going to be deprected (https://aka.ms/binaryformatter). From NET8 - usages of BinaryFormatter will lead to runtime errors (unless user explicitly opts-in with EnableUnsafeBinaryFormatterSerialization) - and custom derived build events rely on BinaryFormatter - so such a build would fail anyways. Current build error/warning gives more grace information.

The runtime errors do not apply to Full Framework yet - hence the build warning is opt-in for Full Framework. However this will change very soon (current deadline for BinaryFormatter removal is 2023-12-31 - https://liquid.microsoft.com/Web/Object/Read/MS.Security/Requirements/Microsoft.Security.SystemsADM.10010#Zguide), so opting-in and refactoring is strongly recommended.

Recommended action

Proper approach is to move to any of the offered alternative build-in events for extensibility (code links will be provided once PR is merged. Those types should be probably documented with generated documentations similarly as CustomBuildEventArgs as part of this documenting effort):

• ExtendedCustomBuildEventArgs
• ExtendedBuildErrorEventArgs
• ExtendedBuildMessageEventArgs
• ExtendedBuildWarningEventArgs

Alternatively users can temporarily disable the check by explicitly setting env. var MSBUILDCUSTOMBUILDEVENTWARNING to something else then 1.
The warning might be given a MSB code - then another way of suppressing would be usage of MSBuildWarningsAsMessages

Feature area

Other (please put exact area in description textbox)

Affected APIs

https://learn.microsoft.com/en-us/dotnet/api/microsoft.build.framework.custombuildeventargs

---

Associated WorkItem - 156744

[gewarren]

Tagging @ghogen to update the API docs as necessary.