skip to content

In a .NET library project, what changes between targeting netstandard2.0, net10.0 and net10.0-windows, and how do OperatingSystem.IsWindows() and CA1416 guard Windows-only calls?

level: middleimportance: should knowfreq 38%

answer

  1. a TFM is an API contract
  2. reach versus newer APIs
  3. OS suffix marks the assembly
  4. annotated APIs, guarded call sites

basics

~20 s

The target framework fixes the API surface you compile against: netstandard2.0 also reaches .NET Framework but lacks newer APIs, net10.0 exposes the full cross-platform library, and net10.0-windows marks the assembly Windows-only. CA1416 flags platform-specific calls unless guarded by OperatingSystem.IsWindows().

solid answer

~40 s

A target framework moniker (TFM) chooses the reference assemblies the compiler sees. `netstandard2.0` is the shared surface of .NET Framework and modern .NET, so it lacks APIs such as `Convert.ToHexString` and `OperatingSystem.IsWindows()` (error CS0117). `net10.0` exposes the whole .NET 10 library, including Windows-only APIs such as `Microsoft.Win32.Registry`, which are annotated `[SupportedOSPlatform("windows")]`. Analyzer CA1416 then warns at any call site reachable on other platforms, unless it sits behind a guard such as `if (OperatingSystem.IsWindows())` or inside a member that is itself annotated. `net10.0-windows` makes the SDK inject an assembly-level `[SupportedOSPlatform("Windows7.0")]`, so the whole assembly counts as Windows-only and those calls stop warning, but non-Windows consumers can no longer use it. A library often multi-targets `netstandard2.0;net10.0` and uses `#if NET` around newer APIs.

code

xml · 5 lines
xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>netstandard2.0;net10.0</TargetFrameworks>
  </PropertyGroup>
</Project>

go deeper

for a junior

Know that the TFM decides which APIs compile, that netstandard2.0 is for sharing with .NET Framework, and that net10.0-windows means Windows-only.

for a middle

Explain multi-targeting with #if NET, how CA1416 reads SupportedOSPlatform annotations, and which guards silence it.

for a senior

Decide between guarded calls in net10.0 and a separate -windows build, annotate your own helpers, and keep netstandard2.0 fallbacks from drifting.

for a principal

Set the supported-consumer policy that drives TFMs, retire netstandard2.0 when the last .NET Framework consumer goes, and make CA1416 an error.

## A target framework is an API contract Every SDK-style project sets `TargetFramework` (or the plural `TargetFrameworks`) to a **target framework moniker (TFM)**. The TFM decides which **reference assemblies** the compiler compiles against, which NuGet assets are chosen, and which **preprocessor symbols** are defined. It does not pick the runtime your code runs on; it states the API surface you promise to need. | TFM | Who can consume it | API surface | Typical use | |---|---|---|---| | `netstandard2.0` | .NET Framework and every modern .NET | The shared .NET Standard 2.0 set | Libraries that must still serve .NET Framework | | `net10.0` | .NET 10 and later apps on any OS | Full .NET 10 library, including annotated OS-specific APIs | Cross-platform libraries and apps | | `net10.0-windows` | .NET 10 and later apps on Windows | Same as `net10.0`, assembly marked Windows-only | Windows-specific libraries; WinForms and WPF also set `UseWindowsForms` or `UseWPF` | The docs point to `netstandard2.0` for sharing code between .NET Framework and other .NET implementations, and suggest skipping .NET Standard 2.1 in favour of a .NET TFM when .NET Framework is not needed. The C# language version each TFM gets by default is a separate rule, covered with language versions. ## Multi-targeting A library can build once per TFM with `<TargetFrameworks>netstandard2.0;net10.0</TargetFrameworks>`. NuGet then gives each consumer the closest compatible build. Inside the code: - The SDK defines a symbol per TFM, formed by upper-casing and replacing dots and hyphens with underscores, for example `NETSTANDARD2_0` and `NET10_0`, plus `NET` for any .NET 5+ target and `_OR_GREATER` variants such as `NET8_0_OR_GREATER`. - Code that uses newer APIs goes inside `#if NET`; the `netstandard2.0` build gets a fallback. Calling `OperatingSystem.IsWindows()` without the `#if` fails the `netstandard2.0` build with **CS0117** ("'OperatingSystem' does not contain a definition for 'IsWindows'"). ## OS-specific TFMs Appending an OS name, as in `net10.0-windows`, keeps the same base library but tells the SDK the assembly targets that platform. The SDK injects an assembly attribute; on the .NET 10 SDK the generated file contains `[assembly: System.Runtime.Versioning.SupportedOSPlatformAttribute("Windows7.0")]`. Everything in the assembly is then treated as Windows-only, so calls to Windows-only APIs do not warn. The flip side: a plain `net10.0` project cannot consume that build at all, on any operating system. The CA1416 docs also note that if `GenerateAssemblyInfo` is `false`, the attribute is not injected and the warnings come back. ## Platform annotations and CA1416 Since .NET 5, OS-specific APIs carry **`[SupportedOSPlatform]`** or **`[UnsupportedOSPlatform]`** attributes from `System.Runtime.Versioning`. The **platform compatibility analyzer, CA1416** ("Validate platform compatibility"), reads them at build time: - An unannotated API is assumed to work everywhere. - A call to an API marked `[SupportedOSPlatform("windows")]` from code reachable on other platforms warns: "This call site is reachable on all platforms. 'Registry.CurrentUser' is only supported on: 'windows'." - Wrapping the call in `if (OperatingSystem.IsWindows())`, or a version check such as `OperatingSystem.IsWindowsVersionAtLeast(10)`, tells the analyzer the call is guarded. - Annotating your own member with `[SupportedOSPlatform("windows")]` moves the obligation to its callers; `[SupportedOSPlatformGuard("windows")]` marks a custom guard property or method. - CA1416 runs inside the compiler. Nothing checks at run time; an unguarded call simply executes the Windows-only API on whatever OS the process runs on. The .NET 10 docs list CA1416 as enabled by default as a warning for projects targeting .NET 5 or later. ## What the smaller surface costs Targeting `netstandard2.0` is not free reach. Newer types either do not exist there or arrive as packages: `TimeProvider`, for example, comes from the Microsoft.Bcl.TimeProvider package on .NET Standard 2.0, while .NET 8 and later have it built in. Every such package is an extra dependency your consumers inherit, and each `#if NET` block is a second code path that needs tests on both builds. That cost is the reason to drop `netstandard2.0` once no .NET Framework consumer remains. ## Choosing a target 1. Start from consumers: if any still run .NET Framework, include `netstandard2.0`; otherwise use `net10.0` alone, or the oldest .NET version you support. 2. Add `net10.0` beside `netstandard2.0` when modern consumers benefit from newer APIs, and keep the differences inside `#if NET` blocks. 3. Prefer `net10.0` with guarded calls for code that is mostly cross-platform with a Windows extra, such as reading an export folder from the registry or falling back to an environment variable. 4. Use `net10.0-windows` only when the assembly is Windows-only in substance; consider promoting CA1416 to an error so unguarded calls cannot ship.

  • How do you mark your own helper as Windows-only so its callers are checked too?
    Put `[SupportedOSPlatform("windows")]` on the method or type. Calls inside it to other Windows-only APIs stop warning, and every caller now needs a guard such as `OperatingSystem.IsWindows()` or its own annotation. For a reusable guard, such as a cached `IsWindowsHost` property, mark it `[SupportedOSPlatformGuard("windows")]` so the analyzer trusts it.
  • When should a library that targets netstandard2.0 add net10.0 as a second target?
    When modern consumers gain from APIs that .NET Standard lacks, such as `OperatingSystem`, `Convert.ToHexString` or newer span-based overloads, or when you want to drop polyfill packages for them. NuGet gives each consumer the closest build, and `#if NET` keeps the two code paths in one file.
  • Why might CA1416 warnings appear in a net10.0-windows project?
    The analyzer relies on the assembly-level `[SupportedOSPlatform]` attribute that the SDK writes into the generated assembly info. If `GenerateAssemblyInfo` is set to `false`, that attribute is missing and Windows-only calls warn again; re-enable generation or add the attribute yourself.

  • You must target net10.0-windows to call any Windows API from .NET 10.
  • OperatingSystem.IsWindows() is available when targeting netstandard2.0.
  • CA1416 is checked at run time and throws when the OS does not match.
  • A library that targets only net10.0 can still be referenced from .NET Framework 4.8.
  • Adding -windows to the TFM automatically brings in WinForms and WPF.

Assumes the .NET 10 SDK; OS-specific TFMs, OperatingSystem.IsWindows() and the platform compatibility analyzer date from .NET 5, so net8.0 and net9.0 projects behave the same way.