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

Статья
01/29/2025

Могут возникнуть проблемы при попытке установить или запустить средство .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`
Виндоус	`%USERPROFILE%\.dotnet\tools`

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

Интерфейс командной строки .NET пытается добавить расположение по умолчанию в переменную среды 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 для .NET Core 2.2 или более ранние версии, и вы установили для переменной среды DOTNET_SKIP_FIRST_TIME_EXPERIENCE значение true.

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

принудительное применение именования пакетов
Предварительные версии
пакет не является средством .NET
фид NuGet недоступен
неверный идентификатор пакета
401 (Неавторизованный)

Обеспечение соблюдения правил именования пакетов

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

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

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 возвращает результат. Ошибка завершает запрос, отменяя любые другие ожидающие запросы на получение данных, которые могут относиться к фидам NuGet от Microsoft. При добавлении параметра --ignore-failed-sources команда обрабатывает эту ошибку как предупреждение и позволяет другим веб-каналам обрабатывать запрос.
```
dotnet tool install -g --ignore-failed-sources <toolName>
```
Принудительная передача ленты Microsoft NuGet с параметром --add-source.

Возможно, в глобальном или локальном файле конфигурации NuGet отсутствует общественный репозиторий Microsoft NuGet. Используйте сочетание параметров --add-source и --ignore-failed-sources, чтобы избежать ошибочного канала и полагаться на общедоступный канал Microsoft.
```
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.

См. также

средства .NET

Поделиться через