From 434b58e2207a13ae37752e9bd3e110d0c21ce4c7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 20 Aug 2025 23:46:29 +0000 Subject: [PATCH 1/4] Initial plan From c3f31c33d585b62d78077151bf11b6f879057799 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 20 Aug 2025 23:55:25 +0000 Subject: [PATCH 2/4] Update cross-platform targeting guidance to prioritize modern .NET over netstandard2.0 Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- .../cross-platform-targeting.md | 25 ++++++++++++------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/docs/standard/library-guidance/cross-platform-targeting.md b/docs/standard/library-guidance/cross-platform-targeting.md index 171b1bc517174..6166e5831bec1 100644 --- a/docs/standard/library-guidance/cross-platform-targeting.md +++ b/docs/standard/library-guidance/cross-platform-targeting.md @@ -1,19 +1,26 @@ --- title: Cross-platform targeting for .NET libraries description: Best practice recommendations for creating cross-platform .NET libraries. -ms.date: 11/11/2024 +ms.date: 01/28/2025 --- # Cross-platform targeting Modern .NET supports multiple operating systems and devices. It's important for .NET open-source libraries to support as many developers as possible, whether they're building an ASP.NET website hosted in Azure, or a .NET game in Unity. +When choosing target frameworks for your library, it's important to distinguish between two different goals: + +- **Cross-platform compatibility**: Your library works on different operating systems (Windows, Linux, macOS). Modern .NET versions like .NET 6+ provide excellent cross-platform support. +- **Breadth targeting**: Your library supports a wide range of .NET implementations and versions to maximize compatibility across different user scenarios. + +These goals don't always require the same approach. If your target applications all use modern .NET, your libraries can target the same modern .NET versions without needing to target older frameworks. + ## .NET and .NET Standard targets .NET and .NET Standard targets are the best way to add cross-platform support to a .NET library. * [.NET Standard](../net-standard.md) is a specification of .NET APIs that are available on all .NET implementations. Targeting .NET Standard lets you produce libraries that are constrained to use APIs that are in a given version of .NET Standard, which means it's usable by all platforms that implement that version of .NET Standard. -* .NET 6-8 are implementations of .NET. Each version is a single product with a uniform set of capabilities and APIs that can be used for Windows desktop apps and cross-platform console apps, cloud services, and websites. +* .NET 6-9 are implementations of .NET. Each version is a single product with a uniform set of capabilities and APIs that can be used for Windows desktop apps and cross-platform console apps, cloud services, and websites. For more information about how .NET compares to .NET Standard, see [.NET 5 and .NET Standard](../net-standard.md#net-5-and-net-standard). @@ -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. -> Most general-purpose libraries don't need APIs outside of .NET Standard 2.0. .NET Standard 2.0 is supported by all modern platforms and is the recommended way to support multiple platforms with one target. If you don't need to support .NET Framework, you could also target .NET Standard 2.1. +> For new libraries, targeting modern .NET (such as .NET 6 or later) provides access to the latest APIs, performance improvements, and enables features like AOT and trimming. Modern .NET versions are cross-platform and provide excellent compatibility across Windows, Linux, and macOS. -✔️ DO include a `net6.0` target or later if you require new APIs introduced in a modern .NET. +✔️ CONSIDER including a `netstandard2.0` target if you need broad compatibility or .NET Framework support. -> .NET 6 and later apps can use a `netstandard2.0` target, so `net6.0` isn't required. You should explicitly target `net6.0`, `net7.0`, `net8.0`, or `net9.0` when you want to use newer .NET APIs. +> .NET Standard 2.0 is supported by .NET Framework 4.6.1+ and all modern .NET implementations. Include this target when you need to support .NET Framework applications or when building libraries for maximum compatibility across different .NET ecosystems. ❌ AVOID including a `netstandard1.x` target. @@ -104,7 +111,7 @@ public static class GpsLocation > The .NET Standard assembly will automatically be used by NuGet. Targeting individual .NET implementations increases the `*.nupkg` size for no benefit. -✔️ CONSIDER adding a target for `net462` when you're offering a `netstandard2.0` target. +✔️ CONSIDER adding a target for `net462` when you're also targeting `netstandard2.0` and need to support older .NET Framework applications. > Using .NET Standard 2.0 from .NET Framework has some issues that were addressed in .NET Framework 4.7.2. You can improve the experience for developers that are still on .NET Framework 4.6.2 - 4.7.1 by offering them a binary that's built for .NET Framework 4.6.2. @@ -117,8 +124,8 @@ public static class GpsLocation ```xml - - netstandard2.0;net462 + + net6.0;netstandard2.0 ``` From 7da78aa21f6817140a8624926f94e04d74ea466c Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 20 Aug 2025 18:31:45 -0700 Subject: [PATCH 3/4] human edits --- .../library-guidance/cross-platform-targeting.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/standard/library-guidance/cross-platform-targeting.md b/docs/standard/library-guidance/cross-platform-targeting.md index 6166e5831bec1..68c1b8babefd5 100644 --- a/docs/standard/library-guidance/cross-platform-targeting.md +++ b/docs/standard/library-guidance/cross-platform-targeting.md @@ -1,7 +1,7 @@ --- title: Cross-platform targeting for .NET libraries description: Best practice recommendations for creating cross-platform .NET libraries. -ms.date: 01/28/2025 +ms.date: 08/20/2025 --- # Cross-platform targeting @@ -10,7 +10,7 @@ Modern .NET supports multiple operating systems and devices. It's important for When choosing target frameworks for your library, it's important to distinguish between two different goals: -- **Cross-platform compatibility**: Your library works on different operating systems (Windows, Linux, macOS). Modern .NET versions like .NET 6+ provide excellent cross-platform support. +- **Cross-platform compatibility**: Your library works on different operating systems (Windows, Linux, macOS). Modern .NET versions like .NET 8+ provide excellent cross-platform support. - **Breadth targeting**: Your library supports a wide range of .NET implementations and versions to maximize compatibility across different user scenarios. These goals don't always require the same approach. If your target applications all use modern .NET, your libraries can target the same modern .NET versions without needing to target older frameworks. @@ -19,8 +19,8 @@ These goals don't always require the same approach. If your target applications .NET and .NET Standard targets are the best way to add cross-platform support to a .NET library. +* .NET versions 5 through 10 are implementations of .NET. Each version is a single product with a uniform set of capabilities and APIs that can be used for Windows desktop apps and cross-platform console apps, cloud services, and websites. * [.NET Standard](../net-standard.md) is a specification of .NET APIs that are available on all .NET implementations. Targeting .NET Standard lets you produce libraries that are constrained to use APIs that are in a given version of .NET Standard, which means it's usable by all platforms that implement that version of .NET Standard. -* .NET 6-9 are implementations of .NET. Each version is a single product with a uniform set of capabilities and APIs that can be used for Windows desktop apps and cross-platform console apps, cloud services, and websites. For more information about how .NET compares to .NET Standard, see [.NET 5 and .NET Standard](../net-standard.md#net-5-and-net-standard). @@ -34,9 +34,9 @@ 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 `net6.0` target or later for new libraries. +✔️ DO start with including a `net8.0` target or later for new libraries. -> For new libraries, targeting modern .NET (such as .NET 6 or later) provides access to the latest APIs, performance improvements, and enables features like AOT and trimming. Modern .NET versions are cross-platform and provide excellent compatibility across Windows, Linux, and macOS. +> For new libraries, targeting modern .NET (such as .NET 8 or later) provides access to the latest APIs and performance improvements, and enables features like AOT and trimming. Modern .NET versions are cross-platform and provide excellent compatibility across Windows, Linux, and macOS. ✔️ CONSIDER including a `netstandard2.0` target if you need broad compatibility or .NET Framework support. @@ -111,7 +111,7 @@ public static class GpsLocation > The .NET Standard assembly will automatically be used by NuGet. Targeting individual .NET implementations increases the `*.nupkg` size for no benefit. -✔️ CONSIDER adding a target for `net462` when you're also targeting `netstandard2.0` and need to support older .NET Framework applications. +✔️ CONSIDER adding a target for `net462` when you're also targeting `netstandard2.0`. > Using .NET Standard 2.0 from .NET Framework has some issues that were addressed in .NET Framework 4.7.2. You can improve the experience for developers that are still on .NET Framework 4.6.2 - 4.7.1 by offering them a binary that's built for .NET Framework 4.6.2. @@ -124,8 +124,8 @@ public static class GpsLocation ```xml - - net6.0;netstandard2.0 + + net8.0;netstandard2.0 ``` From d6f4f11b080dd386c802ab486f356d78b1f3c800 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 20 Aug 2025 19:26:30 -0700 Subject: [PATCH 4/4] Update docs/standard/library-guidance/cross-platform-targeting.md Co-authored-by: Chet Husk --- docs/standard/library-guidance/cross-platform-targeting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standard/library-guidance/cross-platform-targeting.md b/docs/standard/library-guidance/cross-platform-targeting.md index 68c1b8babefd5..f73fd18a53bd7 100644 --- a/docs/standard/library-guidance/cross-platform-targeting.md +++ b/docs/standard/library-guidance/cross-platform-targeting.md @@ -10,7 +10,7 @@ Modern .NET supports multiple operating systems and devices. It's important for When choosing target frameworks for your library, it's important to distinguish between two different goals: -- **Cross-platform compatibility**: Your library works on different operating systems (Windows, Linux, macOS). Modern .NET versions like .NET 8+ provide excellent cross-platform support. +- **Modern APIs and patterns**: Your library leans into the benefits of the recent versions of the .NET platform. You use modern language patterns and support advanced deployment models like Native Ahead-of-Time compilation on the CoreCLR. - **Breadth targeting**: Your library supports a wide range of .NET implementations and versions to maximize compatibility across different user scenarios. These goals don't always require the same approach. If your target applications all use modern .NET, your libraries can target the same modern .NET versions without needing to target older frameworks.