global.json overview

This article applies to: ✔️ .NET Core 2.0 SDK and later versions

The global.json file allows you to define which .NET Core SDK version is used when you run .NET Core CLI commands. Selecting the .NET Core SDK is independent from specifying the runtime your project targets. The .NET Core SDK version indicates which versions of the .NET Core CLI is used.

In general, you want to use the latest version of the SDK tools, so no global.json file is needed. In some advanced scenarios, you might want to control the version of the SDK tools, and this article explains how to do this.

For more information about specifying the runtime instead, see Target frameworks.

.NET Core SDK looks for a global.json file in the current working directory (which isn't necessarily the same as the project directory) or one of its parent directories.

global.json schema

sdk

Type: object

Specifies information about the .NET Core SDK to select.

version

  • Type: string

  • Available since: .NET Core 1.0 SDK.

The version of the .NET Core SDK to use.

This field:

  • Doesn't have wildcard support, that is, the full version number has to be specified.
  • Doesn't support version ranges.

allowPrerelease

  • Type: boolean

  • Available since: .NET Core 3.0 SDK.

Indicates whether the SDK resolver should consider prerelease versions when selecting the SDK version to use.

If you don't set this value explicitly, the default value depends on whether you're running from Visual Studio:

  • If you're not in Visual Studio, the default value is true.
  • If you are in Visual Studio, it uses the prerelease status requested. That is, if you're using a Preview version of Visual Studio or you set the Use previews of the .NET Core SDK option (under Tools > Options > Environment > Preview Features), the default value is true; otherwise, false.

rollForward

  • Type: string

  • Available since: .NET Core 3.0 SDK.

The roll-forward policy to use when selecting an SDK version, either as a fallback when a specific SDK version is missing or as a directive to use a higher version. A version must be specified with a rollForward value, unless you're setting it to latestMajor.

To understand the available policies and their behavior, consider the following definitions for an SDK version in the format x.y.znn:

  • x is the major version.
  • y is the minor version.
  • z is the feature band.
  • nn is the patch version.

The following table shows the possible values for the rollForward key:

Value Behavior
patch Uses the specified version.
If not found, rolls forward to the latest patch level.
If not found, fails.

This value is the legacy behavior from the earlier versions of the SDK.
feature Uses the latest patch level for the specified major, minor, and feature band.
If not found, rolls forward to the next higher feature band within the same major/minor and uses the latest patch level for that feature band.
If not found, fails.
minor Uses the latest patch level for the specified major, minor, and feature band.
If not found, rolls forward to the next higher feature band within the same major/minor version and uses the latest patch level for that feature band.
If not found, rolls forward to the next higher minor and feature band within the same major and uses the latest patch level for that feature band.
If not found, fails.
major Uses the latest patch level for the specified major, minor, and feature band.
If not found, rolls forward to the next higher feature band within the same major/minor version and uses the latest patch level for that feature band.
If not found, rolls forward to the next higher minor and feature band within the same major and uses the latest patch level for that feature band.
If not found, rolls forward to the next higher major, minor, and feature band and uses the latest patch level for that feature band.
If not found, fails.
latestPatch Uses the latest installed patch level that matches the requested major, minor, and feature band with a patch level and that is greater or equal than the specified value.
If not found, fails.
latestFeature Uses the highest installed feature band and patch level that matches the requested major and minor with a feature band and patch level that is greater or equal than the specified value.
If not found, fails.
latestMinor Uses the highest installed minor, feature band, and patch level that matches the requested major with a minor, feature band, and patch level that is greater or equal than the specified value.
If not found, fails.
latestMajor Uses the highest installed .NET Core SDK with a version that is greater or equal than the specified value.
If not found, fail.
disable Doesn't roll forward. Exact match required.

msbuild-sdks

Type: object

Lets you control the project SDK version in one place rather than in each individual project. For more information, see How project SDKs are resolved.

Examples

The following example shows how to not use prerelease versions:

{
  "sdk": {
    "allowPrerelease": false
  }
}

The following example shows how to use the highest version installed that is greater or equal than the specified version. The JSON shown disallows any SDK version earlier than 2.2.200 and allows 2.2.200 or any later version, including 3.0.xxx and 3.1.xxx.

{
  "sdk": {
    "version": "2.2.200",
    "rollForward": "latestMajor"
  }
}

The following example shows how to use the exact specified version:

{
  "sdk": {
    "version": "3.1.100",
    "rollForward": "disable"
  }
}

The following example shows how to use the latest feature band and patch version installed of a specific major and minor version. The JSON shown disallows any SDK version earlier than 3.1.102 and allows 3.1.102 or any later 3.1.xxx version, such as 3.1.103 or 3.1.200.

{
  "sdk": {
    "version": "3.1.102",
    "rollForward": "latestFeature"
  }
}

The following example shows how to use the highest patch version installed of a specific version. The JSON shown disallows any SDK version earlier than 3.1.102 and allows 3.1.102 or any later 3.1.1xx version, such as 3.1.103 or 3.1.199.

{
  "sdk": {
    "version": "3.1.102",
    "rollForward": "latestPatch"
  }
}

global.json and the .NET Core CLI

It's helpful to know which SDK versions are installed on your machine to set one in the global.json file. For more information on how to do that, see How to check that .NET Core is already installed.

To install additional .NET Core SDK versions on your machine, visit the Download .NET Core page.

You can create a new the global.json file in the current directory by executing the dotnet new command, similar to the following example:

dotnet new globaljson --sdk-version 3.0.100

Matching rules

Note

The matching rules are governed by the dotnet.exe entry point, which is common across all installed .NET Core installed runtimes. The matching rules for the latest installed version of the .NET Core Runtime are used when you have multiple runtimes installed side-by-side.

Starting with .NET Core 3.0, the following rules apply when determining which version of the SDK to use:

  • If no global.json file is found, or global.json doesn't specify an SDK version nor an allowPrerelease value, the highest installed SDK version is used (equivalent to setting rollForward to latestMajor). Whether prerelease SDK versions are considered depends on how dotnet is being invoked.

    • If you're not in Visual Studio, prerelease versions are considered.
    • If you are in Visual Studio, it uses the prerelease status requested. That is, if you're using a Preview version of Visual Studio or you set the Use previews of the .NET Core SDK option (under Tools > Options > Environment > Preview Features), prerelease versions are considered; otherwise, only release versions are considered.
  • If a global.json file is found that doesn't specify an SDK version but it specifies an allowPrerelease value, the highest installed SDK version is used (equivalent to setting rollForward to latestMajor). Whether the latest SDK version can be release or prerelease depends on the value of allowPrerelease. true indicates prerelease versions are considered; false indicates that only release versions are considered.

  • If a global.json file is found and it specifies an SDK version:

    • If no rollForward value is set, it uses latestPatch as the default rollForward policy. Otherwise, check each value and their behavior in the rollForward section.
    • Whether prerelease versions are considered and what's the default behavior when allowPrerelease isn't set is described in the allowPrerelease section.

Troubleshoot build warnings

  • The following warning indicates that your project was compiled using a prerelease version of the .NET Core SDK:

    You are working with a preview version of the .NET Core SDK. You can define the SDK version via a global.json file in the current project. More at https://go.microsoft.com/fwlink/?linkid=869452.

    .NET Core SDK versions have a history and commitment of being high quality. However, if you don't want to use a prerelease version, check the different strategies you can use with the .NET Core 3.0 SDK or a later version in the allowPrerelease section. For machines that have never had a .NET Core 3.0 or higher Runtime or SDK installed, you need to create a global.json file and specify the exact version you want to use.

  • The following warning indicates that your project targets EF Core 1.0 or 1.1, which isn't compatible with .NET Core 2.1 SDK and later versions:

    Startup project '{startupProject}' targets framework '.NETCoreApp' version '{targetFrameworkVersion}'. This version of the Entity Framework Core .NET Command-line Tools only supports version 2.0 or higher. For information on using older versions of the tools, see https://go.microsoft.com/fwlink/?linkid=871254.

    Starting with .NET Core 2.1 SDK (version 2.1.300), the dotnet ef command comes included in the SDK. To compile your project, install .NET Core 2.0 SDK (version 2.1.201) or earlier on your machine and define the desired SDK version using the global.json file. For more information about the dotnet ef command, see EF Core .NET Command-line Tools.

See also