Устранение неполадок при использовании средств .NET

  • Статья

При попытке установить или запустить глобальное или локальное средство .NET могут возникнуть проблемы. В этой статье описываются их типичные первопричины и возможные решения.

Установленное средство .NET не запускается

Если средство .NET не запускается, наиболее вероятной причиной является одна из следующих:

Исполняемый файл не найден

Если исполняемый файл не найден, появляется примерно следующее сообщение.

Could not execute because the specified command or file was not found.
Possible reasons for this include:
  * You misspelled a built-in dotnet command.
  * You intended to execute a .NET program, but dotnet-xyz does not exist.
  * You intended to run a global tool, but a dotnet-prefixed executable with this name could not be found on the PATH.

Имя исполняемого файла определяет то, как вызывается средство. Формат описывается в приведенной ниже таблице.

Формат имени исполняемого файла Формат вызова
dotnet-<toolName>.exe dotnet <toolName>
<toolName>.exe <toolName>

Глобальные средства

Глобальные средства можно установить в каталоге по умолчанию или в выбранном вами расположении. Каталоги по умолчанию:

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

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

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

  • используется ОС Linux, и пакет SDK для .NET установлен с помощью файлов .tar.gz, а не apt-get или rpm;
  • используется ОС macOS 10.15 "Catalina" или более поздней версии;
  • используется ОС macOS 10.14 "Mojave" или более ранней версии, и пакет SDK для .NET установлен с помощью файлов .tar.gz, а не .pkg;
  • установлен пакет SDK для .NET Core 3.0, и переменной среды DOTNET_ADD_GLOBAL_TOOLS_TO_PATH присвоено значение false;
  • установлен пакет SDK для пакет SDK.NET Core 2.2 или более ранней версии, и переменной среды DOTNET_SKIP_FIRST_TIME_EXPERIENCE присвоено значение true.

В этих сценариях или --tool-pathпри установке средстваPATH dotnet переменная среды на компьютере не содержит автоматически путь, по которому установлен глобальный инструмент. В этом случае необходимо добавить в переменную среды PATH расположение этого средства (например, $HOME/.dotnet/tools) с использованием любого метода обновления переменных среды, предусмотренного в вашей оболочке. Дополнительные сведения см. в разделе о средствах .NET.

Локальные средства

Если вы пытаетесь запустить локальное средство, убедитесь в наличии файла манифеста с именем dotnet-tools.json в текущем каталоге или в любом из его родительских каталогов. Этот файл также может находиться в папке .config где угодно в иерархии папок проекта, а не в корневой папке. Если файл dotnet-tools.json существует, откройте его и проверьте наличие средства, которое вы пытаетесь запустить. Если в файле нет записи для "isRoot": true, также проверьте наличие дополнительных файлов манифестов средств выше в иерархии файлов.

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

..\<toolDirectory>\dotnet-<toolName>

Среда выполнения не найдена

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

  • Накат выполняется к последнему номеру выпуска исправления указанной основной и дополнительной версии.
  • Если соответствующая среда выполнения с соответствующими номерами основной и дополнительной версий отсутствует, используется следующий последний дополнительный номер версии.
  • Накат не выполняется между предварительными версиями среды выполнения или между предварительной версией и версией выпуска. Таким образом, средства .NET, созданные с помощью предварительных версий, должны быть перестроены и повторно опубликованы автором, а затем переустановлены.

Накат не выполняется по умолчанию в двух распространенных сценариях:

  • доступны только более ранние версии среды выполнения; при накате выбираются только более поздние версии среды выполнения;
  • доступны только более поздние основные версии среды выполнения. При накате границы основной версии не пересекаются.

Если приложению не удается найти подходящую среду выполнения, оно не запускается и сообщает об ошибке.

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

dotnet --list-runtimes
dotnet --info

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

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

Не удается установить средство .NET

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

Tool '{0}' failed to install. This failure may have been caused by:

* You are attempting to install a preview release and did not use the --version option to specify the version.
* A package by this name was found, but it was not a .NET tool.
* The required NuGet feed cannot be accessed, perhaps because of an Internet connection problem.
* You mistyped the name of the tool.

For more reasons, including package naming enforcement, visit https://aka.ms/failure-installing-tool

Помимо предыдущего сообщения, пользователю также выводятся сообщения NuGet, помогающие диагностировать эти сбои. Сообщение NuGet может помочь определить причину проблемы.

Изменение имен пакетов

Корпорация Майкрософт изменила правила в отношении идентификаторов пакетов для средств, из-за чего некоторые средства теперь невозможно найти по прежним именам. Новое руководство заключается в том, что все средства Майкрософт должны быть префиксированы с помощью "Майкрософт". Этот префикс зарезервирован и может использоваться только для пакетов, подписанных с помощью авторизованного сертификата Майкрософт.

Во время перехода некоторые средства Майкрософт будут иметь старую форму идентификатора пакета, а другие — новую форму:

dotnet tool install -g Microsoft.<toolName>
dotnet tool install -g <toolName>

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

Предварительные выпуски

  • Вы пытаетесь установить предварительный выпуск и не использовали параметр --version для указания версии.

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

dotnet tool install -g --version 1.1.0-pre <toolName>

Пакет не является средством .NET

  • Пакет NuGet с таким именем найден, но не является средством .NET.

При попытке установить пакет NuGet, который является обычным пакетом NuGet, а не средством .NET, вы увидите такое сообщение об ошибке:

NU1212: недопустимое сочетание пакетов проекта для <toolName>. Стиль проекта DotnetToolReference допускает только ссылки типа DotnetTool.

Веб-канал NuGet недоступен

  • Не удается получить доступ к требуемому веб-каналу NuGet, возможно, из-за проблемы с подключением к Интернету.

Для установки средства требуется доступ к веб-каналу NuGet, содержащему пакет средства. Установка завершается сбоем, если этот веб-канал недоступен. Вы можете изменить веб-каналы с помощью nuget.config, запросить определенный файл nuget.config или указать дополнительные веб-каналы с помощью параметра --add-source. По умолчанию NuGet выдает ошибку для каждого веб-канала, к которому не удается подключиться. Флаг --ignore-failed-sources позволяет пропускать недоступные источники.

Неправильный идентификатор пакета

  • Вы неправильно ввели имя средства.

Распространенной причиной ошибок является неправильное имя средства. Такое может случаться из-за ошибок при вводе или из-за того, что средство было перемещено либо устарело. Если средство размещено на сайте NuGet.org, один из способов гарантировать правильность имени — выполнить поиск средства на сайте NuGet.org и скопировать команду установки.

401 (Не авторизовано)

Скорее всего, вы указали альтернативный канал NuGet, и этот канал требует проверки подлинности. Вот несколько разных способов решить проблему:

  • Добавьте параметр --ignore-failed-sources, чтобы обойти ошибку из закрытого канала и использовать общедоступный канал Майкрософт.

    Если вы устанавливаете средство из канала Microsoft NuGet, пользовательский канал возвращает эту ошибку, прежде чем канал Microsoft NuGet вернет результат. Ошибка завершает запрос, отменяя любые другие ожидающие запросы канала, который может быть каналом Microsoft NuGet. Добавление параметра --ignore-failed-sources приводит к тому, что команда обрабатывает эту ошибку как предупреждение и позволяет другим каналам обработать запрос.

    dotnet tool install -g --ignore-failed-sources <toolName>

  • Принудительно используйте канал Microsoft NuGet с параметром --add-source.

    Возможно, в глобальном или локальном файле конфигурации NuGet отсутствует общедоступный канал Microsoft NuGet. Используйте сочетание параметров --add-source и --ignore-failed-sources, чтобы избежать ошибочного канала и использовать общедоступный веб-канал Майкрософт.

    dotnet tool install -g --add-source 'https://api.nuget.org/v3/index.json' --ignore-failed-sources <toolName>

  • Используйте настраиваемую конфигурацию NuGet, параметр --configfile <FILE>.

    Создайте локальный файл nuget.config, используя только общедоступный веб-канал Microsoft NuGet, и сошлитесь на него с помощью параметра --configfile:

    dotnet tool install -g --configfile "./nuget.config" <toolName>

    Пример файла конфигурации:

    <?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
  </packageSources>
</configuration>

    Дополнительные сведения см. в справочнике по файлу nuget.config.

  • Добавьте необходимые учетные данные в файл конфигурации.

    Если пакет точно существует в настроенном веб-канале, укажите учетные данные для входа в файле конфигурации NuGet. Дополнительные сведения об учетных данных в файле конфигурации NuGet см. в разделе packageSourceCredentials в справочнике по nuget.config.

См. также