Skip to content

Update cross-platform targeting guidance to prioritize modern .NET over netstandard2.0 #48052

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from

Conversation

Copilot
Copy link
Contributor

@Copilot Copilot AI commented Aug 20, 2025

This PR updates the cross-platform targeting guidance to reflect current best practices by recommending modern .NET versions (net6.0+) as the starting point for new libraries instead of netstandard2.0.

Background

The current documentation suggests starting with netstandard2.0 as the default for cross-platform targeting. However, as noted in the issue, this advice is outdated and may inadvertently:

  1. Discourage the use of modern .NET idioms
  2. Block adoption of AOT/trimming related technologies
  3. Confuse cross-platform compatibility needs with breadth targeting requirements

Changes Made

Primary recommendation updated: Changed from "DO start with including a netstandard2.0 target" to "DO start with including a net6.0 target or later for new libraries."

Added conceptual clarity: Introduced a distinction between:

  • Cross-platform compatibility: Working across different operating systems (Windows, Linux, macOS)
  • Breadth targeting: Supporting a wide range of .NET implementations and versions

Repositioned netstandard2.0: Changed to "CONSIDER including a netstandard2.0 target if you need broad compatibility or .NET Framework support" - positioning it as a specific-use case rather than the default.

Updated examples: The multi-targeting project file example now shows net6.0;netstandard2.0 instead of netstandard2.0;net462 to reflect modern practices.

Impact

The updated guidance encourages developers to:

  • Start with modern .NET versions that provide access to latest APIs and performance improvements
  • Enable features like AOT and trimming by default
  • Only target netstandard2.0 when there's a specific need for .NET Framework support or maximum compatibility

This aligns with the ecosystem-wide push toward modern .NET while still providing clear guidance on when older targets are appropriate.

Fixes #47458.


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.


Internal previews

📄 File 🔗 Preview link
docs/standard/library-guidance/cross-platform-targeting.md Cross-platform targeting

@Copilot Copilot AI changed the title [WIP] Should we reconsider our default suggestions for netstandard2.0? Update cross-platform targeting guidance to prioritize modern .NET over netstandard2.0 Aug 20, 2025
@Copilot Copilot AI requested a review from gewarren August 20, 2025 23:57
Copilot finished work on behalf of gewarren August 20, 2025 23:57
@gewarren gewarren marked this pull request as ready for review August 21, 2025 01:32
@gewarren gewarren requested review from JamesNK, IEvangelist and a team as code owners August 21, 2025 01:32
@gewarren gewarren requested a review from richlander August 21, 2025 01:32
@@ -27,13 +34,13 @@ If your project targets .NET or .NET Standard and compiles successfully, it does
> [!TIP]
> The .NET team offers a [Platform compatibility analyzer](../analyzers/platform-compat-analyzer.md) to help you discover possible issues.

✔️ DO start with including a `netstandard2.0` target.
✔️ DO start with including a `net6.0` target or later for new libraries.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
✔️ DO start with including a `net6.0` target or later for new libraries.
✔️ DO start with including a `net8.0` target or later for new libraries.

let's use the oldest in support version as a baseline here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Should we reconsider our default suggestions for netstandard2.0?
3 participants