skip to content

SDK Pinning & Solutions

Which SDK and framework a build uses: --list-sdks, global.json version and rollForward, target framework monikers, .slnx solutions and Directory.Build.props. Asked because builds drift per machine.

on this pageshow

explore

questions

6

What is the difference between the .NET SDK and the .NET runtime, and what do dotnet --info, --list-sdks and --list-runtimes show?

level: juniorimportance: must knowfreq 55%

answer

  1. build tools vs run-only
  2. SDK 10.0.4xx, runtime 10.0.x
  3. Microsoft.NETCore.App and Microsoft.AspNetCore.App
  4. feature bands install side by side
  5. dotnet --version honours global.json

basics

~20 s

The .NET SDK is the toolchain (dotnet CLI, MSBuild, compilers, NuGet, templates) used to build apps; the runtime only runs them. dotnet --list-sdks and --list-runtimes print what is installed, and dotnet --info prints both plus the SDK selected for the current folder.

solid answer

~40 s

The **runtime** is what executes an app: `Microsoft.NETCore.App`, plus `Microsoft.AspNetCore.App` for web apps, installed as shared frameworks. The **SDK** is the toolchain behind `dotnet build`, `test` and `publish`: MSBuild, the compilers, NuGet and the templates. Installing an SDK also installs the runtimes of its version, so the 10.0.4xx SDK brings a .NET 10 runtime. SDK versions use **feature bands** (`10.0.1xx`, `10.0.2xx`, `10.0.4xx`) that install side by side, while a newer patch in the same band replaces the older one. `dotnet --list-sdks` and `dotnet --list-runtimes` list installs with their paths, `dotnet --version` prints the SDK that would be used in the current folder (which `global.json` can change), and `dotnet --info` shows that SDK, the installed SDKs and runtimes, and environment details.

code

bash · 9 lines
bash
dotnet --version          # SDK used in this folder (global.json applies)
dotnet --list-sdks        # every installed SDK and its path
dotnet --list-runtimes    # Microsoft.NETCore.App, Microsoft.AspNetCore.App, ...
dotnet --info             # all of the above plus OS, RID, host
dotnet sdk check          # what is out of date per feature band

# CI images: no telemetry, no first-run banner
export DOTNET_CLI_TELEMETRY_OPTOUT=1
export DOTNET_NOLOGO=1

go deeper

for a junior

Recall that the SDK builds and the runtime runs, and that dotnet --list-sdks and --list-runtimes show what is installed.

for a middle

Explain feature bands, why SDKs install side by side, what dotnet --version actually reports, and that a newer SDK builds older target frameworks.

for a senior

Diagnose machine drift: compare dotnet --info across agents, keep runtimes and SDKs out of production images where not needed, and set telemetry and banner variables in CI.

for a principal

Define what a build image and a runtime image contain and how they are patched, so build drift and unpatched runtimes are owned by someone rather than discovered.

## Two different installs .NET ships two kinds of installation, and confusing them is the root of most "works on my machine" build problems: | | SDK | Runtime | |---|---|---| | Purpose | build, test, pack and publish apps | run apps | | Contains | the `dotnet` CLI commands, MSBuild, the C# compiler, NuGet, project templates | shared frameworks such as `Microsoft.NETCore.App` and `Microsoft.AspNetCore.App` | | Version shape | `10.0.4xx`: major, minor, feature band, patch | `10.0.x`: major, minor, patch | | Needed on a server | no, unless you build there | yes, for framework-dependent apps | An SDK installation includes the runtimes of its own version: install the .NET 10 SDK and you also get the .NET 10 runtime and the ASP.NET Core 10 runtime. A server that only runs framework-dependent apps needs just the runtime; a self-contained app needs neither. ## Feature bands The SDK version's third number groups releases into **feature bands**: `10.0.100`-`10.0.199` is the `10.0.1xx` band, `10.0.400`-`10.0.499` the `10.0.4xx` band. A band can bring new MSBuild, NuGet or CLI features, which is why bands install **side by side**, while a patch inside a band replaces the earlier patch of that band. One machine can therefore hold `10.0.1xx` and `10.0.4xx` SDKs at once. ## What the commands show - `dotnet --list-sdks`: every installed SDK version with its folder, for the architecture of the `dotnet` you invoked. - `dotnet --list-runtimes`: every shared framework with its version and folder, such as `Microsoft.NETCore.App 10.0.12` and `Microsoft.AspNetCore.App 10.0.12`. - `dotnet --version`: the version of the SDK that `dotnet` commands **would use in the current directory**. A `global.json` above that directory can select a different SDK than the newest one installed, so this is the first thing to check when two folders build differently. - `dotnet --info`: the selected SDK, the host, all SDKs and runtimes, the OS and RID, and environment variables that affect `dotnet`. It is what you paste into a bug report. - `dotnet sdk check`: the latest available SDK and runtime for each installed feature band, flagging what is out of date. With the .NET 10 host, `--list-sdks` and `--list-runtimes` also accept `--arch` to inspect an install of another architecture. ## Building older targets with a newer SDK The SDK and the target framework are independent. The .NET 10 SDK builds `net8.0` and `net9.0` projects as well as `net10.0`; running or testing them needs the matching runtime. The reverse fails: an older SDK cannot target a newer framework and reports **NETSDK1045** ("The current .NET SDK does not support '...' as a target"). Pinning which SDK a repository uses is the job of `global.json`. ## Telemetry The SDK collects usage telemetry by default in Microsoft builds. Set `DOTNET_CLI_TELEMETRY_OPTOUT` to `1` or `true` to opt out, before installing if you also want the installer's single telemetry event suppressed. `DOTNET_NOLOGO` only hides the first-run banner and does not affect telemetry. CI images usually set both. ## Common mistakes - Installing only a runtime on a build agent and wondering why `dotnet build` is not available. - Reading the runtime version from `--list-runtimes` and assuming it is the SDK version that builds the code. - Assuming the newest SDK always builds the repository when a `global.json` pins another one.

  • Why can dotnet --version print different values in two folders on the same machine?
    It prints the SDK that would be selected for the current directory. A `global.json` in or above one folder can pin an older installed SDK, while the other folder, with no `global.json`, gets the highest installed SDK.
  • Does DOTNET_NOLOGO disable telemetry?
    No. It only hides the welcome and telemetry notice text. Telemetry is turned off with `DOTNET_CLI_TELEMETRY_OPTOUT` set to `1` or `true`.

The SDK is a print shop's workshop with presses and typesetting tools; the runtime is the reader who only needs the finished booklet. You need the workshop to make a booklet, but every reader needs only the booklet and the ability to read it.

  • A production server needs the SDK installed to run a framework-dependent app.
  • The SDK version and the runtime version are always the same number.
  • Installing SDK 10.0.400 removes an installed 10.0.100 SDK.
  • The .NET 10 SDK can only build net10.0 projects.
  • DOTNET_NOLOGO turns off SDK telemetry.
open as a page

How does global.json select the .NET SDK for a repository, and what happens with version 10.0.100 and no rollForward when only 10.0.400 is installed?

level: middleimportance: must knowfreq 50%

basics

~20 s

global.json pins the SDK with sdk.version, and without rollForward the policy is patch: use that version or a later patch in the same feature band. With 10.0.100 requested and only 10.0.400 installed, no 10.0.1xx SDK exists, so SDK resolution fails.

open as a page

How does Directory.Build.props share MSBuild settings across a .NET solution, and why does a nested Directory.Build.props stop inheriting from the parent one?

level: middleimportance: should knowfreq 42%

basics

~20 s

MSBuild automatically imports the first Directory.Build.props it finds walking up from each project's folder, early in evaluation, so common properties live in one place. It stops at that first file, so a nested one must import its parent explicitly to keep inheriting.

open as a page

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%

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.

open as a page

Which global.json rollForward policy suits a team repository, and what do allowPrerelease and the .NET 10 paths, errorMessage and test.runner settings add?

level: seniorimportance: should knowfreq 34%

basics

~10 s

Teams usually pin a version with rollForward latestFeature (newest 10.0 band) or latestPatch (one band); disable demands an exact SDK. The .NET 10 SDK adds paths for repository-local SDKs, errorMessage and test.runner.

open as a page

With the .NET 10 SDK, how do .sln and .slnx solution files differ, and how would you move a 40-project solution to .slnx with dotnet sln migrate?

level: seniorimportance: should knowfreq 32%

basics

~20 s

.sln is the old line-based format full of GUIDs and configuration sections; .slnx is a short XML file listing projects and folders. dotnet sln App.sln migrate writes App.slnx next to the original, after which you switch every reference and delete the .sln.

open as a page