[BinFmt] Facilitate proper documentation of Custom BuildEventArgs deprecation and replacement

[JanKrivanek]

#8917 (comment)

Background

#6215
This subitem is focused on making sure that https://aka.ms/msbuild/eventargs / https://learn.microsoft.com/en-us/dotnet/api/microsoft.build.framework.custombuildeventargs contains information about CustomBuildEventArgs deprecation, reasoning, suggested replacements and possibly planned timelines (for Core and for FullFw)

Suggested approach

Put together the required information (based on #8917), create documentation bug https://github.com/dotnet/docs/issues and cooperate with @ghogen on apropriate planning and execution or directly create proposal PR in the doc repo [internal] https://github.com/MicrosoftDocs/visualstudio-docs-pr

[JanKrivanek]

dotnet/docs#36403

[KalleOlaviNiemitalo]

Can an assembly with custom events be made compatible with both older and newer versions of MSBuild? If not, I guess a package could ship two assemblies and load one of them in UsingTask.

For a logger that consumes such events, the situation seems simpler, as loggers have to be chosen by the caller of MSBuild, which can then choose the version of MSBuild as well… but does this change make older binlog files incompatible?

[JanKrivanek]

@KalleOlaviNiemitalo Good observations and questions. The term 'deprecation' that we use a lot in this context is missleading at the very least. From the language and binary point of view there is no depraction as we commonly know it. Only now engine checks the types of events transmitted and if it encounters unknown event (that therefore relies on BinaryFormatter serialization) a warning is issued. So full backwards compatibility should be guaranteed.

You however have a very good point of forward compatibility - the newly introduced events won't get transfered by the older versions of engine - looking into that...

[JanKrivanek]

@KalleOlaviNiemitalo Forward compatibility will not be guaranteed here. Assemblies should be compiled against the oldest MSBuild they intend to support.
For Full Framework the build warnings are explicit opt-in - so it shouldn't cause unexpected degradations.
For Core we haven't detected any usage of concerns internaly or in the wild - so hopefully this should be 'just fine'. There still will be an option to override the warning/error/crashing behavior temporarily before facilitating the proper resolution (onboard onto the new custom events).

[slang25]

@KirillOsenkov does this effect StructuredLogger?

[JanKrivanek]

@slang25 No events have been removed - so old logs will be still possible to open with new BinlogViewers without any issues
New events have been introduced - so version check needs to be employed and new version of BinlogViewer will need to be used - @rokonec - have you increased the FileFormat and facilitated the BinlogViewer change?

[rokonec]

There were no reason to increase FileFormat because file format has not been changed at all.
This will be addressed in #9091