How does the .NET SDK decide which SDK version to use, and how does global.json change that?

1. Three pieces: host, hostfxr and the SDK

When you type dotnet build, three separate components are involved:

Only one muxer runs: the first dotnet found on the PATH. hostfxr then looks for SDKs in the sdk folder next to that muxer, so a second installation elsewhere on the machine is invisible to it. From .NET 10, global.json can also name extra SDK locations (see section 6).

 dotnet build
     |
     v
 muxer: first dotnet on PATH (e.g. /usr/share/dotnet/dotnet)
     |
     v
 hostfxr: walk up from the CURRENT DIRECTORY
     ./global.json ? ../global.json ? ... filesystem root
     |
     +-- none found --> newest SDK installed next to this muxer
     |                  (previews included unless told otherwise)
     |
     +-- found      --> read sdk.version, rollForward, allowPrerelease
                        filter the installed SDKs (dotnet --list-sdks)
                        |
                        +-- match --> load dotnet/sdk/<version>/dotnet.dll
                        |              --> MSBuild, Roslyn, NuGet
                        |
                        +-- none  --> "A compatible .NET SDK was not found"
                                       (lists the requested version, the
                                        global.json path and installed SDKs)

2. The search starts from the current directory

hostfxr searches from the current working directory, not from the project you pass on the command line. These two commands can use different SDKs:

cd ~/repos/orders && dotnet build                      # uses ~/repos/orders/global.json
cd ~ && dotnet build repos/orders/src/Orders.Api       # starts searching in ~ and may not find it

It stops at the first global.json it finds. A file in a parent folder (for example one someone left in their home folder, or a monorepo root) applies to every repo below it unless a closer file overrides it.

3. Reading an SDK version number

An SDK version looks like 10.0.105:

 10 . 0 . 1 05
 |    |   | |
 |    |   | +-- patch (05): security and bug fixes, released roughly monthly
 |    |   +---- feature band (1 = 1xx): new MSBuild/Roslyn/CLI features
 |    +-------- minor (0)
 +------------- major (10): matches the .NET release

• Patches within a band are meant to be safe to take.
• Feature bands (10.0.1xx, 10.0.2xx, 10.0.3xx) usually ship alongside Visual Studio minor releases. A new band can bring a newer MSBuild and compiler, new analyser rules and new warnings, so moving bands is a real change even though the major version stays the same.
• The SDK version is independent of the runtime version: SDK 10.0.105 ships with a 10.0.x runtime, but it can build projects that target net8.0 or net9.0.

4. Every rollForward policy, with an example

Assume "version": "10.0.100" and these SDKs installed: 10.0.103, 10.0.105, 10.0.201, 11.0.100-preview.3.

Two rules apply to every policy:

• The resolver never rolls backwards. If 10.0.200 is requested and only 10.0.105 is installed, it fails under every policy.
• Prerelease SDKs are only candidates when allowPrerelease allows them.

5. allowPrerelease and its default

allowPrerelease decides whether preview SDKs can be selected. If you don't set it, the default depends on where the command runs. From the command line it is true. Inside Visual Studio it follows Visual Studio's own preview setting. That difference is why a build can pick a preview SDK in a terminal or on a CI agent but not in the IDE. Set "allowPrerelease": false explicitly on main branches so the result is the same everywhere.

6. Everything global.json can contain (.NET 10)

{
  "sdk": {
    "version": "10.0.100",
    "rollForward": "latestFeature",
    "allowPrerelease": false,
    "paths": [ ".dotnet", "$host$" ],
    "errorMessage": "Install the .NET 10 SDK: run ./eng/install-sdk.sh or see README.md."
  },
  "msbuild-sdks": {
    "Microsoft.Build.Traversal": "4.1.0"
  },
  "test": {
    "runner": "Microsoft.Testing.Platform"
  }
}

Older SDKs ignore the settings they don't understand, so adding the .NET 10 fields is safe in a mixed environment.

7. SDK roll forward is not runtime roll forward

These two are often confused:

DOTNET_ROLL_FORWARD=Major lets a net8.0 app run on the .NET 10 runtime. It has no effect on which SDK dotnet build uses.

8. Who honours global.json

9. Workloads are tied to the feature band

Optional workloads such as maui, wasm-tools and aspire (on older SDKs) are installed per SDK feature band. When latestFeature moves a machine from 10.0.1xx to 10.0.2xx, the new band has no workloads until you run dotnet workload restore or dotnet workload install. That is a common cause of "it built yesterday" on developer machines.

10. Diagnosing a resolution problem

1. Run dotnet --info from the folder where the command fails. It shows the SDK in use, the global.json file: path it found, the host path and the installed SDKs and runtimes.
2. Run dotnet --list-sdks and compare it with the policy in section 4.
3. Run which dotnet (macOS/Linux) or where.exe dotnet (Windows) to check which muxer is first on the PATH.
4. In CI, print dotnet --info as the first step of every job, so a changed agent image is visible in the logs.
5. Run dotnet sdk check to see which installed SDKs are out of support or have patches available.

11. Performance and security

• Resolution itself is fast. The cost of an unpinned SDK is in non-reproducible builds: a CI cache keyed on the SDK version misses after every agent image update.
• rollForward: disable stops security patches being picked up, so machines and agents keep running SDKs with known vulnerabilities. Prefer latestPatch or latestFeature and keep SDKs updated.
• A repo-local SDK through sdk.paths gives full control, but then your team owns patching it.

12. Try it yourself

1. Run dotnet --list-sdks and note the versions.
2. In an empty folder, run dotnet new globaljson --sdk-version 10.0.100 --roll-forward disable, then dotnet --version.
3. Change the version to one you don't have, such as 10.0.999, and run dotnet build to see the error.
4. Change rollForward to latestPatch, then latestFeature, and run dotnet --version after each change. Compare with the table in section 4.
5. cd to the parent folder and run dotnet --info again: the global.json line disappears, because the search starts from the current directory.
6. Set DOTNET_ROLL_FORWARD=Major and run dotnet --version. It doesn't change, because that variable controls the runtime, not the SDK.

# Create a pinned global.json at the repo root
dotnet new globaljson --sdk-version 10.0.100 --roll-forward latestFeature

# What did the host choose, and why?
dotnet --info
dotnet --list-sdks

# GitHub Actions: install exactly what the repo asks for
- uses: actions/setup-dotnet@v4
  with:
    global-json-file: global.json
- run: dotnet --info

# Azure Pipelines equivalent
- task: UseDotNet@2
  inputs:
    useGlobalJson: true
- script: dotnet --info