skip to content

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%

answer

  1. searched upward from the working directory
  2. sdk.version needs a full version
  3. no rollForward means patch
  4. patch stays inside the feature band
  5. no global.json: highest SDK installed

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.

solid answer

~40 s

The `dotnet` host looks for `global.json` from the current directory upward (the MSBuild SDK resolver starts at the solution or project folder). Without one, it uses the **highest installed SDK**. With `"sdk": { "version": "10.0.100" }` and no `rollForward`, the default policy is **`patch`**: the exact version, else the latest patch of the same major, minor and feature band, else failure. `10.0.400` is a different feature band, so a machine with only that SDK cannot satisfy the file and the command errors instead of building. `version` must be a full version (`10.0` is invalid) and takes no wildcards. The usual team setting is a version plus `"rollForward": "latestFeature"`, which accepts any newer 10.0 band. `dotnet new globaljson --sdk-version 10.0.100 --roll-forward latestFeature` writes the file.

code

json · 5 lines
json
{
  "sdk": {
    "version": "10.0.100"
  }
}

go deeper

for a junior

Recall that global.json at the repository root pins the SDK version, and that without it the newest installed SDK is used.

for a middle

Explain the upward search, the default patch policy and why it stays inside one feature band, and that version needs a full SDK number.

for a senior

Diagnose SDK resolution failures on agents, choose a rollForward that tolerates new bands, and verify with dotnet --version from the repository root.

for a principal

Set the organisation's pinning stance: how strict global.json is per repository, how agent images track feature bands, and who moves the pin.

## What global.json is for By default the `dotnet` command uses the **highest SDK installed** on the machine. That means a developer who installs a new SDK silently changes the MSBuild, NuGet and compiler versions that build the repository. A `global.json` file at the repository root pins which SDK is used, so the build is the same on every machine and agent. ## How the file is found Two components look for it, each searching **up through parent directories**: - The **`dotnet` host** (the muxer) handles CLI commands and starts from the **current working directory**. - The **MSBuild project SDK resolver**, used during builds, starts from the directory of the solution file if there is one, otherwise the project file, otherwise the working directory. The first `global.json` found wins. Running commands from a folder outside the repository therefore ignores the repository's file, a common surprise in CI scripts that `cd` elsewhere. ## The sdk section ```json { "sdk": { "version": "10.0.100", "rollForward": "latestFeature" } } ``` - `version` must be a **full SDK version** like `10.0.100`. `10`, `10.0` or `10.0.x` are invalid, and there are no wildcards or ranges. - `rollForward` says what may be used instead when that exact version is missing, or whether a later one is preferred. - `allowPrerelease` controls whether preview SDKs count; outside Visual Studio it defaults to `true`. Comments are allowed in the file. ## The matching rules 1. **No `global.json`**, or one without a version: the highest installed SDK is used (as if `rollForward` were `latestMajor`). 2. **A version and no `rollForward`**: the policy is **`patch`**. Use the exact version; if missing, roll forward to the latest installed **patch in the same feature band**; if none, **fail**. 3. **A version and a `rollForward`**: apply that policy. ## The worked case The file says `10.0.100` and nothing else, and the machine has only `10.0.400`. Under `patch`, the acceptable SDKs are `10.0.100`-`10.0.199`. `10.0.400` is in the `10.0.4xx` feature band, so it is not acceptable, and every `dotnet build`, `dotnet --version` or `dotnet test` in that tree fails with an SDK resolution error naming the requested version. Developers often expect "10.0.100 or newer"; that is what `latestFeature` (or `feature`) gives, not the default. Fixes, in order of preference: - Add `"rollForward": "latestFeature"` so any installed `10.0.x` SDK at or above `10.0.100` qualifies. - Bump `version` to the band the team actually uses, such as `10.0.400`. - Install a `10.0.1xx` SDK on the machine. ## Creating the file `dotnet new globaljson --sdk-version 10.0.400 --roll-forward latestFeature` writes it in the current folder. `dotnet --version` run from inside the repository then shows which SDK the rules picked, which is the quickest way to verify the file works. ## Common mistakes - Writing `"version": "10.0"` and getting an invalid-version error. - Expecting `global.json` to change the runtime an app runs on; it selects the SDK only, and the target framework is set in the project. - Committing a pin to an SDK patch that build agents do not have, with the default policy, and breaking CI. ## How CI images interact with the pin Hosted and self-built agent images usually carry one or two SDKs, often the newest band of each supported major. A repository pinned with the default `patch` policy to a band the image lacks fails on the first command. Either the pipeline installs the pinned SDK before building (an install step that reads `global.json`), or the file uses a policy such as `latestFeature` that accepts what the image has. Choosing between them is a trade-off between exact reproducibility and tolerance for image updates.

  • Why does a build behave differently when a script runs dotnet from /tmp with a project path?
    The host searches for `global.json` upward from the current working directory, so from `/tmp` it never sees the repository's file and picks the highest installed SDK. Running from inside the repository, or pointing at it with a solution path the resolver can start from, restores the pinned behaviour.
  • Does global.json control the runtime version an app uses?
    No. It only selects the SDK that runs the CLI commands. The runtime an app needs comes from its target framework and runtime configuration.

  • With version 10.0.100 and no rollForward, any newer 10.0 SDK is used.
  • "version": "10.0" pins the latest 10.0 SDK.
  • global.json selects the runtime the app runs on in production.
  • The SDK only reads global.json from the folder that holds the project file.
  • Without global.json the oldest installed SDK is used for safety.