Skip to content

update global.json #4704

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jul 9, 2018
Merged

update global.json #4704

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c343118
update global.json
mairaw Apr 3, 2018
dfc9999
updates
mairaw May 24, 2018
2d5869f
further updates
mairaw Jun 27, 2018
c319803
feedback
mairaw Jun 29, 2018
358f970
feedback
mairaw Jul 3, 2018
9cb1ddc
removed extra space
mairaw Jul 3, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 85 additions & 13 deletions docs/core/tools/global-json.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,104 @@
---
title: global.json reference
description: See the schema for the global.json file, which permits setting the .NET Core tools version.
author: blackdwarf
title: global.json overview
description: Learn how to use the global.json file to set the .NET Core SDK version when running .NET Core CLI commands.
author: mairaw
ms.author: mairaw
ms.date: 04/05/2017
ms.date: 07/02/2018
ms.custom: "updateeachrelease"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this also have "mvc" with a topic type of "conceptual"?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure how you all do topics, but...

This is relevant for all .NET Core apps, there is nothing about MVC that makes it more or less relevant, so I would suggest not including it, or including all application types that work in .NET Core.

Copy link
Member

@BillWagner BillWagner Jul 3, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@KathleenDollard The "MVC" moniker here is an internal APEX term that refers to a content process. We have asked for a change because of confusion with the "ASP.NET MVC" product. The two are unrelated.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought that conceptual wasn't really a mvc topic type @JRAlexander.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As far as I know, it is.

---
# global.json reference
# global.json overview

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

.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.
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.

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

.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

## sdk
Type: Object

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm seeing enough confusion that I would like to add the following, perhaps as a note:

Selecting the .NET Core SDK is independent from specifying the .NET Core Runtime your project targets. You specify the runtime [[ a few words and links for how you select target runtime ]]. The .NET Core SDK version indicates which versions of tools are used. In general you want to use the latest tools, and thus no global.json is needed.

#### version

### version
Type: String

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

Note that this field:

For example:
- Doesn't have globbing support, that is, the full version number has to be specified.
- Doesn't support version ranges.

The following example shows the contents of a *global.json* file:

```json
{
"sdk": {
"version": "1.0.0-preview2-003121"
"version": "2.1.300"
}
}
```

## global.json and the .NET Core CLI

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:

```console
dotnet --list-sdks
```

To install additional .NET Core SDK versions on your machine, visit the [.NET Downloads](https://www.microsoft.com/net/download/all) site.

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:

```console
dotnet new globaljson --sdk-version 2.1.300
```

## Matching rules
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should matching rules. be in the main global.json topic rather than reference?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what is the main global.json topic? Would you like to split this in two? Customers complain this topic has too little information so maybe I could just tweak the title to be more generic like global.json overview and add a subsection called global.json reference?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this rule might be better in the global.json overview.

If that leaves this topic too thin, you could fold it all into one

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As discussed offline, this is the only topic, so keeping that here but reworking title and sections.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this topic is covered here


> [!NOTE]
> The matching rules are governed by the apphost, which is part of the .NET Core runtime.
> The latest version of the host is used when you have multiple runtimes installed side-by-side.

Starting with .NET Core 2.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, the latest installed SDK version is used. Latest SDK version can be either release or pre-release - the highest version number wins.
- If *global.json* does specify an SDK version:
- If the specified SDK version is found on the machine, that exact version is used.
- 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.
- If the specified SDK version and an appropriate SDK **patch version** can't be found, an error is thrown.

The SDK version is currently composed of the following parts:

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

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.

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`.

.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.

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.

## Troubleshooting build warnings

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

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.

> [!WARNING]
> 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 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).

## See also

[How project SDKs are resolved](/visualstudio/msbuild/how-to-use-project-sdk#how-project-sdks-are-resolved)