Skip to content

Commit 8965131

Browse files
mairawmairaw
authored
update global.json (#4704)
* update global.json * updates * further updates * feedback * feedback * removed extra space
1 parent c9d1a62 commit 8965131

File tree

1 file changed

+85
-13
lines changed

1 file changed

+85
-13
lines changed

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

Lines changed: 85 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,104 @@
11
---
2-
title: global.json reference
3-
description: See the schema for the global.json file, which permits setting the .NET Core tools version.
4-
author: blackdwarf
2+
title: global.json overview
3+
description: Learn how to use the global.json file to set the .NET Core SDK version when running .NET Core CLI commands.
4+
author: mairaw
55
ms.author: mairaw
6-
ms.date: 04/05/2017
6+
ms.date: 07/02/2018
7+
ms.custom: "updateeachrelease"
78
---
8-
# global.json reference
9+
# global.json overview
910

10-
The *global.json* file allows selection of the .NET Core tools version being used through the `sdk` property.
11+
[!INCLUDE [topic-appliesto-net-core-all](../../../includes/topic-appliesto-net-core-all.md)]
1112

12-
.NET Core CLI tools look for this file in the current working directory (which isn't necessarily the same as the project directory) or one of its parent directories.
13+
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.
14+
15+
For more information about specifying the runtime instead, see [Target frameworks](../../standard/frameworks.md).
16+
17+
.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.
18+
19+
## global.json schema
20+
21+
### sdk
1322

14-
## sdk
1523
Type: Object
1624

17-
Specifies information about the SDK.
25+
Specifies information about the .NET Core SDK to select.
26+
27+
#### version
1828

19-
### version
2029
Type: String
2130

22-
The version of the SDK to use.
31+
The version of the .NET Core SDK to use.
32+
33+
Note that this field:
2334

24-
For example:
35+
- Doesn't have globbing support, that is, the full version number has to be specified.
36+
- Doesn't support version ranges.
37+
38+
The following example shows the contents of a *global.json* file:
2539

2640
```json
2741
{
2842
"sdk": {
29-
"version": "1.0.0-preview2-003121"
43+
"version": "2.1.300"
3044
}
3145
}
3246
```
47+
48+
## global.json and the .NET Core CLI
49+
50+
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 [.NET Downloads](https://www.microsoft.com/net/download/all) site. Starting with .NET Core SDK 2.1, you can run the following command to verify which SDK versions are already installed on your machine:
51+
52+
```console
53+
dotnet --list-sdks
54+
```
55+
56+
To install additional .NET Core SDK versions on your machine, visit the [.NET Downloads](https://www.microsoft.com/net/download/all) site.
57+
58+
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:
59+
60+
```console
61+
dotnet new globaljson --sdk-version 2.1.300
62+
```
63+
64+
## Matching rules
65+
66+
> [!NOTE]
67+
> The matching rules are governed by the apphost, which is part of the .NET Core runtime.
68+
> The latest version of the host is used when you have multiple runtimes installed side-by-side.
69+
70+
Starting with .NET Core 2.0, the following rules apply when determining which version of the SDK to use:
71+
72+
- 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.
73+
- If *global.json* does specify an SDK version:
74+
- If the specified SDK version is found on the machine, that exact version is used.
75+
- 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.
76+
- If the specified SDK version and an appropriate SDK **patch version** can't be found, an error is thrown.
77+
78+
The SDK version is currently composed of the following parts:
79+
80+
`[.NET Core major version].[.NET Core minor version].[xyz][-optional preview name]`
81+
82+
The **feature release** of the .NET Core SDK is represented by the first digit (`x`) in the last portion of the number (`xyz`) for SDK versions 2.1.100 and higher. In general, the .NET Core SDK has a faster release cycle than .NET Core.
83+
84+
The **patch version** is defined by the last two digits (`yz`) in the last portion of the number (`xyz`) for SDK versions 2.1.100 and higher. For example, if you specify `2.1.300` as the SDK version, SDK selection finds up to `2.1.399` but `2.1.400` isn't considered a patch version for `2.1.300`.
85+
86+
.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.
87+
88+
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.
89+
90+
## Troubleshooting build warnings
91+
92+
> [!WARNING]
93+
> 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
94+
95+
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.
96+
97+
> [!WARNING]
98+
> 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
99+
100+
Starting with .NET Core SDK 2.1 (v. 2.1.300), the `dotnet ef` command comes included in the SDK. This warning indicates that your project targets EF Core 1.0 or 1.1, which isn't compatible with .NET Core SDK 2.1 and later versions. To compile your project, install .NET Core SDK 2.0 (v. 2.1.201) and earlier on your machine. For more information, see [EF Core .NET Command-line Tools](/ef/core/miscellaneous/cli/dotnet).
101+
102+
## See also
103+
104+
[How project SDKs are resolved](/visualstudio/msbuild/how-to-use-project-sdk#how-project-sdks-are-resolved)

0 commit comments

Comments
 (0)