Skip to content

Commit c0c7f92

Browse files
mairawKathleenDollard
mairaw
and
KathleenDollard
authored
Update global.json for 3.0 (#15382)
* initial commit * table review * add missing word * more edits * fix weird formatting * more weird formatting * last weird formatting * fix tab names * linting rules * add one more example * update sdk version * acrolinx + more updates * small change * Apply suggestions from docs review Co-Authored-By: Kathleen Dollard <[email protected]> * feedback + acrolinx * Apply suggestions from docs review Co-Authored-By: Kathleen Dollard <[email protected]> * update ms.date * Apply suggestions from docs review Co-Authored-By: Kathleen Dollard <[email protected]> * update ms.date Co-authored-by: Kathleen Dollard <[email protected]>
1 parent c06a5e9 commit c0c7f92

File tree

1 file changed

+113
-22
lines changed

1 file changed

+113
-22
lines changed

‎docs/core/tools/global-json.md

Lines changed: 113 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
11
---
22
title: global.json overview
33
description: Learn how to use the global.json file to set the .NET Core SDK version when running .NET Core CLI commands.
4-
ms.date: 12/03/2018
4+
ms.date: 01/14/2020
55
ms.custom: "updateeachrelease"
66
---
77
# global.json overview
88

9-
[!INCLUDE [topic-appliesto-net-core-all](../../../includes/topic-appliesto-net-core-all.md)]
9+
**This article applies to: ✓** .NET Core 2.0 SDK and later versions
1010

11-
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 tools are used. In general, you want to use the latest version of the tools, so no *global.json* file is needed.
11+
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 tools are used.
12+
13+
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.
1214

1315
For more information about specifying the runtime instead, see [Target frameworks](../../standard/frameworks.md).
1416

@@ -18,62 +20,151 @@ For more information about specifying the runtime instead, see [Target framework
1820

1921
### sdk
2022

21-
Type: Object
23+
Type: `object`
2224

2325
Specifies information about the .NET Core SDK to select.
2426

2527
#### version
2628

27-
Type: String
29+
- Type: `string`
30+
31+
- Available since: .NET Core 1.0 SDK.
2832

2933
The version of the .NET Core SDK to use.
3034

31-
Note that this field:
35+
This field:
3236

33-
- Doesn't have globbing support, that is, the full version number has to be specified.
37+
- Doesn't have wildcard support, that is, the full version number has to be specified.
3438
- Doesn't support version ranges.
3539

36-
The following example shows the contents of a *global.json* file:
40+
#### allowPrerelease
41+
42+
- Type: `boolean`
43+
44+
- Available since: .NET Core 3.0 SDK.
45+
46+
Indicates whether the SDK resolver should consider prerelease versions when selecting the SDK version to use.
47+
48+
If you don't set this value explicitly, the default value depends on whether you're running from Visual Studio:
49+
50+
- If you're **not** in Visual Studio, the default value is `true`.
51+
- 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`.
52+
53+
#### rollForward
54+
55+
- Type: `string`
56+
57+
- Available since: .NET Core 3.0 SDK.
58+
59+
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](#version) must be specified with a `rollForward` value, unless you're setting it to `latestMajor`.
60+
61+
To understand the available policies and their behavior, consider the following definitions for an SDK version in the format `x.y.znn`:
62+
63+
- `x` is the major version.
64+
- `y` is the minor version.
65+
- `z` is the feature band.
66+
- `nn` is the patch version.
67+
68+
The following table shows the possible values for the `rollForward` key:
69+
70+
| Value | Behavior |
71+
| ------------- | ---------- |
72+
| `patch` | Uses the specified version. <br> If not found, rolls forward to the latest patch level. <br> If not found, fails. <br><br> This value is the legacy behavior from the earlier versions of the SDK. |
73+
| `feature` | Uses the latest patch level for the specified major, minor, and feature band. <br> 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. <br> If not found, fails. |
74+
| `minor` | Uses the latest patch level for the specified major, minor, and feature band. <br> 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. <br> 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. <br> If not found, fails. |
75+
| `major` | Uses the latest patch level for the specified major, minor, and feature band. <br> 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. <br> 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. <br> If not found, rolls forward to the next higher major, minor, and feature band and uses the latest patch level for that feature band. <br> If not found, fails. |
76+
| `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. <br> If not found, fails. |
77+
| `latestFeature` | Uses the highest installed feature band and patch level that matches the requested major and minor with a feature band that is greater or equal than the specified value. <br> If not found, fails. |
78+
| `latestMinor` | Uses the highest installed minor, feature band, and patch level that matches the requested major with a minor that is greater or equal than the specified value. <br> If not found, fails. |
79+
| `latestMajor` | Uses the highest installed .NET Core SDK with a major that is greater or equal than the specified value. <br> If not found, fail. |
80+
| `disable` | Doesn't roll forward. Exact match required. |
81+
82+
## Examples
83+
84+
The following example shows how to not use prerelease versions:
3785

3886
```json
3987
{
4088
"sdk": {
41-
"version": "2.2.100"
89+
"allowPrerelease": false
4290
}
4391
}
4492
```
4593

46-
## global.json and the .NET Core CLI
94+
The following example shows how to use the highest version installed that is greater or equal than the specified version:
95+
96+
```json
97+
{
98+
"sdk": {
99+
"version": "3.1.100",
100+
"rollForward": "latestMajor"
101+
}
102+
}
103+
```
47104

48-
It's helpful to know which versions are available in order to set one in the *global.json* file. You can find the full list of supported available SDKs at the [Download .NET Core](https://dotnet.microsoft.com/download/dotnet-core) page. Starting with .NET Core 2.1 SDK, you can run the following command to verify which SDK versions are already installed on your machine:
105+
The following example shows how to use the exact specified version:
49106

50-
```dotnetcli
51-
dotnet --list-sdks
107+
```json
108+
{
109+
"sdk": {
110+
"version": "3.1.100",
111+
"rollForward": "disable"
112+
}
113+
}
114+
```
115+
116+
The following example shows how to use the highest patch version installed of a specific version (in the form, 3.1.1xx):
117+
118+
```json
119+
{
120+
"sdk": {
121+
"version": "3.1.100",
122+
"rollForward": "latestPatch"
123+
}
124+
}
52125
```
53126

127+
## global.json and the .NET Core CLI
128+
129+
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](../install/how-to-detect-installed-versions.md#check-sdk-versions).
130+
54131
To install additional .NET Core SDK versions on your machine, visit the [Download .NET Core](https://dotnet.microsoft.com/download/dotnet-core) page.
55132

56133
You can create a new the *global.json* file in the current directory by executing the [dotnet new](dotnet-new.md) command, similar to the following example:
57134

58135
```dotnetcli
59-
dotnet new globaljson --sdk-version 2.2.100
136+
dotnet new globaljson --sdk-version 3.0.100
60137
```
61138

62139
## Matching rules
63140

64141
> [!NOTE]
65-
> The matching rules are governed by the apphost, which is part of the .NET Core runtime.
66-
> The latest version of the host is used when you have multiple runtimes installed side-by-side.
142+
> 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.
67143
68-
Starting with .NET Core 2.0, the following rules apply when determining which version of the SDK to use:
144+
## [.NET Core 3.x](#tab/netcore3x)
69145

70-
- If no *global.json* file is found or *global.json* doesn't specify an SDK version, the latest installed SDK version is used. Latest SDK version can be either release or pre-release - the highest version number wins.
146+
Starting with .NET Core 3.0, the following rules apply when determining which version of the SDK to use:
147+
148+
- 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.
149+
- If you're **not** in Visual Studio, prerelease versions are considered.
150+
- 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.
151+
- 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.
152+
- If a *global.json* file is found and it specifies an SDK version:
153+
154+
- If no `rollFoward` value is set, it uses `latestPatch` as the default `rollForward` policy. Otherwise, check each value and their behavior in the [rollForward](#rollforward) section.
155+
- Whether prerelease versions are considered and what's the default behavior when `allowPrerelease` isn't set is described in the [allowPrerelease](#allowprerelease) section.
156+
157+
## [.NET Core 2.x](#tab/netcore2x)
158+
159+
In .NET Core 2.x SDK, the following rules apply when determining which version of the SDK to use:
160+
161+
- If no *global.json* file is found or *global.json* doesn't specify an SDK version, the latest installed SDK version is used. Latest SDK version can be either release or prerelease - the highest version number wins.
71162
- If *global.json* does specify an SDK version:
72163
- If the specified SDK version is found on the machine, that exact version is used.
73-
- If the specified SDK version can't be found on the machine, the latest installed SDK **patch version** of that version is used. Latest installed SDK **patch version** can be either release or pre-release - the highest version number wins. In .NET Core 2.1 and higher, the **patch versions** lower than the **patch version** specified are ignored in the SDK selection.
164+
- If the specified SDK version can't be found on the machine, the latest installed SDK **patch version** of that version is used. Latest installed SDK **patch version** can be either release or prerelease - the highest version number wins. In .NET Core 2.1 and higher, the **patch versions** lower than the **patch version** specified are ignored in the SDK selection.
74165
- If the specified SDK version and an appropriate SDK **patch version** can't be found, an error is thrown.
75166

76-
The SDK version is currently composed of the following parts:
167+
The SDK version is composed of the following parts:
77168

78169
`[.NET Core major version].[.NET Core minor version].[xyz][-optional preview name]`
79170

@@ -83,14 +174,14 @@ The **patch version** is defined by the last two digits (`yz`) in the last porti
83174

84175
.NET Core SDK versions `2.1.100` through `2.1.201` were released during the transition between version number schemes and don't correctly handle the `xyz` notation. We highly recommend if you specify these versions in the *global.json* file, that you ensure the specified versions are on the target machines.
85176

86-
With .NET Core SDK 1.x, if you specified a version and no exact match was found, the latest installed SDK version was used. Latest SDK version can be either release or pre-release - the highest version number wins.
177+
---
87178

88179
## Troubleshooting build warnings
89180

90181
> [!WARNING]
91182
> 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>
92183
93-
This warning indicates that your project is being compiled using a preview version of the .NET Core SDK, as explained in the [Matching rules](#matching-rules) section. .NET Core SDK versions have a history and commitment of being high quality. However, if you don't want to use a preview version, add a *global.json* file to your project hierarchy structure to specify which SDK version to use, and use `dotnet --list-sdks` to confirm that the version is installed on your machine. When a new version is released, to use the new version, either remove the *global.json* file or update it to use the newer version.
184+
This warning indicates that your project was compiled using a prerelease version of the .NET Core SDK. .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](#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.
94185

95186
> [!WARNING]
96187
> 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>

0 commit comments

Comments
 (0)