Description
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):
ExtendedCustomBuildEventArgsExtendedBuildErrorEventArgsExtendedBuildMessageEventArgsExtendedBuildWarningEventArgs
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