skip to content

In an SDK-style .NET project, what is the difference between TargetFramework and TargetFrameworks, and how do the dotnet commands handle a multi-targeted project?

level: middleimportance: should knowfreq 45%

answer

  1. TFMs: net8.0, net10.0, net10.0-windows
  2. plural is ignored when singular is set
  3. one inner build per framework
  4. -f / --framework picks one
  5. NET10_0_OR_GREATER symbols

basics

~20 s

TargetFramework names the single framework a project builds for, such as net10.0; TargetFrameworks lists several, such as net8.0;net10.0, and the SDK builds once per framework. dotnet build and test cover every framework, while dotnet run needs -f to choose one.

solid answer

~40 s

A **target framework moniker** (TFM) like `net10.0`, `net8.0` or `net10.0-windows` says which APIs a build compiles against. `<TargetFramework>net10.0</TargetFramework>` builds once. `<TargetFrameworks>net8.0;net10.0</TargetFrameworks>` makes an outer build that runs one inner build per TFM, with output in `bin/<Configuration>/net8.0/` and `bin/<Configuration>/net10.0/`; if the singular property is also set, the plural one is ignored. `dotnet build`, `test` and `pack` process every framework; `-f net10.0` limits them to one. `dotnet run` has to start a single app, so it asks for `--framework` (the 10.0.4xx SDK prompts in an interactive terminal). Each inner build defines symbols such as `NET10_0_OR_GREATER` for `#if`, and conditions on `$(TargetFramework)` vary references per framework. The SDK must know the newest TFM, or it fails with NETSDK1045.

code

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

  <ItemGroup Condition="'$(TargetFramework)' == 'net8.0'">
    <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.0" />
  </ItemGroup>
  <ItemGroup Condition="'$(TargetFramework)' == 'net10.0'">
    <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.0" />
  </ItemGroup>
</Project>

go deeper

for a junior

Recall that TargetFramework sets the .NET version a project builds for, such as net10.0, and that TargetFrameworks lists several.

for a middle

Explain the outer and inner builds, per-framework output folders, -f, why dotnet run needs one framework, and the precedence of the singular property.

for a senior

Use multi-targeting where it pays (libraries), guard code with OR_GREATER symbols and compatibility checks, and recognise NETSDK1045 and props-file overrides when builds go wrong.

for a principal

Decide a framework support policy for shared libraries: which TFMs to carry, when to drop one, and what that costs every consumer's build and test matrix.

## Target framework monikers Every SDK-style project declares which .NET it targets with a **target framework moniker (TFM)**: - `net10.0`, `net9.0`, `net8.0`: .NET 10, 9 and 8. - `net10.0-windows`, `net10.0-android` and similar: OS-specific TFMs that add that platform's APIs on top of the base TFM. - `netstandard2.0`, `net472`: .NET Standard and .NET Framework, mostly for libraries that must reach older platforms. The TFM decides which reference assemblies the compiler sees and which runtime the app needs. It is independent of the SDK version: the .NET 10 SDK builds a `net8.0` project as well as a `net10.0` one. ## Singular vs plural | Property | Example | Result | |---|---|---| | `TargetFramework` | `<TargetFramework>net10.0</TargetFramework>` | one build, output in `bin/Debug/net10.0/` | | `TargetFrameworks` | `<TargetFrameworks>net8.0;net10.0</TargetFrameworks>` | an outer build plus one inner build per TFM, one output folder each | If a project sets **both**, `TargetFramework` (singular) wins and `TargetFrameworks` is **ignored**: the project silently builds for one framework. This happens when a shared `Directory.Build.props` sets the singular property for every project and one library tries to multi-target. ## How the commands behave 1. `dotnet build` and `dotnet test` run every target framework; test results are reported per framework. 2. `dotnet pack` puts each framework's assembly into its own `lib/<tfm>/` folder of one package. 3. `-f net10.0` (`--framework`) restricts build, test or publish to one TFM. 4. `dotnet run` must start one process, so a multi-targeted app needs `--framework`. With the 10.0.4xx SDK an interactive terminal shows a selection prompt; non-interactive runs fail with a message listing the frameworks and an example `dotnet run --framework ...` line. 5. `dotnet publish` of a multi-targeted app is normally run with `-f` as well, since a deployment targets one runtime. ## Varying code and references per framework Each inner build defines **preprocessor symbols** for its TFM, including `NET10_0` and `..._OR_GREATER` symbols for every compatible version, so `#if NET10_0_OR_GREATER` guards code that uses newer APIs. In the project file, conditions on `$(TargetFramework)` add references only where needed: - `<ItemGroup Condition="'$(TargetFramework)' == 'net8.0'">` to reference the 8.0 line of a `Microsoft.Extensions.*` package for the older target and the 10.0 line for the newer one. - `$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net10.0'))` for a version-range test instead of string equality. ## When an SDK is too old An SDK knows the TFMs up to its own version. Building `net10.0` with a .NET 8 SDK fails with **NETSDK1045** ("The current .NET SDK does not support 'newer version' as a target"). The fix is a newer SDK, usually pinned through `global.json`, not a change to the project. ## When to multi-target Libraries consumed by apps on different .NET versions multi-target so each consumer gets the best build. Applications rarely need it: an app ships on one runtime, and multi-targeting it doubles build and test time for little benefit. Moving an application from one TFM to the next is an upgrade task in its own right. ## Output layout and packaging Each inner build writes its own folder (`bin/Release/net8.0/`, `bin/Release/net10.0/`), and a `dotnet pack` of a multi-targeted library places each build under `lib/<tfm>/` of a single package, so a consumer's restore picks the nearest compatible framework. Tests run once per framework, which is the point: an API that behaves differently on .NET 8 and .NET 10 is caught before a consumer finds it.

  • Why would a multi-targeted library suddenly build only one framework?
    Because `TargetFramework` is set somewhere, often in a `Directory.Build.props` shared by every project. When the singular property has a value the plural one is ignored, so the project quietly becomes single-target. Remove the singular setting for that project or set it only where projects do not multi-target.
  • Can a .NET 10 SDK build a net8.0 project, and what does it need to test it?
    Yes, a newer SDK builds older .NET TFMs. Running or testing the result needs a .NET 8 runtime installed, because the test host executes the net8.0 build on the runtime it targets.

  • Setting both TargetFramework and TargetFrameworks builds the union of both.
  • dotnet run on a multi-targeted app runs every framework in turn.
  • The TFM must match the SDK version, so net8.0 needs an 8.0 SDK.
  • #if NET10_0 also matches code compiled for later .NET versions.
  • Applications should multi-target by default to be future-proof.