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 SDK version is used when you run .NET CLI commands. Selecting the .NET SDK is independent from specifying the runtime your project targets. The .NET SDK version indicates which versions of the .NET 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.

The .NET 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 SDK to select.

version

• Type: string

• Available since: .NET Core 1.0 SDK.

The version of the .NET 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. The default roll forward behavior is determined by the matching rules.

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:

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 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 is already installed.

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

You can create a new 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

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

• How project SDKs are resolved