Developers can follow documentation to resolve Platform Compatibility warnings

[jeffhandley]

Original issue description

The Platform Compatibility Analyzer was introduced in .NET 5.0, raising new diagnostics when APIs are referenced that are unsupported on targeted platforms. These diagnostic messages result in build warnings, but there are no corresponding code fixers in place to automatically address the warnings or illustrate how to do so. Instead, developers must turn to the documentation for the analyzer and the CA1416 diagnostic ID to determine how to handle the warnings.

There are multiple ways to handle the warnings, and each of these could be supplied a possible fixer.

1. Guard platform-specific APIs with guard methods
2. Mark call site as platform-specific
3. Assert the call-site with platform check
4. Suppress the warning

When developers encounter warnings from the Platform Compatibility analyzer, they can be uncertain which approach is best for resolving the warnings. To aide them we will collect our own best practices and document how we've decided to use each remediation approach in our own code base.

• Review and document the patterns and practices that are emerging within the runtime code
• Categorize the patterns into scenarios such that we can document refined guidance for when to use each pattern

[jeffhandley]

I talked with @terrajobst about this story and we agreed that we’re not yet to a point where we can confidently define the fixer behaviors. As we have applied more platform annotations throughout the runtime, we’ve been iterating on the patterns and practices we apply. Before we build the fixer, we should:

• Review and document the patterns and practices that are emerging within the runtime code
• Categorize the patterns into scenarios such that we can document refined guidance for when to use each pattern
• Determine if we should implement new SDK features related to assembly-level attributes
• Implement the feature that allows for custom guard methods that assert platform compatibility
• Finish annotating the runtime with the new 6.0 platforms
• Feel comfortable that the annotation/guard method logic fully meets the needs in the runtime repo

Thereafter, we can define which fixes this code fixer would offer in which scenarios, and then implement it.

Based on this status, I’m removing this story from scope for 6.0. But we will meet those preconditions above before 6.0 ships, allowing us to plan the fixer work.