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