Обзор глобальных средств .NET Core.NET Core Global Tools overview

Эта статья относится к ✓ SDK для .NET Core 2.1This article applies to: ✓ .NET Core 2.1 SDK

Глобальное средство .NET Core — это специальный пакет NuGet, который содержит консольное приложение.A .NET Core Global Tool is a special NuGet package that contains a console application. Глобальное средство можно установить на компьютере в расположении по умолчанию, которое включено в переменную среды PATH, или в другом расположении.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.

Процесс работы с глобальным средством .NET Core включает следующие этапы:If you want to use a .NET Core Global Tool:

  • поиск информации о средстве (обычно на веб-сайте или странице GitHub);Find information about the tool (usually a website or GitHub page).
  • проверку автора и статистики в корневой папке веб-канала (обычно NuGet.org);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.

Важно!

Глобальные средства .NET Core устанавливаются по выбранному вами пути и выполняются в режиме полного доверия..NET Core Global Tools appear on your path and run in full trust. Не устанавливайте глобальные средства .NET Core, если вы не доверяете автору.Do not install .NET Core Global Tools unless you trust the author.

Как найти глобальное средство .NET CoreFind a .NET Core Global Tool

В интерфейсе командной строки (CLI) .NET Core пока нет функции поиска глобальных средств.Currently, there isn't a Global Tool search feature in the .NET Core Command-line Interface (CLI).

Глобальные средства .NET Core можно найти в NuGet.You can find .NET Core Global Tools on NuGet. При этом NuGet пока не позволяет выполнять поиск конкретных глобальных средств .NET Core.However, NuGet doesn't yet allow you to search specifically for .NET Core Global Tools.

Вы можете найти рекомендации средств в записях блога или в репозитории GitHub natemcmaster/dotnet-tools.You may also find tool recommendations in blog posts or in the natemcmaster/dotnet-tools GitHub repository.

Кроме того, в репозитории GitHub aspnet/DotNetTools вам доступен исходный код для глобальных средств, созданных командой разработчиков для ASP.NET.You can also see the source code for the Global Tools created by the ASP.NET team at the aspnet/DotNetTools GitHub repository.

Проверка автора и статистикиCheck the author and statistics

Поскольку глобальные средства .NET Core выполняются в режиме полного доверия и обычно устанавливаются по заданному вами пути, они имеют большие привилегии.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.

Если средство размещается в NuGet, вы можете проверить автора и статистику, выполнив поиск средства.If the tool is hosted on NuGet, you can check the author and statistics by searching for the tool.

Установка глобального средстваInstall a Global Tool

Чтобы установить глобальное средство, используйте команду .NET Core CLI dotnet tool install.To install a Global Tool, you use the dotnet tool install .NET Core CLI command. В примере ниже показано, как установить глобальное средство в расположении по умолчанию:The following example shows how to install a Global Tool in the default location:

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:

dotnet tool install -g <package-name> --version <version-number>

Если установка выполнена успешно, отображается сообщение с командой, используемой для вызова средства, и установленной версией, аналогичное приведенному ниже: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 can be installed in the default directory or in a specific location. Каталоги по умолчанию:The default directories are:

Операционная системаOS ПутьPath
Linux/macOSLinux/macOS $HOME/.dotnet/tools
WindowsWindows %USERPROFILE%\.dotnet\tools

Эти расположения добавляются в путь пользователя при первом запуске пакета SDK, поэтому установленные в них глобальные средства можно вызывать напрямую.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. В этом случае .NET Core CLI не добавляет это расположение автоматически в переменную среды PATH.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.

Если команда — dotnetsay, она вызывается с помощью:If the command is dotnetsay, you call it with:

dotnetsay

Если автор средства предусмотрел его отображение в контексте запроса dotnet, оно может вызываться как dotnet <command>, например: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 <command>, such as:

dotnet doc

Чтобы узнать, какие средства входят в установленный пакет глобального средства, можно перечислить установленные пакеты с помощью команды dotnet tool list.You can find which tools are included in an installed Global Tool package by listing the installed packages using the dotnet tool list command.

Вы также можете найти инструкции по использованию на веб-сайте средства или выполнив одну из следующих команд:You can also look for usage instructions at the tool's website or by typing one of the following commands:

<command> --help
dotnet <command> --help

Какие проблемы могут возникнутьWhat could go wrong

Глобальные средства — это приложения, зависящие от платформы, то есть от среды выполнения .NET Core, установленной на компьютере.Global Tools are framework-dependent applications, which means they rely on a .NET Core runtime installed on your machine. Если ожидаемая среда выполнения не найдена, они следуют обычным правилам наката среды выполнения .NET Core: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. Таким образом, глобальные средства, созданные с помощью предварительных версий, должны быть перестроены и повторно опубликованы автором, а затем переустановлены.Thus, Global Tools created using preview versions must be rebuilt and republished by the author and reinstalled.
  • Дополнительные проблемы могут возникать с глобальными средствами, созданными в .NET Core 2.1 предварительной версии 1.Additional issues can occur with Global Tools created in .NET Core 2.1 Preview 1. Дополнительные сведения см. в статье, посвященной известным проблемам .NET Core 2.1 предварительной версии 2.For more information, see .NET Core 2.1 Preview 2 Known Issues.

Если приложению не удается найти подходящую среду выполнения, оно не запускается и сообщает об ошибке.If an application cannot find an appropriate runtime, it fails to run and reports an error.

Может возникать еще одна проблема, которая связана с тем, что глобальное средство, которое было создано в более ранней предварительной версии, может не поддерживать текущие установленные среды выполнения .NET Core.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:

dotnet --list-runtimes

Обратитесь к автору глобального средства и попросите его перекомпилировать и повторно опубликовать пакет средства в NuGet с обновленным номером версии.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. После обновления пакета в NuGet вы сможете обновить установленную копию.Once they have updated the package on NuGet, you can update your copy.

Интерфейс .NET Core CLI пытается добавить расположения по умолчанию в переменную среды PATH при первом использовании.The .NET Core CLI tries to add the default locations to the PATH environment variable on its first usage. Однако есть ситуации, когда расположение не удается добавить в переменную PATH автоматически, например:However, there are a couple of scenarios where the location might not be added to PATH automatically, such as:

  • вы задали переменную среды DOTNET_SKIP_FIRST_TIME_EXPERIENCE;If you've set the DOTNET_SKIP_FIRST_TIME_EXPERIENCE environment variable.
  • в macOS пакет SDK для .NET Core установлен с помощью TAR.GZ-, а не PKG-файлов;On macOS, if you've installed the .NET Core SDK using .tar.gz files and not .pkg.
  • в Linux необходимо изменить файл среды оболочки для настройки переменной PATH.On Linux, you need to edit the shell environment file to configure the PATH.

Другие команды интерфейса командной строкиOther CLI commands

Пакет SDK для .NET Core содержит другие команды, которые поддерживают глобальные средства .NET Core.The .NET Core SDK contains other commands that support .NET Core Global Tools. Все команды dotnet tool можно использовать с одним из следующих параметров:Use any of the dotnet tool commands with one of the following options:

  • --global или -g указывает, что команда применяется к глобальному средству уровня пользователя;--global or -g specifies that the command is applicable to user-wide Global Tools.
  • --tool-path задает пользовательское расположение для глобальных средств.--tool-path specifies a custom location for Global Tools.

Чтобы узнать, какие команды доступны для глобальных средств, выполните следующую команду:To find out which commands are available for Global Tools:

dotnet tool --help

Обновление глобального средства подразумевает его удаление и установку последней стабильной версии.Updating a Global Tool involves uninstalling and reinstalling it with the latest stable version. Чтобы обновить глобальное средство, используйте команду dotnet tool update:To update a Global Tool, use the dotnet tool update command:

dotnet tool update -g <packagename>

Удалите глобальное средство с помощью команды dotnet tool uninstall:Remove a Global Tool using the dotnet tool uninstall:

dotnet tool uninstall -g <packagename>

Чтобы отобразить все глобальные средства, установленные на компьютере (вместе со сведениями о версиях и командах), используйте команду dotnet tool list:To display all of the Global Tools currently installed on the machine, along with their version and commands, use the dotnet tool list command:

dotnet tool list -g