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

  • Статья

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

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

  • Как глобальное средство.

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

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

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

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

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

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

Внимание

Средства .NET выполняются с полным доверием. Не устанавливайте средство .NET, если вы не доверяете автору.

Средства .NET могут работать неправильно, если платформа .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.

Примечание.

По умолчанию архитектура двоичных файлов .NET для установки представляет архитектуру операционной системы. Чтобы указать другую архитектуру ОС, см . параметр dotnet tool install, --arch.

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

ОС Путь
Linux/macOS $HOME/.dotnet/tools
Windows %USERPROFILE%\.dotnet\tools

Это расположение добавляется в путь пользователя при первом запуске пакета 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 tool install и omit опции --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 tool list:

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 tool update с той же опцией, что и при установке средства.

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

См. также