Управление инструментами .NET

Эта статья относится к пакету ✔️ SDK для .NET Core 2.1 и более поздним версиям.

Средство .NET — это специальный пакет NuGet, содержащий консольное приложение. Вы можете установить средство на компьютере следующим образом:

• Как глобальный инструмент.

  Двоичные файлы инструментов устанавливаются в каталог по умолчанию, который добавляется в переменную среды PATH. Средство можно вызвать из любого каталога на компьютере, не указывая его расположение. Одна версия средства используется для всех каталогов на компьютере.

• Как глобальное средство в пользовательском расположении (также называемое инструментом пути к инструменту).

  Двоичные файлы инструментов устанавливаются в указанное расположение. Средство можно вызвать из каталога установки, указав каталог с именем команды или добавив каталог в переменную среды PATH. Одна версия средства используется для всех каталогов на компьютере.

• Как локальное средство (применяется к пакету SDK для .NET Core версии 3.0 и более поздних версий).

  Двоичные файлы инструментов устанавливаются в каталог по умолчанию. Средство можно вызвать из каталога установки или любого из его подкаталогов. Разные каталоги могут использовать разные версии одного и того же средства.

  Интерфейс командной строки .NET использует файлы манифеста для отслеживания средств, установленных как локальные в каталоге. Если файл манифеста сохраняется в корневом каталоге репозитория исходного кода, участник может клонировать репозиторий и вызвать одну команду .NET CLI, чтобы установить все средства, перечисленные в файлах манифеста.

Поиск инструмента

Ниже приведены некоторые способы поиска средств.

• Используйте команду поиска dotnet tool , чтобы найти инструмент, опубликованный в NuGet.org.
• Используйте фильтр типа пакета .NET для поиска веб-сайта NuGet . Дополнительные сведения см. в разделе Поиск и выбор пакетов.
• См. исходный код средств, созданных командой ASP.NET Core, созданной в каталоге Tools репозитория dotnet/aspnetcore GitHub.
• Узнайте о средствах диагностики в средствах диагностики .NET.

Проверка автора и статистики

Средства .NET могут быть мощными, так как они выполняются в полном доверии, а глобальные средства добавляются в переменную среды PATH. Не скачивайте средства из людей, которым вы не доверяете.

Если средство размещено в NuGet, вы можете проверить автора и статистику, выполнив поиск средства.

Установка глобального инструмента

Чтобы установить средство в качестве глобального инструмента, используйте -g или --global параметр установки dotnet, как показано в следующем примере:

dotnet tool install -g dotnetsay

В выходных данных показана команда, используемая для вызова средства и установленной версии, как показано в следующем примере:

You can invoke the tool using the following command: dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.

Расположение двоичных файлов средства по умолчанию зависит от операционной системы:

Это расположение добавляется в путь пользователя при первом запуске пакета SDK. Таким образом, глобальные средства можно вызывать из любого каталога без указания расположения инструмента.

Доступ к инструменту является определенным пользователем, а не глобальным компьютером. Глобальное средство доступно только пользователю, который установил это средство.

Установка глобального инструмента в пользовательском расположении

Чтобы установить средство в качестве глобального инструмента в пользовательском расположении, используйте --tool-path параметр установки dotnet tool, как показано в следующих примерах:

В Windows:

dotnet tool install dotnetsay --tool-path c:\dotnet-tools

В Linux или macOS:

dotnet tool install dotnetsay --tool-path ~/bin

Пакет SDK для .NET не добавляет это расположение автоматически в переменную среды PATH. Чтобы вызвать средство пути к инструменту, необходимо убедиться, что команда доступна с помощью одного из следующих методов:

• Добавьте каталог установки в переменную среды PATH.
• Укажите полный путь к инструменту при его вызове.
• Вызовите средство из каталога установки.

Установка локального средства

Применяется к пакету SDK для .NET Core 3.0 и более поздних версий.

Если вы хотите установить средство для локального доступа (только для текущего каталога и подкаталогов), необходимо добавить средство в файл манифеста средства. Чтобы создать файл манифеста средства, выполните dotnet new tool-manifest команду:

dotnet new tool-manifest

Эта команда создает файл манифеста с именемdotnet-tools.json в каталоге .config . Чтобы добавить локальное средство в файл манифеста, используйте команду установки средства dotnet и опустите--global--tool-path параметры, как показано в следующем примере:

dotnet tool install dotnetsay

Выходные данные команды показывают, в каком файле манифеста присутствует только что установленное средство, аналогично следующему примеру:

You can invoke the tool from this directory using the following command:
dotnet tool run dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.
Entry is added to the manifest file /home/name/botsay/.config/dotnet-tools.json.

В следующем примере показан файл манифеста с двумя установленными локальными средствами:

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    },
    "dotnetsay": {
      "version": "2.1.3",
      "commands": [
        "dotnetsay"
      ]
    }
  }
}

Обычно локальное средство добавляется в корневой каталог репозитория. После возврата файла манифеста в репозиторий разработчики, которые извлекли код из репозитория, получают последний файл манифеста. Чтобы установить все средства, перечисленные в файле манифеста, они выполняют dotnet tool restore команду:

dotnet tool restore

Выходные данные указывают на восстановленные средства:

Tool 'botsay' (version '1.0.0') was restored. Available commands: botsay
Tool 'dotnetsay' (version '2.1.3') was restored. Available commands: dotnetsay
Restore was successful.

Установка определенной версии средства

Чтобы установить предварительную версию или определенную версию средства, укажите номер версии с помощью --version параметра, как показано в следующем примере:

dotnet tool install dotnetsay --version 2.1.3

Чтобы установить предварительную версию средства без указания точного номера версии, используйте --version параметр и укажите подстановочный знак, как показано в следующем примере:

dotnet tool install --global dotnetsay --version "*-rc*"

Использование средства

Команда, используемая для вызова средства, может отличаться от имени устанавливаемого пакета. Чтобы отобразить все средства, установленные на компьютере для текущего пользователя, используйте команду списка инструментов dotnet :

dotnet tool list

Выходные данные показывают версию и команду каждого средства, как показано в следующем примере:

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
botsay          1.0.0        botsay         /home/name/repository/.config/dotnet-tools.json
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

Как показано в предыдущем примере, в списке показаны локальные инструменты. Чтобы просмотреть глобальные --global инструменты, используйте этот параметр. Чтобы просмотреть средства пути к инструменту --tool-path , используйте этот параметр.

Чтобы вывести список определенных инструментов, используйте команду dotnet tool list <PACKAGE_ID> :

dotnet tool list dotnetsay

Выходные данные будут отображаться только в том случае, если он установлен, как показано в следующем примере:

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

Вызов глобального инструмента

Для глобальных средств используйте самую команду средства. Например, если команда имеет или dotnet-docиспользуется dotnetsay для вызова глобального средства:

dotnetsay
dotnet-doc

Если команда начинается с префикса dotnet-, альтернативный способ вызова средства — использовать dotnet команду и опустить префикс команды средства. Например, если команда задана dotnet-doc, следующая команда вызывает средство:

dotnet doc

Однако в следующем сценарии нельзя использовать dotnet команду для вызова глобального средства:

• Глобальное средство и локальное средство имеют одинаковые префиксы dotnet-команды.
• Вы хотите вызвать глобальное средство из каталога, который находится в области локального инструмента.

В этом сценарии dotnet doc и dotnet dotnet-doc вызов локального средства. Чтобы вызвать глобальное средство, используйте команду самостоятельно:

dotnet-doc

Вызов средства для пути к инструменту

Чтобы вызвать глобальное средство, установленное с помощью tool-path параметра, убедитесь, что команда доступна, как описано ранее в этой статье.

Вызов локального средства

Чтобы вызвать локальное средство, необходимо использовать dotnet команду из каталога установки. Можно использовать длинную форму (dotnet tool run <COMMAND_NAME>) или короткую форму (dotnet <COMMAND_NAME>), как показано в следующих примерах:

dotnet tool run dotnetsay
dotnet dotnetsay

Если команда префиксирована dotnet-, можно включить или опустить префикс при вызове средства. Например, если команда имеет значение dotnet-doc, любой из следующих примеров вызывает локальное средство:

dotnet tool run dotnet-doc
dotnet dotnet-doc
dotnet doc

Обновление средства

Обновление средства включает удаление и переустановку с помощью последней стабильной версии. Чтобы обновить средство, используйте команду обновления средства dotnet с тем же параметром, который использовался для установки средства:

dotnet tool update --global <packagename>
dotnet tool update --tool-path <packagename>
dotnet tool update <packagename>

Для локального средства пакет SDK выглядит в текущем каталоге и родительских каталогах, чтобы найти первый файл манифеста, содержащий идентификатор пакета. Если такой идентификатор пакета отсутствует в любом файле манифеста, пакет SDK добавляет новую запись в ближайший файл манифеста.

Удаление средства

Удалите средство с помощью команды удаления dotnet с тем же параметром, который использовался для установки средства:

dotnet tool uninstall --global <packagename>
dotnet tool uninstall --tool-path <packagename>
dotnet tool uninstall <packagename>

Для локального средства пакет SDK выглядит в текущем каталоге и родительских каталогах, чтобы найти первый файл манифеста, содержащий идентификатор пакета.

Получение справки и устранения неполадок

Если средство не удается установить или запустить, см. статью "Устранение неполадок с использованием средства .NET". Список доступных dotnet tool команд и параметров можно получить с помощью --help параметра:

dotnet tool --help

Чтобы получить инструкции по использованию инструментов, введите одну из следующих команд или просмотрите веб-сайт средства:

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

См. также

• Руководство. Создание средства .NET с помощью .NET CLI
• Руководство. Установка и использование глобального средства .NET с помощью .NET CLI
• Руководство. Установка и использование локального средства .NET с помощью .NET CLI