From 7bb4c90d5bac1921d9dac86892cc3454945e0429 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Wed, 25 Apr 2018 19:28:32 -0700 Subject: [PATCH 01/10] first draft of global tools --- docs/core/tools/dotnet-tool-install.md | 85 +++++++++++ docs/core/tools/dotnet-tool-list.md | 55 +++++++ docs/core/tools/dotnet-tool-uninstall.md | 61 ++++++++ docs/core/tools/dotnet-tool-update.md | 77 ++++++++++ docs/core/tools/global-tools.md | 149 +++++++++++++++++++ docs/toc.md | 13 +- includes/topic-appliesto-net-core-2-1plus.md | 1 + 7 files changed, 438 insertions(+), 3 deletions(-) create mode 100644 docs/core/tools/dotnet-tool-install.md create mode 100644 docs/core/tools/dotnet-tool-list.md create mode 100644 docs/core/tools/dotnet-tool-uninstall.md create mode 100644 docs/core/tools/dotnet-tool-update.md create mode 100644 docs/core/tools/global-tools.md create mode 100644 includes/topic-appliesto-net-core-2-1plus.md diff --git a/docs/core/tools/dotnet-tool-install.md b/docs/core/tools/dotnet-tool-install.md new file mode 100644 index 0000000000000..464bc9db28986 --- /dev/null +++ b/docs/core/tools/dotnet-tool-install.md @@ -0,0 +1,85 @@ +--- +title: dotnet tool install command - .NET Core CLI +description: The dotnet tool install command installs the specified .NET Core Global Tool on your machine. +author: mairaw +ms.author: mairaw +ms.date: 04/25/2018 +ms.topic: article +ms.prod: .net-core +ms.technology: dotnet-cli +ms.workload: + - dotnetcore +--- +# dotnet tool install + +[!INCLUDE [topic-appliesto-net-core-2-1plus.md](../../../includes/topic-appliesto-net-core-2-1plus.md)] + +## Name + +`dotnet tool install` - Installs the specified [.NET Core Global Tool](global-tools.md) on your machine. + +## Synopsis + +``` +dotnet tool install <-g|--global> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] [--version] +dotnet tool install <--tool-path> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] [--version] +dotnet tool install [-h|--help] +``` + +## Description + +The `dotnet tool install` command provides a way for you to install .NET Core Global Tools on your machine. To use the command, you either have to specify that you want a user-wide installation using the `--global` option or you specify a path to install it using the `--tool-path` option. + +## Arguments + +`PACKAGE_ID` + +ID of the NuGet package that contains the .NET Core Global tool to install. + +## Options + +`--configfile ` + +The NuGet configuration (*nuget.config*) file to use. + +`-f|--framework ` + +Specifies the [target framework](../../standard/frameworks.md) to install the tool for. + +`-g|--global` + +Specifies that the installation is user wide. If you don't specify this option, you must specify the `--tool-path` option. + +`-h|--help` + +Prints out a short help for the command. + +`--source-feed ` + +Adds an additional NuGet package source to use during installation. + +`--tool-path ` + +Specifies the location where to install the global tool. PATH can be absolute or relative. If PATH doesn't exist, the command tries to create it. Can't be combined with the `--global` option. + +`-v|--verbosity ` + +Sets the verbosity level of the command. Allowed values are `q[uiet]`, `m[inimal]`, `n[ormal]`, `d[etailed]`, and `diag[nostic]`. + +`--version ` + +The version of the tool to install. By default, the latest stable package version is installed. + +## Examples + +Installs the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool: + +`dotnet tool install -g dotnetsay` + +Installs the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool on a specific Windows folder: + +`dotnet tool install dotnetsay --tool-path c:\global-tools` + +Installs version 1.0.0 of the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool: + +`dotnet tool install -g dotnetsay --version 1.0.0` \ No newline at end of file diff --git a/docs/core/tools/dotnet-tool-list.md b/docs/core/tools/dotnet-tool-list.md new file mode 100644 index 0000000000000..7961ecbf545ce --- /dev/null +++ b/docs/core/tools/dotnet-tool-list.md @@ -0,0 +1,55 @@ +--- +title: dotnet tool list command - .NET Core CLI +description: The dotnet tool list command lists the specified .NET Core Global Tool from your machine. +author: mairaw +ms.author: mairaw +ms.date: 04/25/2018 +ms.topic: article +ms.prod: .net-core +ms.technology: dotnet-cli +ms.workload: + - dotnetcore +--- +# dotnet tool list + +[!INCLUDE [topic-appliesto-net-core-2-1plus.md](../../../includes/topic-appliesto-net-core-2-1plus.md)] + +## Name + +`dotnet tool list` - Lists all [.NET Core Global Tools](global-tools.md) currently installed on your machine or specified path. + +## Synopsis + +``` +dotnet tool list <-g|--global> +dotnet tool list <--tool-path> +dotnet tool list [-h|--help] +``` + +## Description + +The `dotnet tool list` command provides a way for you to list all .NET Core Global Tools installed on your machine (current user profile) or specified path. The command lists the package name, version installed, and the global tool command. To use the list command, you either have to specify that you want to see all user-wide tools using the `--global` option or specify a custom path using the `--tool-path` option. + +## Options + +`-g|--global` + +Specifies that the tool to be removed is from a user-wide installation. If you don't specify this option, you must specify the `--tool-path` option. + +`-h|--help` + +Prints out a short help for the command. + +`--tool-path ` + +Specifies a custom location where to find global tools. PATH can be absolute or relative. Can't be combined with the `--global` option. + +## Examples + +Lists all Global Tools installed in your machine (current user profile): + +`dotnet tool list -g` + +Lists the sample Global Tools from a specific Windows folder: + +`dotnet tool list --tool-path c:\global-tools` \ No newline at end of file diff --git a/docs/core/tools/dotnet-tool-uninstall.md b/docs/core/tools/dotnet-tool-uninstall.md new file mode 100644 index 0000000000000..0beafe53d38ec --- /dev/null +++ b/docs/core/tools/dotnet-tool-uninstall.md @@ -0,0 +1,61 @@ +--- +title: dotnet tool uninstall command - .NET Core CLI +description: The dotnet tool uninstall command uninstalls the specified .NET Core Global Tool from your machine. +author: mairaw +ms.author: mairaw +ms.date: 04/25/2018 +ms.topic: article +ms.prod: .net-core +ms.technology: dotnet-cli +ms.workload: + - dotnetcore +--- +# dotnet tool uninstall + +[!INCLUDE [topic-appliesto-net-core-2-1plus.md](../../../includes/topic-appliesto-net-core-2-1plus.md)] + +## Name + +`dotnet tool uninstall` - Uninstalls the specified [.NET Core Global Tool](global-tools.md) from your machine. + +## Synopsis + +``` +dotnet tool uninstall <-g|--global> +dotnet tool uninstall <--tool-path> +dotnet tool uninstall [-h|--help] +``` + +## Description + +The `dotnet tool uninstall` command provides a way for you to uninstall .NET Core Global Tools from your machine. To use the command, you either have to specify that you want to remove a user-wide tool using the `--global` option or specify a path to where the tool is installed using the `--tool-path` option. + +## Arguments + +`PACKAGE_ID` + +ID of the NuGet package that contains the .NET Core Global tool to uninstall. + +## Options + +`-g|--global` + +Specifies that the tool to be removed is from a user-wide installation. If you don't specify this option, you must specify the `--tool-path` option. + +`-h|--help` + +Prints out a short help for the command. + +`--tool-path ` + +Specifies the location where to uninstall the global tool. PATH can be absolute or relative. Can't be combined with the `--global` option. + +## Examples + +Uninstalls the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool: + +`dotnet tool uninstall -g dotnetsay` + +Uninstalls the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool from a specific Windows folder: + +`dotnet tool uninstall dotnetsay --tool-path c:\global-tools` \ No newline at end of file diff --git a/docs/core/tools/dotnet-tool-update.md b/docs/core/tools/dotnet-tool-update.md new file mode 100644 index 0000000000000..2da004bb5ff51 --- /dev/null +++ b/docs/core/tools/dotnet-tool-update.md @@ -0,0 +1,77 @@ +--- +title: dotnet tool update command - .NET Core CLI +description: The dotnet tool update command updates the specified .NET Core Global Tool on your machine. +author: mairaw +ms.author: mairaw +ms.date: 04/25/2018 +ms.topic: article +ms.prod: .net-core +ms.technology: dotnet-cli +ms.workload: + - dotnetcore +--- +# dotnet tool update + +[!INCLUDE [topic-appliesto-net-core-2-1plus.md](../../../includes/topic-appliesto-net-core-2-1plus.md)] + +## Name + +`dotnet tool update` - Updates the specified [.NET Core Global Tool](global-tools.md) on your machine. + +## Synopsis + +``` +dotnet tool update <-g|--global> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] +dotnet tool update <--tool-path> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] +dotnet tool update [-h|--help] +``` + +## Description + +The `dotnet tool update` command provides a way for you to update .NET Core Global Tools on your machine to the latest stable version of the package. The command uninstalls and reinstalls a tool, effectively updating it. To use the command, you either have to specify that you want to update a tool from a user-wide installation using the `--global` option or specify a path to where the tool is installed using the `--tool-path` option. + +## Arguments + +`PACKAGE_ID` + +ID of the NuGet package that contains the .NET Core Global tool to update. + +## Options + +`--configfile ` + +The NuGet configuration (*nuget.config*) file to use. + +`-f|--framework ` + +Specifies the [target framework](../../standard/frameworks.md) to update the tool for. + +`-g|--global` + +Specifies that the update is for a user-wide tool. If you don't specify this option, you must specify the `--tool-path` option. + +`-h|--help` + +Prints out a short help for the command. + +`--source-feed ` + +Adds an additional NuGet package source to use during the update. + +`--tool-path ` + +Specifies the location where the global tool is installed. PATH can be absolute or relative. Can't be combined with the `--global` option. + +`-v|--verbosity ` + +Sets the verbosity level of the command. Allowed values are `q[uiet]`, `m[inimal]`, `n[ormal]`, `d[etailed]`, and `diag[nostic]`. + +## Examples + +Updates the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool: + +`dotnet tool update -g dotnetsay` + +Updates the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool located on a specific Windows folder: + +`dotnet tool update dotnetsay --tool-path c:\global-tools` \ No newline at end of file diff --git a/docs/core/tools/global-tools.md b/docs/core/tools/global-tools.md new file mode 100644 index 0000000000000..4ec6ad1a3654b --- /dev/null +++ b/docs/core/tools/global-tools.md @@ -0,0 +1,149 @@ +--- +title: .NET Core Global Tools +description: An overview of what .NET Core Global Tools are and the .NET Core CLI commands available for them. +author: KathleenDollard +ms.author: mairaw +ms.date: 04/25/2018 +ms.topic: article +ms.prod: .net-core +ms.technology: dotnet-cli +ms.workload: + - dotnetcore +--- +# .NET Core Global Tools overview + +.NET Core Global Tools are applications that are installed on your path. + +If you want to use a .NET Core Global Tool: + +* Find information about the tool (usually a website or GitHub page). +* Check the author and statistics in the home for the feed (usually NuGet.org). +* Install the tool. +* Call the tool. + +> [!IMPORTANT] +> .NET Core Global Tools appear on your path and run in full trust. Do not install .NET Core Global Tools unless you trust the author. + +## Find a .NET Core Global Tool + +Currently, there isn't a Global Tool search feature in the .NET Core CLI. + +You can find .NET Core Global Tools on [NuGet](https://www.nuget.org). However, NuGet doesn't yet allow you to search specifically for .NET Core Global Tools. + +You may also find tool recommendations in blog posts. + +## Check the author and statistics + +Since .NET Core Global Tools run in full trust and are installed on your path, they can be very powerful. Don't download tools from people you don't trust. + +If the tool is hosted on NuGet, you can check the author and statistics by searching for the tool. + +## Install a global tool + +To install a global tool, you use the [dotnet tool install](dotnet-tool-install.md) .NET Core CLI command like in the following example: + +```bash +dotnet tool install -g dotnetsay +``` + +If the tool can't be installed, error messages are displayed. Check that the feeds you expected are being checked. + +If you're trying to install a pre-release version or a specific version of the tool, you can specify the version number using the following format: + +```bash +dotnet tool install -g --version +``` + +If installation is successful, a message is displayed showing the command used to call the tool and the version installed, similar to the following example: + +``` +You can invoke the tool using the following command: dotnetsay +Tool 'dotnetsay' (version '2.0.0') was successfully installed. +``` + +Global Tools are installed in the following directories by default when you specify the `-g` (or `--global`) option: + +| OS | Path | +|-------------|-------------------------------| +| Linux/macOS | `$HOME/.dotnet/tools` | +| Windows | `%USERPROFILE%\.dotnet\tools` | + +## Use the tool + +Once the tool is installed, you can call it by using its command. Note that the command may not be the same as the package name. + +If the command is `dotnetsay`, you call it with: + +```bash +dotnetsay +``` + +If the tool author wanted the tool to appear in the context of the `dotnet` prompt, they may have written it in a way that you call it as `dotnet `, such as: + +```bash +dotnet ef +``` + +You can find which tools are included in an installed Global Tool package by listing the installed packages. + +You can also look for usage instructions at the tool's website or by typing one of the following commands: + +```bash + --help +dotnet --help +``` + +### What could go wrong + +Global Tools are shared framework applications, which means they rely on a .NET Core runtime installed on your machine. If the expected runtime is not found, they follow normal .NET Core runtime roll-forward rules such as: + +* An application rolls forward to the highest patch release of the specified major and minor version. +* If there is no matching runtime with a matching major and minor version number, the next higher minor version is used. +* Roll forward doesn't occur between preview versions of the runtime or between preview versions and release versions. + +If an application cannot find an appropriate runtime, it fails to run and reports an error. + +Another issue that might happen is that a Global Tool that was created during an earlier preview may not run with your currently installed .NET Core runtimes. You can see which runtimes are installed on your machine using the following command: + +```bash +dotnet --list-runtimes +``` + +Contact the author of the Global Tool and see if they can recompile and republish their tool package to NuGet with an updated version number. Once they have updated the package on NuGet, you can update your copy. + +The .NET Core CLI tries to add the default locations to the PATH environment variable on its first usage. However, there are a couple of scenarios where the location might not be added to PATH automatically, such as: + +* If you've set the `DOTNET_SKIP_FIRST_TIME_EXPERIENCE` environment variable. +* On macOS, if you've installed the .NET Core SDK using *.tar.gz* files and not *.pkg*. +* On Linux, you need to edit the shell environment file to configure the PATH. + +## Other CLI commands + +The .NET Core SDK contains other commands that support .NET Core Global Tools. Use any of the `dotnet tool` commands with one of the following options: + +* `--global` or `-g` specifies that the command is applicable to user-wide Global Tools. +* `--tool-path` specifies a custom location for Global Tools. + +To find out which commands are available for Global Tools: + +```bash +dotnet tool --help +``` + +Updating a Global Tool involves uninstalling and reinstalling it with the latest stable version. To update a Global Tool, use the [dotnet tool update](dotnet-tool-update.md) command: + +```bash +dotnet tool update -g +``` + +Remove a Global Tool using the [dotnet tool uninstall](dotnet-tool-uninstall.md): + +```bash +dotnet tool uninstall -g +``` + +To display all of the Global Tools currently installed on the machine, along with their version and commands, use the [dotnet tool list](dotnet-tool-list.md) command: + +```bash +dotnet tool list -g +``` \ No newline at end of file diff --git a/docs/toc.md b/docs/toc.md index b7585ebea1f97..0239d8e45b168 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -122,6 +122,7 @@ ## [.NET Core SDK Overview](core/sdk.md) ## [.NET Core CLI Tools](core/tools/index.md) ### [Telemetry](core/tools/telemetry.md) +### [Global Tools](core/tools/global-tools.md) ### [Extensibility Model](core/tools/extensibility.md) ### [Continuous Integration](core/tools/using-ci-with-cli.md) ### [Custom templates](core/tools/custom-templates.md) @@ -133,9 +134,10 @@ ### [dotnet migrate](core/tools/dotnet-migrate.md) ### [dotnet msbuild](core/tools/dotnet-msbuild.md) ### [dotnet new](core/tools/dotnet-new.md) -### [dotnet nuget delete](core/tools/dotnet-nuget-delete.md) -### [dotnet nuget locals](core/tools/dotnet-nuget-locals.md) -### [dotnet nuget push](core/tools/dotnet-nuget-push.md) +### dotnet nuget +#### [dotnet nuget delete](core/tools/dotnet-nuget-delete.md) +#### [dotnet nuget locals](core/tools/dotnet-nuget-locals.md) +#### [dotnet nuget push](core/tools/dotnet-nuget-push.md) ### [dotnet pack](core/tools/dotnet-pack.md) ### [dotnet publish](core/tools/dotnet-publish.md) ### [dotnet restore](core/tools/dotnet-restore.md) @@ -143,6 +145,11 @@ ### [dotnet sln](core/tools/dotnet-sln.md) ### [dotnet store](core/tools/dotnet-store.md) ### [dotnet test](core/tools/dotnet-test.md) +### dotnet tool +#### [dotnet tool install](core/tools/dotnet-tool-install.md) +#### [dotnet tool list](core/tools/dotnet-tool-list.md) +#### [dotnet tool uninstall](core/tools/dotnet-tool-uninstall.md) +#### [dotnet tool update](core/tools/dotnet-tool-update.md) ### [dotnet vstest](core/tools/dotnet-vstest.md) ### Project modification commands #### References diff --git a/includes/topic-appliesto-net-core-2-1plus.md b/includes/topic-appliesto-net-core-2-1plus.md new file mode 100644 index 0000000000000..625e962a44181 --- /dev/null +++ b/includes/topic-appliesto-net-core-2-1plus.md @@ -0,0 +1 @@ +**This topic applies to: ✓** .NET Core SDK 2.1 \ No newline at end of file From b3cb79dfb68e859e48eddc8502e555fb23d97254 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Wed, 25 Apr 2018 19:37:37 -0700 Subject: [PATCH 02/10] some updates --- docs/core/tools/dotnet-tool-install.md | 13 ++++++++++++- docs/core/tools/dotnet-tool-list.md | 6 +++++- docs/core/tools/dotnet-tool-uninstall.md | 6 +++++- docs/core/tools/dotnet-tool-update.md | 6 +++++- includes/topic-appliesto-net-core-2-1plus.md | 2 +- 5 files changed, 28 insertions(+), 5 deletions(-) diff --git a/docs/core/tools/dotnet-tool-install.md b/docs/core/tools/dotnet-tool-install.md index 464bc9db28986..9f0b744859a3c 100644 --- a/docs/core/tools/dotnet-tool-install.md +++ b/docs/core/tools/dotnet-tool-install.md @@ -30,6 +30,13 @@ dotnet tool install [-h|--help] The `dotnet tool install` command provides a way for you to install .NET Core Global Tools on your machine. To use the command, you either have to specify that you want a user-wide installation using the `--global` option or you specify a path to install it using the `--tool-path` option. +Global Tools are installed in the following directories by default when you specify the `-g` (or `--global`) option: + +| OS | Path | +|-------------|-------------------------------| +| Linux/macOS | `$HOME/.dotnet/tools` | +| Windows | `%USERPROFILE%\.dotnet\tools` | + ## Arguments `PACKAGE_ID` @@ -82,4 +89,8 @@ Installs the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Globa Installs version 1.0.0 of the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool: -`dotnet tool install -g dotnetsay --version 1.0.0` \ No newline at end of file +`dotnet tool install -g dotnetsay --version 1.0.0` + +## See also + +[.NET Core Global Tool](global-tools.md) \ No newline at end of file diff --git a/docs/core/tools/dotnet-tool-list.md b/docs/core/tools/dotnet-tool-list.md index 7961ecbf545ce..721c61b54a578 100644 --- a/docs/core/tools/dotnet-tool-list.md +++ b/docs/core/tools/dotnet-tool-list.md @@ -52,4 +52,8 @@ Lists all Global Tools installed in your machine (current user profile): Lists the sample Global Tools from a specific Windows folder: -`dotnet tool list --tool-path c:\global-tools` \ No newline at end of file +`dotnet tool list --tool-path c:\global-tools` + +## See also + +[.NET Core Global Tool](global-tools.md) \ No newline at end of file diff --git a/docs/core/tools/dotnet-tool-uninstall.md b/docs/core/tools/dotnet-tool-uninstall.md index 0beafe53d38ec..1f5742d10ecf4 100644 --- a/docs/core/tools/dotnet-tool-uninstall.md +++ b/docs/core/tools/dotnet-tool-uninstall.md @@ -58,4 +58,8 @@ Uninstalls the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Glo Uninstalls the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool from a specific Windows folder: -`dotnet tool uninstall dotnetsay --tool-path c:\global-tools` \ No newline at end of file +`dotnet tool uninstall dotnetsay --tool-path c:\global-tools` + +## See also + +[.NET Core Global Tool](global-tools.md) \ No newline at end of file diff --git a/docs/core/tools/dotnet-tool-update.md b/docs/core/tools/dotnet-tool-update.md index 2da004bb5ff51..7b223875c7e38 100644 --- a/docs/core/tools/dotnet-tool-update.md +++ b/docs/core/tools/dotnet-tool-update.md @@ -74,4 +74,8 @@ Updates the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Updates the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool located on a specific Windows folder: -`dotnet tool update dotnetsay --tool-path c:\global-tools` \ No newline at end of file +`dotnet tool update dotnetsay --tool-path c:\global-tools` + +## See also + +[.NET Core Global Tool](global-tools.md) \ No newline at end of file diff --git a/includes/topic-appliesto-net-core-2-1plus.md b/includes/topic-appliesto-net-core-2-1plus.md index 625e962a44181..f03fa6579a615 100644 --- a/includes/topic-appliesto-net-core-2-1plus.md +++ b/includes/topic-appliesto-net-core-2-1plus.md @@ -1 +1 @@ -**This topic applies to: ✓** .NET Core SDK 2.1 \ No newline at end of file +**This topic applies to: ✓** .NET Core SDK 2.1.300 and later versions \ No newline at end of file From 074686f3b1c08e13e25126f4c74a083cf562b2c3 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Thu, 26 Apr 2018 17:15:54 -0700 Subject: [PATCH 03/10] feedback --- docs/core/tools/dotnet-tool-install.md | 20 +++++------ docs/core/tools/dotnet-tool-list.md | 4 +-- docs/core/tools/dotnet-tool-uninstall.md | 12 +++---- docs/core/tools/dotnet-tool-update.md | 12 +++---- docs/core/tools/global-tools.md | 35 +++++++++++++++----- includes/topic-appliesto-net-core-2-1plus.md | 5 ++- 6 files changed, 54 insertions(+), 34 deletions(-) diff --git a/docs/core/tools/dotnet-tool-install.md b/docs/core/tools/dotnet-tool-install.md index 9f0b744859a3c..77e9b156fdb08 100644 --- a/docs/core/tools/dotnet-tool-install.md +++ b/docs/core/tools/dotnet-tool-install.md @@ -21,8 +21,8 @@ ms.workload: ## Synopsis ``` -dotnet tool install <-g|--global> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] [--version] -dotnet tool install <--tool-path> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] [--version] +dotnet tool install <-g|--global> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] [--version] +dotnet tool install <--tool-path> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] [--version] dotnet tool install [-h|--help] ``` @@ -39,9 +39,9 @@ Global Tools are installed in the following directories by default when you spec ## Arguments -`PACKAGE_ID` +`PACKAGE_NAME` -ID of the NuGet package that contains the .NET Core Global tool to install. +Name/ID of the NuGet package that contains the .NET Core Global tool to install. ## Options @@ -55,7 +55,7 @@ Specifies the [target framework](../../standard/frameworks.md) to install the to `-g|--global` -Specifies that the installation is user wide. If you don't specify this option, you must specify the `--tool-path` option. +Specifies that the installation is user wide. Can't be combined with the `--tool-path` option. If you don't specify this option, you must specify the `--tool-path` option. `-h|--help` @@ -67,7 +67,7 @@ Adds an additional NuGet package source to use during installation. `--tool-path ` -Specifies the location where to install the global tool. PATH can be absolute or relative. If PATH doesn't exist, the command tries to create it. Can't be combined with the `--global` option. +Specifies the location where to install the global tool. PATH can be absolute or relative. If PATH doesn't exist, the command tries to create it. Can't be combined with the `--global` option. If you don't specify this option, you must specify the `--global` option. `-v|--verbosity ` @@ -75,11 +75,11 @@ Sets the verbosity level of the command. Allowed values are `q[uiet]`, `m[inimal `--version ` -The version of the tool to install. By default, the latest stable package version is installed. +The version of the tool to install. By default, the latest stable package version is installed. Use this option to install preview or older versions of the tool. ## Examples -Installs the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool: +Installs the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool in the default location: `dotnet tool install -g dotnetsay` @@ -87,9 +87,9 @@ Installs the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Globa `dotnet tool install dotnetsay --tool-path c:\global-tools` -Installs version 1.0.0 of the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool: +Installs version 2.0.0 of the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool: -`dotnet tool install -g dotnetsay --version 1.0.0` +`dotnet tool install -g dotnetsay --version 2.0.0` ## See also diff --git a/docs/core/tools/dotnet-tool-list.md b/docs/core/tools/dotnet-tool-list.md index 721c61b54a578..56e6093594c85 100644 --- a/docs/core/tools/dotnet-tool-list.md +++ b/docs/core/tools/dotnet-tool-list.md @@ -34,7 +34,7 @@ The `dotnet tool list` command provides a way for you to list all .NET Core Glob `-g|--global` -Specifies that the tool to be removed is from a user-wide installation. If you don't specify this option, you must specify the `--tool-path` option. +Lists user-wide Global Tools. Can't be combined with the `--tool-path` option. If you don't specify this option, you must specify the `--tool-path` option. `-h|--help` @@ -42,7 +42,7 @@ Prints out a short help for the command. `--tool-path ` -Specifies a custom location where to find global tools. PATH can be absolute or relative. Can't be combined with the `--global` option. +Specifies a custom location where to find global tools. PATH can be absolute or relative. Can't be combined with the `--global` option. If you don't specify this option, you must specify the `--global` option. ## Examples diff --git a/docs/core/tools/dotnet-tool-uninstall.md b/docs/core/tools/dotnet-tool-uninstall.md index 1f5742d10ecf4..dbeec6766cfd3 100644 --- a/docs/core/tools/dotnet-tool-uninstall.md +++ b/docs/core/tools/dotnet-tool-uninstall.md @@ -21,8 +21,8 @@ ms.workload: ## Synopsis ``` -dotnet tool uninstall <-g|--global> -dotnet tool uninstall <--tool-path> +dotnet tool uninstall <-g|--global> +dotnet tool uninstall <--tool-path> dotnet tool uninstall [-h|--help] ``` @@ -32,15 +32,15 @@ The `dotnet tool uninstall` command provides a way for you to uninstall .NET Cor ## Arguments -`PACKAGE_ID` +`PACKAGE_NAME` -ID of the NuGet package that contains the .NET Core Global tool to uninstall. +Name/ID of the NuGet package that contains the .NET Core Global tool to uninstall. You can find the package name using the [dotnet tool list](dotnet-tool-list.md) command. ## Options `-g|--global` -Specifies that the tool to be removed is from a user-wide installation. If you don't specify this option, you must specify the `--tool-path` option. +Specifies that the tool to be removed is from a user-wide installation. Can't be combined with the `--tool-path` option. If you don't specify this option, you must specify the `--tool-path` option. `-h|--help` @@ -48,7 +48,7 @@ Prints out a short help for the command. `--tool-path ` -Specifies the location where to uninstall the global tool. PATH can be absolute or relative. Can't be combined with the `--global` option. +Specifies the location where to uninstall the global tool. PATH can be absolute or relative. Can't be combined with the `--global` option. If you don't specify this option, you must specify the `--global` option. ## Examples diff --git a/docs/core/tools/dotnet-tool-update.md b/docs/core/tools/dotnet-tool-update.md index 7b223875c7e38..0ec73ee94a548 100644 --- a/docs/core/tools/dotnet-tool-update.md +++ b/docs/core/tools/dotnet-tool-update.md @@ -21,8 +21,8 @@ ms.workload: ## Synopsis ``` -dotnet tool update <-g|--global> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] -dotnet tool update <--tool-path> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] +dotnet tool update <-g|--global> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] +dotnet tool update <--tool-path> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] dotnet tool update [-h|--help] ``` @@ -32,9 +32,9 @@ The `dotnet tool update` command provides a way for you to update .NET Core Glob ## Arguments -`PACKAGE_ID` +`PACKAGE_NAME` -ID of the NuGet package that contains the .NET Core Global tool to update. +Name/ID of the NuGet package that contains the .NET Core Global tool to update. You can find the package name using the [dotnet tool list](dotnet-tool-list.md) command. ## Options @@ -48,7 +48,7 @@ Specifies the [target framework](../../standard/frameworks.md) to update the too `-g|--global` -Specifies that the update is for a user-wide tool. If you don't specify this option, you must specify the `--tool-path` option. +Specifies that the update is for a user-wide tool. Can't be combined with the `--tool-path` option. If you don't specify this option, you must specify the `--tool-path` option. `-h|--help` @@ -60,7 +60,7 @@ Adds an additional NuGet package source to use during the update. `--tool-path ` -Specifies the location where the global tool is installed. PATH can be absolute or relative. Can't be combined with the `--global` option. +Specifies the location where the global tool is installed. PATH can be absolute or relative. Can't be combined with the `--global` option. If you don't specify this option, you must specify the `--global` option. `-v|--verbosity ` diff --git a/docs/core/tools/global-tools.md b/docs/core/tools/global-tools.md index 4ec6ad1a3654b..33ecdb114fd2c 100644 --- a/docs/core/tools/global-tools.md +++ b/docs/core/tools/global-tools.md @@ -12,7 +12,9 @@ ms.workload: --- # .NET Core Global Tools overview -.NET Core Global Tools are applications that are installed on your path. +[!INCLUDE [topic-appliesto-net-core-2-1plus.md](../../../includes/topic-appliesto-net-core-2-1plus.md)] + +.NET Core Global Tools are a special NuGet package that contains a console application. A Global Tool can be installed on your machine on a default location that is specified in the PATH environment variable or on a custom location. If you want to use a .NET Core Global Tool: @@ -20,27 +22,31 @@ If you want to use a .NET Core Global Tool: * Check the author and statistics in the home for the feed (usually NuGet.org). * Install the tool. * Call the tool. +* Update the tool. +* Uninstall the tool. > [!IMPORTANT] > .NET Core Global Tools appear on your path and run in full trust. Do not install .NET Core Global Tools unless you trust the author. ## Find a .NET Core Global Tool -Currently, there isn't a Global Tool search feature in the .NET Core CLI. +Currently, there isn't a Global Tool search feature in the .NET Core Command-line Interface (CLI). You can find .NET Core Global Tools on [NuGet](https://www.nuget.org). However, NuGet doesn't yet allow you to search specifically for .NET Core Global Tools. -You may also find tool recommendations in blog posts. +You may also find tool recommendations in blog posts or in the [natemcmaster/dotnet-tools](https://github.com/natemcmaster/dotnet-tools) GitHub repository. + +You can also see the source code for the Global Tools created by the ASP.NET team at the [aspnet/DotNetTools](https://github.com/aspnet/DotNetTools/) GitHub repository. ## Check the author and statistics -Since .NET Core Global Tools run in full trust and are installed on your path, they can be very powerful. Don't download tools from people you don't trust. +Since .NET Core Global Tools run in full trust and are generally installed on your path, they can be very powerful. Don't download tools from people you don't trust. If the tool is hosted on NuGet, you can check the author and statistics by searching for the tool. -## Install a global tool +## Install a Global Tool -To install a global tool, you use the [dotnet tool install](dotnet-tool-install.md) .NET Core CLI command like in the following example: +To install a Global Tool, you use the [dotnet tool install](dotnet-tool-install.md) .NET Core CLI command. The following example shows how to install a Global Tool in the default location: ```bash dotnet tool install -g dotnetsay @@ -61,13 +67,20 @@ You can invoke the tool using the following command: dotnetsay Tool 'dotnetsay' (version '2.0.0') was successfully installed. ``` -Global Tools are installed in the following directories by default when you specify the `-g` (or `--global`) option: +Global Tools can be installed in the default directory or in a specific location. The default directories are: | OS | Path | |-------------|-------------------------------| | Linux/macOS | `$HOME/.dotnet/tools` | | Windows | `%USERPROFILE%\.dotnet\tools` | +These locations are added to the user's path when the SDK is first run, so Global Tools installed there can be called directly. + +Note that the Global Tools are user-specific, not machine global. Being user-specific means you cannot install a Global Tool that is available to all users of the machine. The tool is only available for each user profile where the tool was installed. + +Global Tools can also be installed in a specific directory. When installed in a specific directory, the user must ensure the command is available, by including that directory in the path, by calling the command with the directory specified, or calling the tool from within the specified directory. +In this case, the .NET Core CLI doesn't add this location automatically to the PATH environment variable. + ## Use the tool Once the tool is installed, you can call it by using its command. Note that the command may not be the same as the package name. @@ -84,7 +97,7 @@ If the tool author wanted the tool to appear in the context of the `dotnet` prom dotnet ef ``` -You can find which tools are included in an installed Global Tool package by listing the installed packages. +You can find which tools are included in an installed Global Tool package by listing the installed packages using the [dotnet tool list](dotnet-tool-list.md) command. You can also look for usage instructions at the tool's website or by typing one of the following commands: @@ -99,7 +112,8 @@ Global Tools are shared framework applications, which means they rely on a .NET * An application rolls forward to the highest patch release of the specified major and minor version. * If there is no matching runtime with a matching major and minor version number, the next higher minor version is used. -* Roll forward doesn't occur between preview versions of the runtime or between preview versions and release versions. +* Roll forward doesn't occur between preview versions of the runtime or between preview versions and release versions. Thus, Global Tools created using preview versions must be rebuilt and republished by the author and reinstalled. +* Additional issues can occur with Global Tools created in .NET Core 2.1 Preview 1. For more information, see [.NET Core 2.1 Preview 2 Known Issues](https://github.com/dotnet/core/blob/master/release-notes/2.1/Preview/2.1.0-preview2-known-issues.md). If an application cannot find an appropriate runtime, it fails to run and reports an error. @@ -111,6 +125,9 @@ dotnet --list-runtimes Contact the author of the Global Tool and see if they can recompile and republish their tool package to NuGet with an updated version number. Once they have updated the package on NuGet, you can update your copy. +> [!WARNING] +> If you installed Global Tools that were built with .NET Core 2.1 Preview 1 release, there's a known issue where you must manually uninstall and install the tool, instead of simply updating it. If you try to update it, you'll get errors. + The .NET Core CLI tries to add the default locations to the PATH environment variable on its first usage. However, there are a couple of scenarios where the location might not be added to PATH automatically, such as: * If you've set the `DOTNET_SKIP_FIRST_TIME_EXPERIENCE` environment variable. diff --git a/includes/topic-appliesto-net-core-2-1plus.md b/includes/topic-appliesto-net-core-2-1plus.md index f03fa6579a615..084606107cf0c 100644 --- a/includes/topic-appliesto-net-core-2-1plus.md +++ b/includes/topic-appliesto-net-core-2-1plus.md @@ -1 +1,4 @@ -**This topic applies to: ✓** .NET Core SDK 2.1.300 and later versions \ No newline at end of file +**This topic applies to: ✓** .NET Core SDK 2.1.300 and later versions + +> [!NOTE] +> [This topic is pre-release documentation and is subject to change in future releases.] \ No newline at end of file From fc2a5a8050abd16d8d8c7eb52c135a8364bbbaac Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Tue, 29 May 2018 22:52:48 -0700 Subject: [PATCH 04/10] feedback --- docs/core/tools/dotnet-tool-install.md | 11 +++------- docs/core/tools/dotnet-tool-list.md | 21 +++++++++---------- docs/core/tools/dotnet-tool-uninstall.md | 17 +++++++-------- docs/core/tools/dotnet-tool-update.md | 13 ++++-------- docs/core/tools/global-tools.md | 22 +++++++------------- includes/topic-appliesto-net-core-2-1plus.md | 4 ---- includes/topic-appliesto-net-core-21plus.md | 1 + 7 files changed, 33 insertions(+), 56 deletions(-) delete mode 100644 includes/topic-appliesto-net-core-2-1plus.md create mode 100644 includes/topic-appliesto-net-core-21plus.md diff --git a/docs/core/tools/dotnet-tool-install.md b/docs/core/tools/dotnet-tool-install.md index 77e9b156fdb08..992c24adf35e8 100644 --- a/docs/core/tools/dotnet-tool-install.md +++ b/docs/core/tools/dotnet-tool-install.md @@ -3,12 +3,7 @@ title: dotnet tool install command - .NET Core CLI description: The dotnet tool install command installs the specified .NET Core Global Tool on your machine. author: mairaw ms.author: mairaw -ms.date: 04/25/2018 -ms.topic: article -ms.prod: .net-core -ms.technology: dotnet-cli -ms.workload: - - dotnetcore +ms.date: 05/29/2018 --- # dotnet tool install @@ -23,7 +18,7 @@ ms.workload: ``` dotnet tool install <-g|--global> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] [--version] dotnet tool install <--tool-path> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] [--version] -dotnet tool install [-h|--help] +dotnet tool install <-h|--help> ``` ## Description @@ -51,7 +46,7 @@ The NuGet configuration (*nuget.config*) file to use. `-f|--framework ` -Specifies the [target framework](../../standard/frameworks.md) to install the tool for. +Specifies the [target framework](../../standard/frameworks.md) to install the tool for. By default, the .NET Core SDK tries to choose the most appropriate target framework. `-g|--global` diff --git a/docs/core/tools/dotnet-tool-list.md b/docs/core/tools/dotnet-tool-list.md index 56e6093594c85..39430ca5fb122 100644 --- a/docs/core/tools/dotnet-tool-list.md +++ b/docs/core/tools/dotnet-tool-list.md @@ -3,12 +3,7 @@ title: dotnet tool list command - .NET Core CLI description: The dotnet tool list command lists the specified .NET Core Global Tool from your machine. author: mairaw ms.author: mairaw -ms.date: 04/25/2018 -ms.topic: article -ms.prod: .net-core -ms.technology: dotnet-cli -ms.workload: - - dotnetcore +ms.date: 05/29/2018 --- # dotnet tool list @@ -16,19 +11,19 @@ ms.workload: ## Name -`dotnet tool list` - Lists all [.NET Core Global Tools](global-tools.md) currently installed on your machine or specified path. +`dotnet tool list` - Lists all [.NET Core Global Tools](global-tools.md) currently installed in the default directory on your machine or in the specified path. ## Synopsis ``` dotnet tool list <-g|--global> dotnet tool list <--tool-path> -dotnet tool list [-h|--help] +dotnet tool list <-h|--help> ``` ## Description -The `dotnet tool list` command provides a way for you to list all .NET Core Global Tools installed on your machine (current user profile) or specified path. The command lists the package name, version installed, and the global tool command. To use the list command, you either have to specify that you want to see all user-wide tools using the `--global` option or specify a custom path using the `--tool-path` option. +The `dotnet tool list` command provides a way for you to list all .NET Core Global Tools installed user-wide on your machine (current user profile) or in the specified path. The command lists the package name, version installed, and the global tool command. To use the list command, you either have to specify that you want to see all user-wide tools using the `--global` option or specify a custom path using the `--tool-path` option. ## Options @@ -46,14 +41,18 @@ Specifies a custom location where to find global tools. PATH can be absolute or ## Examples -Lists all Global Tools installed in your machine (current user profile): +Lists all Global Tools installed user-wide on your machine (current user profile): `dotnet tool list -g` -Lists the sample Global Tools from a specific Windows folder: +Lists the Global Tools from a specific Windows folder: `dotnet tool list --tool-path c:\global-tools` +Lists the Global Tools from a specific Linux/macOS folder: + +`dotnet tool list --tool-path ~/bin` + ## See also [.NET Core Global Tool](global-tools.md) \ No newline at end of file diff --git a/docs/core/tools/dotnet-tool-uninstall.md b/docs/core/tools/dotnet-tool-uninstall.md index dbeec6766cfd3..78b6a6c72bc61 100644 --- a/docs/core/tools/dotnet-tool-uninstall.md +++ b/docs/core/tools/dotnet-tool-uninstall.md @@ -3,12 +3,7 @@ title: dotnet tool uninstall command - .NET Core CLI description: The dotnet tool uninstall command uninstalls the specified .NET Core Global Tool from your machine. author: mairaw ms.author: mairaw -ms.date: 04/25/2018 -ms.topic: article -ms.prod: .net-core -ms.technology: dotnet-cli -ms.workload: - - dotnetcore +ms.date: 05/29/2018 --- # dotnet tool uninstall @@ -23,7 +18,7 @@ ms.workload: ``` dotnet tool uninstall <-g|--global> dotnet tool uninstall <--tool-path> -dotnet tool uninstall [-h|--help] +dotnet tool uninstall <-h|--help> ``` ## Description @@ -52,14 +47,18 @@ Specifies the location where to uninstall the global tool. PATH can be absolute ## Examples -Uninstalls the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool: +Uninstalls the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) Global Tool: `dotnet tool uninstall -g dotnetsay` -Uninstalls the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool from a specific Windows folder: +Uninstalls the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) Global Tool from a specific Windows folder: `dotnet tool uninstall dotnetsay --tool-path c:\global-tools` +Uninstalls the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) Global Tool from a specific Linux/macOS folder: + +`dotnet tool uninstall dotnetsay --tool-path ~/bin` + ## See also [.NET Core Global Tool](global-tools.md) \ No newline at end of file diff --git a/docs/core/tools/dotnet-tool-update.md b/docs/core/tools/dotnet-tool-update.md index 0ec73ee94a548..00f9e0b45dd42 100644 --- a/docs/core/tools/dotnet-tool-update.md +++ b/docs/core/tools/dotnet-tool-update.md @@ -3,12 +3,7 @@ title: dotnet tool update command - .NET Core CLI description: The dotnet tool update command updates the specified .NET Core Global Tool on your machine. author: mairaw ms.author: mairaw -ms.date: 04/25/2018 -ms.topic: article -ms.prod: .net-core -ms.technology: dotnet-cli -ms.workload: - - dotnetcore +ms.date: 05/29/2018 --- # dotnet tool update @@ -23,7 +18,7 @@ ms.workload: ``` dotnet tool update <-g|--global> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] dotnet tool update <--tool-path> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] -dotnet tool update [-h|--help] +dotnet tool update <-h|--help> ``` ## Description @@ -68,11 +63,11 @@ Sets the verbosity level of the command. Allowed values are `q[uiet]`, `m[inimal ## Examples -Updates the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool: +Updates the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) Global Tool: `dotnet tool update -g dotnetsay` -Updates the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool located on a specific Windows folder: +Updates the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) Global Tool located on a specific Windows folder: `dotnet tool update dotnetsay --tool-path c:\global-tools` diff --git a/docs/core/tools/global-tools.md b/docs/core/tools/global-tools.md index 33ecdb114fd2c..17b95cc578f19 100644 --- a/docs/core/tools/global-tools.md +++ b/docs/core/tools/global-tools.md @@ -3,18 +3,13 @@ title: .NET Core Global Tools description: An overview of what .NET Core Global Tools are and the .NET Core CLI commands available for them. author: KathleenDollard ms.author: mairaw -ms.date: 04/25/2018 -ms.topic: article -ms.prod: .net-core -ms.technology: dotnet-cli -ms.workload: - - dotnetcore +ms.date: 05/29/2018 --- # .NET Core Global Tools overview [!INCLUDE [topic-appliesto-net-core-2-1plus.md](../../../includes/topic-appliesto-net-core-2-1plus.md)] -.NET Core Global Tools are a special NuGet package that contains a console application. A Global Tool can be installed on your machine on a default location that is specified in the PATH environment variable or on a custom location. +A .NET Core Global Tool is a special NuGet package that contains a console application. A Global Tool can be installed on your machine on a default location that is included in the PATH environment variable or on a custom location. If you want to use a .NET Core Global Tool: @@ -87,28 +82,28 @@ Once the tool is installed, you can call it by using its command. Note that the If the command is `dotnetsay`, you call it with: -```bash +```console dotnetsay ``` If the tool author wanted the tool to appear in the context of the `dotnet` prompt, they may have written it in a way that you call it as `dotnet `, such as: -```bash -dotnet ef +```console +dotnet doc ``` You can find which tools are included in an installed Global Tool package by listing the installed packages using the [dotnet tool list](dotnet-tool-list.md) command. You can also look for usage instructions at the tool's website or by typing one of the following commands: -```bash +```console --help dotnet --help ``` ### What could go wrong -Global Tools are shared framework applications, which means they rely on a .NET Core runtime installed on your machine. If the expected runtime is not found, they follow normal .NET Core runtime roll-forward rules such as: +Global Tools are [framework-dependent applications](../deploying/index.md#framework-dependent-deployments-fdd), which means they rely on a .NET Core runtime installed on your machine. If the expected runtime is not found, they follow normal .NET Core runtime roll-forward rules such as: * An application rolls forward to the highest patch release of the specified major and minor version. * If there is no matching runtime with a matching major and minor version number, the next higher minor version is used. @@ -125,9 +120,6 @@ dotnet --list-runtimes Contact the author of the Global Tool and see if they can recompile and republish their tool package to NuGet with an updated version number. Once they have updated the package on NuGet, you can update your copy. -> [!WARNING] -> If you installed Global Tools that were built with .NET Core 2.1 Preview 1 release, there's a known issue where you must manually uninstall and install the tool, instead of simply updating it. If you try to update it, you'll get errors. - The .NET Core CLI tries to add the default locations to the PATH environment variable on its first usage. However, there are a couple of scenarios where the location might not be added to PATH automatically, such as: * If you've set the `DOTNET_SKIP_FIRST_TIME_EXPERIENCE` environment variable. diff --git a/includes/topic-appliesto-net-core-2-1plus.md b/includes/topic-appliesto-net-core-2-1plus.md deleted file mode 100644 index 084606107cf0c..0000000000000 --- a/includes/topic-appliesto-net-core-2-1plus.md +++ /dev/null @@ -1,4 +0,0 @@ -**This topic applies to: ✓** .NET Core SDK 2.1.300 and later versions - -> [!NOTE] -> [This topic is pre-release documentation and is subject to change in future releases.] \ No newline at end of file diff --git a/includes/topic-appliesto-net-core-21plus.md b/includes/topic-appliesto-net-core-21plus.md new file mode 100644 index 0000000000000..f03fa6579a615 --- /dev/null +++ b/includes/topic-appliesto-net-core-21plus.md @@ -0,0 +1 @@ +**This topic applies to: ✓** .NET Core SDK 2.1.300 and later versions \ No newline at end of file From 3b1867234c338e8d132dc8d11d81145132c79d3a Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Tue, 29 May 2018 23:03:43 -0700 Subject: [PATCH 05/10] fix link test --- docs/core/tools/dotnet-tool-install.md | 2 +- docs/core/tools/dotnet-tool-list.md | 2 +- docs/core/tools/dotnet-tool-uninstall.md | 2 +- docs/core/tools/dotnet-tool-update.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/core/tools/dotnet-tool-install.md b/docs/core/tools/dotnet-tool-install.md index 992c24adf35e8..3c6285d1f6ce8 100644 --- a/docs/core/tools/dotnet-tool-install.md +++ b/docs/core/tools/dotnet-tool-install.md @@ -88,4 +88,4 @@ Installs version 2.0.0 of the [dotnetsay](https://www.nuget.org/packages/dotnets ## See also -[.NET Core Global Tool](global-tools.md) \ No newline at end of file +[.NET Core Global Tools](global-tools.md) \ No newline at end of file diff --git a/docs/core/tools/dotnet-tool-list.md b/docs/core/tools/dotnet-tool-list.md index 39430ca5fb122..e218faae7454e 100644 --- a/docs/core/tools/dotnet-tool-list.md +++ b/docs/core/tools/dotnet-tool-list.md @@ -55,4 +55,4 @@ Lists the Global Tools from a specific Linux/macOS folder: ## See also -[.NET Core Global Tool](global-tools.md) \ No newline at end of file +[.NET Core Global Tools](global-tools.md) \ No newline at end of file diff --git a/docs/core/tools/dotnet-tool-uninstall.md b/docs/core/tools/dotnet-tool-uninstall.md index 78b6a6c72bc61..a0454fb9709da 100644 --- a/docs/core/tools/dotnet-tool-uninstall.md +++ b/docs/core/tools/dotnet-tool-uninstall.md @@ -61,4 +61,4 @@ Uninstalls the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) Global Too ## See also -[.NET Core Global Tool](global-tools.md) \ No newline at end of file +[.NET Core Global Tools](global-tools.md) \ No newline at end of file diff --git a/docs/core/tools/dotnet-tool-update.md b/docs/core/tools/dotnet-tool-update.md index 00f9e0b45dd42..edeef0dcf3d8f 100644 --- a/docs/core/tools/dotnet-tool-update.md +++ b/docs/core/tools/dotnet-tool-update.md @@ -73,4 +73,4 @@ Updates the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) Global Tool l ## See also -[.NET Core Global Tool](global-tools.md) \ No newline at end of file +[.NET Core Global Tools](global-tools.md) \ No newline at end of file From fc7c2b594cfca5bf20bab61e7e9accc647ce8e0a Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Tue, 29 May 2018 23:05:35 -0700 Subject: [PATCH 06/10] added linux/mac samples --- docs/core/tools/dotnet-tool-install.md | 10 +++++++--- docs/core/tools/dotnet-tool-update.md | 4 ++++ 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/core/tools/dotnet-tool-install.md b/docs/core/tools/dotnet-tool-install.md index 3c6285d1f6ce8..554c16ff689c1 100644 --- a/docs/core/tools/dotnet-tool-install.md +++ b/docs/core/tools/dotnet-tool-install.md @@ -74,15 +74,19 @@ The version of the tool to install. By default, the latest stable package versio ## Examples -Installs the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool in the default location: +Installs the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) Global Tool in the default location: `dotnet tool install -g dotnetsay` -Installs the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool on a specific Windows folder: +Installs the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) Global Tool on a specific Windows folder: `dotnet tool install dotnetsay --tool-path c:\global-tools` -Installs version 2.0.0 of the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool: +Installs the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) Global Tool on a specific Linux/macOS folder: + +`dotnet tool install dotnetsay --tool-path ~/bin` + +Installs version 2.0.0 of the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) Global Tool: `dotnet tool install -g dotnetsay --version 2.0.0` diff --git a/docs/core/tools/dotnet-tool-update.md b/docs/core/tools/dotnet-tool-update.md index edeef0dcf3d8f..ef2b6557a507b 100644 --- a/docs/core/tools/dotnet-tool-update.md +++ b/docs/core/tools/dotnet-tool-update.md @@ -71,6 +71,10 @@ Updates the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) Global Tool l `dotnet tool update dotnetsay --tool-path c:\global-tools` +Updates the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) Global Tool located on a specific Linux/macOS folder: + +`dotnet tool update dotnetsay --tool-path ~/bin` + ## See also [.NET Core Global Tools](global-tools.md) \ No newline at end of file From ce44d50a9912fd694b01cd814d42c8a5a3b70d0e Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Tue, 29 May 2018 23:07:27 -0700 Subject: [PATCH 07/10] consistent capitalization --- docs/core/tools/dotnet-tool-install.md | 4 ++-- docs/core/tools/dotnet-tool-list.md | 4 ++-- docs/core/tools/dotnet-tool-uninstall.md | 4 ++-- docs/core/tools/dotnet-tool-update.md | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/core/tools/dotnet-tool-install.md b/docs/core/tools/dotnet-tool-install.md index 554c16ff689c1..15900bc2bb9e9 100644 --- a/docs/core/tools/dotnet-tool-install.md +++ b/docs/core/tools/dotnet-tool-install.md @@ -36,7 +36,7 @@ Global Tools are installed in the following directories by default when you spec `PACKAGE_NAME` -Name/ID of the NuGet package that contains the .NET Core Global tool to install. +Name/ID of the NuGet package that contains the .NET Core Global Tool to install. ## Options @@ -62,7 +62,7 @@ Adds an additional NuGet package source to use during installation. `--tool-path ` -Specifies the location where to install the global tool. PATH can be absolute or relative. If PATH doesn't exist, the command tries to create it. Can't be combined with the `--global` option. If you don't specify this option, you must specify the `--global` option. +Specifies the location where to install the Global Tool. PATH can be absolute or relative. If PATH doesn't exist, the command tries to create it. Can't be combined with the `--global` option. If you don't specify this option, you must specify the `--global` option. `-v|--verbosity ` diff --git a/docs/core/tools/dotnet-tool-list.md b/docs/core/tools/dotnet-tool-list.md index e218faae7454e..1e88957fc9eaf 100644 --- a/docs/core/tools/dotnet-tool-list.md +++ b/docs/core/tools/dotnet-tool-list.md @@ -23,7 +23,7 @@ dotnet tool list <-h|--help> ## Description -The `dotnet tool list` command provides a way for you to list all .NET Core Global Tools installed user-wide on your machine (current user profile) or in the specified path. The command lists the package name, version installed, and the global tool command. To use the list command, you either have to specify that you want to see all user-wide tools using the `--global` option or specify a custom path using the `--tool-path` option. +The `dotnet tool list` command provides a way for you to list all .NET Core Global Tools installed user-wide on your machine (current user profile) or in the specified path. The command lists the package name, version installed, and the Global Tool command. To use the list command, you either have to specify that you want to see all user-wide tools using the `--global` option or specify a custom path using the `--tool-path` option. ## Options @@ -37,7 +37,7 @@ Prints out a short help for the command. `--tool-path ` -Specifies a custom location where to find global tools. PATH can be absolute or relative. Can't be combined with the `--global` option. If you don't specify this option, you must specify the `--global` option. +Specifies a custom location where to find Global Tools. PATH can be absolute or relative. Can't be combined with the `--global` option. If you don't specify this option, you must specify the `--global` option. ## Examples diff --git a/docs/core/tools/dotnet-tool-uninstall.md b/docs/core/tools/dotnet-tool-uninstall.md index a0454fb9709da..05f91f9f775b1 100644 --- a/docs/core/tools/dotnet-tool-uninstall.md +++ b/docs/core/tools/dotnet-tool-uninstall.md @@ -29,7 +29,7 @@ The `dotnet tool uninstall` command provides a way for you to uninstall .NET Cor `PACKAGE_NAME` -Name/ID of the NuGet package that contains the .NET Core Global tool to uninstall. You can find the package name using the [dotnet tool list](dotnet-tool-list.md) command. +Name/ID of the NuGet package that contains the .NET Core Global Tool to uninstall. You can find the package name using the [dotnet tool list](dotnet-tool-list.md) command. ## Options @@ -43,7 +43,7 @@ Prints out a short help for the command. `--tool-path ` -Specifies the location where to uninstall the global tool. PATH can be absolute or relative. Can't be combined with the `--global` option. If you don't specify this option, you must specify the `--global` option. +Specifies the location where to uninstall the Global Tool. PATH can be absolute or relative. Can't be combined with the `--global` option. If you don't specify this option, you must specify the `--global` option. ## Examples diff --git a/docs/core/tools/dotnet-tool-update.md b/docs/core/tools/dotnet-tool-update.md index ef2b6557a507b..00525f783094a 100644 --- a/docs/core/tools/dotnet-tool-update.md +++ b/docs/core/tools/dotnet-tool-update.md @@ -29,7 +29,7 @@ The `dotnet tool update` command provides a way for you to update .NET Core Glob `PACKAGE_NAME` -Name/ID of the NuGet package that contains the .NET Core Global tool to update. You can find the package name using the [dotnet tool list](dotnet-tool-list.md) command. +Name/ID of the NuGet package that contains the .NET Core Global Tool to update. You can find the package name using the [dotnet tool list](dotnet-tool-list.md) command. ## Options @@ -55,7 +55,7 @@ Adds an additional NuGet package source to use during the update. `--tool-path ` -Specifies the location where the global tool is installed. PATH can be absolute or relative. Can't be combined with the `--global` option. If you don't specify this option, you must specify the `--global` option. +Specifies the location where the Global Tool is installed. PATH can be absolute or relative. Can't be combined with the `--global` option. If you don't specify this option, you must specify the `--global` option. `-v|--verbosity ` From 276b41de1e41c7ca31e3ed0c9da3eb868b251a01 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Tue, 29 May 2018 23:16:05 -0700 Subject: [PATCH 08/10] fixed include path --- docs/core/tools/dotnet-tool-install.md | 2 +- docs/core/tools/dotnet-tool-list.md | 2 +- docs/core/tools/dotnet-tool-uninstall.md | 2 +- docs/core/tools/dotnet-tool-update.md | 2 +- docs/core/tools/global-tools.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/core/tools/dotnet-tool-install.md b/docs/core/tools/dotnet-tool-install.md index 15900bc2bb9e9..9e3a54d8cff6f 100644 --- a/docs/core/tools/dotnet-tool-install.md +++ b/docs/core/tools/dotnet-tool-install.md @@ -7,7 +7,7 @@ ms.date: 05/29/2018 --- # dotnet tool install -[!INCLUDE [topic-appliesto-net-core-2-1plus.md](../../../includes/topic-appliesto-net-core-2-1plus.md)] +[!INCLUDE [topic-appliesto-net-core-21plus.md](../../../includes/topic-appliesto-net-core-21plus.md)] ## Name diff --git a/docs/core/tools/dotnet-tool-list.md b/docs/core/tools/dotnet-tool-list.md index 1e88957fc9eaf..bf3bb6b3976e7 100644 --- a/docs/core/tools/dotnet-tool-list.md +++ b/docs/core/tools/dotnet-tool-list.md @@ -7,7 +7,7 @@ ms.date: 05/29/2018 --- # dotnet tool list -[!INCLUDE [topic-appliesto-net-core-2-1plus.md](../../../includes/topic-appliesto-net-core-2-1plus.md)] +[!INCLUDE [topic-appliesto-net-core-21plus.md](../../../includes/topic-appliesto-net-core-21plus.md)] ## Name diff --git a/docs/core/tools/dotnet-tool-uninstall.md b/docs/core/tools/dotnet-tool-uninstall.md index 05f91f9f775b1..1a335a5f49ca8 100644 --- a/docs/core/tools/dotnet-tool-uninstall.md +++ b/docs/core/tools/dotnet-tool-uninstall.md @@ -7,7 +7,7 @@ ms.date: 05/29/2018 --- # dotnet tool uninstall -[!INCLUDE [topic-appliesto-net-core-2-1plus.md](../../../includes/topic-appliesto-net-core-2-1plus.md)] +[!INCLUDE [topic-appliesto-net-core-21plus.md](../../../includes/topic-appliesto-net-core-21plus.md)] ## Name diff --git a/docs/core/tools/dotnet-tool-update.md b/docs/core/tools/dotnet-tool-update.md index 00525f783094a..6840500709c11 100644 --- a/docs/core/tools/dotnet-tool-update.md +++ b/docs/core/tools/dotnet-tool-update.md @@ -7,7 +7,7 @@ ms.date: 05/29/2018 --- # dotnet tool update -[!INCLUDE [topic-appliesto-net-core-2-1plus.md](../../../includes/topic-appliesto-net-core-2-1plus.md)] +[!INCLUDE [topic-appliesto-net-core-21plus.md](../../../includes/topic-appliesto-net-core-21plus.md)] ## Name diff --git a/docs/core/tools/global-tools.md b/docs/core/tools/global-tools.md index 17b95cc578f19..7a5b192306ddf 100644 --- a/docs/core/tools/global-tools.md +++ b/docs/core/tools/global-tools.md @@ -7,7 +7,7 @@ ms.date: 05/29/2018 --- # .NET Core Global Tools overview -[!INCLUDE [topic-appliesto-net-core-2-1plus.md](../../../includes/topic-appliesto-net-core-2-1plus.md)] +[!INCLUDE [topic-appliesto-net-core-21plus.md](../../../includes/topic-appliesto-net-core-21plus.md)] A .NET Core Global Tool is a special NuGet package that contains a console application. A Global Tool can be installed on your machine on a default location that is included in the PATH environment variable or on a custom location. From 65c06251c1b850a9fae0b4abbab7cce6610c5f02 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Tue, 29 May 2018 23:37:44 -0700 Subject: [PATCH 09/10] command updates --- docs/core/tools/dotnet-tool-install.md | 14 +++++++------- docs/core/tools/dotnet-tool-update.md | 14 +++++++------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/core/tools/dotnet-tool-install.md b/docs/core/tools/dotnet-tool-install.md index 9e3a54d8cff6f..64cbdc11535a5 100644 --- a/docs/core/tools/dotnet-tool-install.md +++ b/docs/core/tools/dotnet-tool-install.md @@ -16,8 +16,8 @@ ms.date: 05/29/2018 ## Synopsis ``` -dotnet tool install <-g|--global> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] [--version] -dotnet tool install <--tool-path> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] [--version] +dotnet tool install <-g|--global> [--add-source] [--configfile] [--framework] [-v|--verbosity] [--version] +dotnet tool install <--tool-path> [--add-source] [--configfile] [--framework] [-v|--verbosity] [--version] dotnet tool install <-h|--help> ``` @@ -40,11 +40,15 @@ Name/ID of the NuGet package that contains the .NET Core Global Tool to install. ## Options +`--add-source ` + +Adds an additional NuGet package source to use during installation. + `--configfile ` The NuGet configuration (*nuget.config*) file to use. -`-f|--framework ` +`--framework ` Specifies the [target framework](../../standard/frameworks.md) to install the tool for. By default, the .NET Core SDK tries to choose the most appropriate target framework. @@ -56,10 +60,6 @@ Specifies that the installation is user wide. Can't be combined with the `--tool Prints out a short help for the command. -`--source-feed ` - -Adds an additional NuGet package source to use during installation. - `--tool-path ` Specifies the location where to install the Global Tool. PATH can be absolute or relative. If PATH doesn't exist, the command tries to create it. Can't be combined with the `--global` option. If you don't specify this option, you must specify the `--global` option. diff --git a/docs/core/tools/dotnet-tool-update.md b/docs/core/tools/dotnet-tool-update.md index 6840500709c11..bb9dc5c2c3f2c 100644 --- a/docs/core/tools/dotnet-tool-update.md +++ b/docs/core/tools/dotnet-tool-update.md @@ -16,8 +16,8 @@ ms.date: 05/29/2018 ## Synopsis ``` -dotnet tool update <-g|--global> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] -dotnet tool update <--tool-path> [--configfile] [-f|--framework] [--source-feed] [-v|--verbosity] +dotnet tool update <-g|--global> [--configfile] [--framework] [-v|--verbosity] +dotnet tool update <--tool-path> [--configfile] [--framework] [-v|--verbosity] dotnet tool update <-h|--help> ``` @@ -33,11 +33,15 @@ Name/ID of the NuGet package that contains the .NET Core Global Tool to update. ## Options +`--add-source ` + +Adds an additional NuGet package source to use during installation. + `--configfile ` The NuGet configuration (*nuget.config*) file to use. -`-f|--framework ` +`--framework ` Specifies the [target framework](../../standard/frameworks.md) to update the tool for. @@ -49,10 +53,6 @@ Specifies that the update is for a user-wide tool. Can't be combined with the `- Prints out a short help for the command. -`--source-feed ` - -Adds an additional NuGet package source to use during the update. - `--tool-path ` Specifies the location where the Global Tool is installed. PATH can be absolute or relative. Can't be combined with the `--global` option. If you don't specify this option, you must specify the `--global` option. From 414102bf671a3cdf6b36dc6bda7a7eded97f346e Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Wed, 30 May 2018 01:47:13 -0700 Subject: [PATCH 10/10] updates what's new --- docs/core/tools/global-tools.md | 14 ++++++------- docs/core/whats-new/dotnet-core-2-1.md | 28 +++++++++++++------------- 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/core/tools/global-tools.md b/docs/core/tools/global-tools.md index 7a5b192306ddf..8d9dd8d23e1db 100644 --- a/docs/core/tools/global-tools.md +++ b/docs/core/tools/global-tools.md @@ -43,7 +43,7 @@ If the tool is hosted on NuGet, you can check the author and statistics by searc To install a Global Tool, you use the [dotnet tool install](dotnet-tool-install.md) .NET Core CLI command. The following example shows how to install a Global Tool in the default location: -```bash +```console dotnet tool install -g dotnetsay ``` @@ -51,7 +51,7 @@ If the tool can't be installed, error messages are displayed. Check that the fee If you're trying to install a pre-release version or a specific version of the tool, you can specify the version number using the following format: -```bash +```console dotnet tool install -g --version ``` @@ -114,7 +114,7 @@ If an application cannot find an appropriate runtime, it fails to run and report Another issue that might happen is that a Global Tool that was created during an earlier preview may not run with your currently installed .NET Core runtimes. You can see which runtimes are installed on your machine using the following command: -```bash +```console dotnet --list-runtimes ``` @@ -135,24 +135,24 @@ The .NET Core SDK contains other commands that support .NET Core Global Tools. U To find out which commands are available for Global Tools: -```bash +```console dotnet tool --help ``` Updating a Global Tool involves uninstalling and reinstalling it with the latest stable version. To update a Global Tool, use the [dotnet tool update](dotnet-tool-update.md) command: -```bash +```console dotnet tool update -g ``` Remove a Global Tool using the [dotnet tool uninstall](dotnet-tool-uninstall.md): -```bash +```console dotnet tool uninstall -g ``` To display all of the Global Tools currently installed on the machine, along with their version and commands, use the [dotnet tool list](dotnet-tool-list.md) command: -```bash +```console dotnet tool list -g ``` \ No newline at end of file diff --git a/docs/core/whats-new/dotnet-core-2-1.md b/docs/core/whats-new/dotnet-core-2-1.md index e048bb0644b74..4dec5d6514918 100644 --- a/docs/core/whats-new/dotnet-core-2-1.md +++ b/docs/core/whats-new/dotnet-core-2-1.md @@ -3,7 +3,7 @@ title: What's new in .NET Core 2.1 description: Learn about the new features found in .NET Core 2.1. author: rpetrusha ms.author: ronpet -ms.date: 05/07/2018 +ms.date: 05/30/2018 --- # What's new in .NET Core 2.1 @@ -14,7 +14,7 @@ ms.date: 05/07/2018 - [Deployment](#deployment) - [Windows Compatibility Pack](#windows-compatibility-pack) - [JIT compiler improvements](#jit-compiler-improvements) -- [API changes](#api-changes) +- [API changes](#api-changes) ## Tooling @@ -52,19 +52,19 @@ A number of tools that were available only on a per project basis using [`Dotnet - `dotnet sql-cache` creates a table and indexes in a Microsoft SQL Server database to be used for distributed caching. -- `dotnet ef` is a tool for managing databases, objects, and migrations in Entity Framework Core applications. For more information, see [EF Core .NET Command-line Tools](/ef/core/miscellaneous/cli/dotnet) +- `dotnet ef` is a tool for managing databases, objects, and migrations in Entity Framework Core applications. For more information, see [EF Core .NET Command-line Tools](/ef/core/miscellaneous/cli/dotnet). -### Global tools +### Global Tools -.NET Core 2.1 supports *global tools* -- that is, custom tools that are available globally from the command line. The extensibility model in previous versions of .NET Core made custom tools available on a per project basis only by using [`DotnetCliToolReference`](../tools/extensibility.md). +.NET Core 2.1 supports *Global Tools* -- that is, custom tools that are available globally from the command line. The extensibility model in previous versions of .NET Core made custom tools available on a per project basis only by using [`DotnetCliToolReference`](../tools/extensibility.md#consuming-per-project-tools). -To install a global tool, you use the `dotnet tool install -g ` command. For example: +To install a Global Tool, you use the [dotnet tool install](..\tools\dotnet-tool-install.md) command. For example: ```console dotnet tool install -g dotnetsay ``` -Once installed, the tool can be run from the command line by specifying the tool name. +Once installed, the tool can be run from the command line by specifying the tool name. For more information, see [.NET Core Global Tools overview](../tools/global-tools.md). ### Single-source tool management with the `dotnet tool` command @@ -80,7 +80,7 @@ In .NET Core 2.1, all tools operations use the `dotnet tool` command. The follow All .NET Core applications starting with the .NET Core 2.0 automatically roll forward to the latest *minor version* installed on a system. That is, if the .NET Core version that an application was built with is not present, the application runs against the latest installed minor version. In other words, if an application is built with .NET Core 2.0 and .NET Core 2.0 itself is not present on the host system but .NET Core 2.1 is, the application runs with .NET Core 2.1. -> [!IMPORTANT] +> [!IMPORTANT] > This roll-forward behavior doesn't apply to preview releases. Nor does it apply to major releases. For example, a .NET Core 1.0 application wouldn't roll forward to .NET Core 2.0 or .NET Core 2.1. You can also disable minor version roll forward in any of three ways: @@ -129,7 +129,7 @@ You can test tiered compilation with a .NET Core 2.1 app by setting the followin COMPlus_TieredCompilation="1" ``` -## API changes +## API changes ### `Span` and `Memory` @@ -143,7 +143,7 @@ Without these types, when passing such items as a portion of an array or a secti The following example uses a instance to provide a virtual view of 10 elements of an array. -[!CODE-csharp[Span](~/samples/core/whats-new/whats-new-in-21/cs/program.cs)] +[!CODE-csharp[Span\](~/samples/core/whats-new/whats-new-in-21/cs/program.cs)] ### Brotli compression @@ -151,7 +151,7 @@ The following example uses a instance to provide a virtua [!CODE-csharp[Brotli compression](~/samples/core/whats-new/whats-new-in-21/cs/brotli.cs#1)] -The behavior is the same as and , which makes it easy to convert code that calls these APIs to . +The behavior is the same as and , which makes it easy to convert code that calls these APIs to . ### New cryptography APIs and cryptography improvements @@ -165,11 +165,11 @@ The behavior is the same as has improved by about 15% by using a -based implementation. -- The new class includes two new methods: +- The new class includes two new methods: - - takes a fixed amount of time to return for any two inputs of the same length, which makes it suitable for use in cryptographic verification to avoid contributing to timing side-channel information. + - takes a fixed amount of time to return for any two inputs of the same length, which makes it suitable for use in cryptographic verification to avoid contributing to timing side-channel information. - - is a memory-clearing routine that cannot be optimized. + - is a memory-clearing routine that cannot be optimized. - The static method fills a with random values.