Which global.json rollForward policy suits a team repository, and what do allowPrerelease and the .NET 10 paths, errorMessage and test.runner settings add?
answer
- latestFeature: newest 10.0.x at or above
- disable: exact match, pairs with lock files
- allowPrerelease defaults to true outside VS
- paths with $host$, errorMessage
- test.runner: Microsoft.Testing.Platform
basics
~10 sTeams 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.
solid answer
~40 s`rollForward` values: `patch` (default with a version), `feature`, `minor`, `major` (use the requested level if present, otherwise roll to the next), `latestPatch`, `latestFeature`, `latestMinor`, `latestMajor` (prefer the highest installed at that level, never below the version), and `disable` (exact match). `latestFeature` suits most teams: everyone on 10.0, newest band installed, with a floor. `latestPatch` keeps one feature band when a new band's MSBuild or NuGet would change outputs, and `disable` keeps the SDK in lockstep with package lock files. Set `allowPrerelease: false` explicitly, because it defaults to `true` outside Visual Studio. New in .NET 10: `paths` lists folders to search for SDKs (`$host$` is the running `dotnet`), `errorMessage` replaces the resolution error, and `test.runner` set to `Microsoft.Testing.Platform` switches `dotnet test` from VSTest.
code
json · 12 lines{
"sdk": {
"version": "10.0.100",
"rollForward": "latestFeature",
"allowPrerelease": false,
"paths": [ ".dotnet", "$host$" ],
"errorMessage": "Pinned .NET SDK not found. Run ./eng/install-sdk.sh."
},
"test": {
"runner": "Microsoft.Testing.Platform"
}
}go deeper
Recall that rollForward tells the SDK what to do when the pinned version is missing, and that latestFeature is a common team choice.
Explain the two families of policies, why every policy keeps the version as a floor, and the default allowPrerelease behaviour outside Visual Studio.
Pick a policy per repository and justify it: latestFeature for teams, latestPatch or disable for reproducible or locked builds, and use paths and errorMessage to make SDK bootstrap self-explanatory.
Balance reproducibility against upgrade friction across many repositories: strict pins need image and bootstrap discipline, loose pins need tolerance for feature-band changes.
## Two families of policies For an SDK version written as `x.y.znn` (major, minor, feature band `z`, patch `nn`), `global.json`'s `rollForward` takes these values: | Value | Behaviour | |---|---| | `patch` | requested version, else latest patch in the same band, else fail (the default when a version is given) | | `feature` | latest patch of the requested band, else the next higher band of the same major.minor | | `minor` | as `feature`, then the next higher minor of the same major | | `major` | as `minor`, then the next higher major | | `latestPatch` | highest installed patch of the requested band, at or above the version | | `latestFeature` | highest installed band and patch of the requested major.minor, at or above the version | | `latestMinor` | highest installed minor of the requested major, at or above the version | | `latestMajor` | highest installed SDK at or above the version | | `disable` | exact match only | The first group **prefers what you asked for** and moves only when it is missing; the `latest*` group **prefers the newest installed** within its limit. Every policy fails rather than going below the requested version. ## Choosing one - **`latestFeature`** is the usual team choice: everyone stays on .NET 10's SDK line, picks up new feature bands and patches as they install them, and the version acts as a floor. It tolerates developers and agents being on different bands. - **`latestPatch`** pins one feature band. Use it when a new band's MSBuild, NuGet or analyzer changes have bitten the build and you want bands to move only by an explicit edit. - **`disable`** demands the exact SDK. The SDK docs recommend it with **package lock files**, because the SDK carries NuGet and a different SDK can change the restore graph; it is also the choice for fully reproducible release builds. Every machine then needs that exact version. - **`latestMajor`** means effectively no pin, useful only for samples or tools that must build with whatever is newest. ## allowPrerelease When not set, prerelease SDKs are considered **outside Visual Studio** (`true`), while Visual Studio follows its own preview setting. A developer who installs a .NET preview SDK can therefore start building the repository with it from the command line. Teams that do not want that set `"allowPrerelease": false` explicitly. ## What the .NET 10 SDK adds 1. **`paths`**: an ordered list of folders to search for SDKs, absolute or relative to `global.json`. `$host$` stands for the installation of the `dotnet` being run. `[ ".dotnet", "$host$" ]` prefers an SDK installed into the repository's `.dotnet` folder by a bootstrap script, then falls back to the machine install. It applies to SDK commands only, not to launching a built app. 2. **`errorMessage`**: custom text shown when no SDK satisfies the file, such as "Run ./eng/install-sdk.sh to install the pinned SDK", which turns a cryptic failure into an instruction. 3. **`test.runner`**: `"Microsoft.Testing.Platform"` makes `dotnet test` use Microsoft.Testing.Platform instead of the default `VSTest`. The CLI options then change, so pipelines must be updated with it; the platform itself is covered by the MSTest runner topic. ## The scenario A team moving a 40-project solution to the .NET 10 SDK commits `version` `10.0.100` with `latestFeature`, `allowPrerelease: false`, and an `errorMessage` pointing at the install script. Agents built from an image with `10.0.4xx` qualify, laptops with `10.0.1xx` qualify, and a preview SDK on someone's machine does not hijack the build.
- Why does the SDK documentation pair rollForward disable with package lock files?The SDK includes NuGet and controls parts of restore, so a different SDK can resolve a different dependency graph than the one the lock file recorded. Requiring the exact SDK keeps the SDK and the locked graph in step.
- Does paths affect running a built app with dotnet app.dll?No. It only applies to commands that resolve an SDK, such as `dotnet build` or `dotnet run`. Launching a built app, through its apphost or `dotnet app.dll`, does not consult it.
- rollForward latestFeature may select an SDK older than the version written.
- allowPrerelease defaults to false, so previews never build the repository.
- patch and latestPatch behave identically.
- paths in global.json also controls which runtime a published app starts on.
- test.runner only changes the console output of dotnet test.
Assumes the .NET 10 SDK; global.json's paths, errorMessage and test.runner settings are honoured only by .NET 10 SDKs and hosts.