For .NET 5 Obsoletions - use partial ref source classes instead of ifdefs

[jeffhandley]

In #39269, we had heavy use of #ifdef statements in the ref source files. This will make the ref source generator harder to re-run for those assemblies.

Instead, we should use sidecar source files and utilize the partial classes to maintain all of the conditional obsoletions. That file can then be conditionally compiled based on the target framework.

[jeffhandley]

Unfortunately, enums and members being marked as conditionally obsolete cannot be handled by partials. (For members, we'd have to mark both sides as partial). That means this approach ends up splitting the conditional obsoletions across the regular ref source file and the partial ref source file. There’s only one ref source file afflicted by this and it’s System.Security.Permissions. I'm not sure this is a good tradeoff since it's not a complete solution.

I'd love to get the opinion of @bartonjs and (@Anipik or @ViktorHofer) on this. Would this be helpful? I created a draft PR on my fork jeffhandley/runtime#5 that shows the (compiling, but unverified) result.

[ViktorHofer]

We plan to consolidate the ref and source projects hopefully later this year (after product work is completed) and genearte the reference source file automatically when building the project. The idea is to:

1. Use Roslyn's ReferenceAssembly feature to generate the reference assembly
2. Use the new ApiCompat tool that @safern is working on to compare the implementation assemblies with the generated reference assembly.
3. Use another tool (which doesn't exist yet) to generate the reference source file (i.e. System.Runtime.cs) and check it into the source tree next to the project file to make it obvious when APIs change (for PR purposes and to have history on API changes per project). That file isn't required for building the project at all and should be considered as a helper file.

As the tooling for 3 isn't defined yet I would mimic what we already have with GenAPI: https://github.com/dotnet/arcade/blob/8f38c4b47fa7d6c3cee96df03c3fc1ce2e77d68e/src/Microsoft.DotNet.GenAPI/build/Microsoft.DotNet.GenAPI.targets#L32. How does GenAPI today represent APIs for different TFMs? I assume via ifdefs?

[safern]

How does GenAPI today represent APIs for different TFMs? I assume via ifdefs?

Unfortunately since GenAPI generates source from metadata and it doesn't do a diff in between different TFMs it can't express ifdefs. It basically just generates source based on the settings it get's passed down to.

[ViktorHofer]

Ah that's not great to hear but if we will invest in new tooling anyway it might not matter much. What would an ideal solution look like? I assume ifdefs would just be fine?

[jeffhandley]

Would it be either #ifdef or generate separate source for each target (with no #ifdef logic required then)?

This upcoming effort makes me feel even less inclined to move this specific issue forward though. Would either of you have any objections to closing this as won't fix?

[ViktorHofer]

This upcoming effort makes me feel even less inclined to move this specific issue forward though. Would either of you have any objections to closing this as won't fix?

I agree that based on the automation that we want to implement, this issue might not be useful to invest time on.