排查 .NET Core 工具使用问题Troubleshoot .NET Core tool usage issues

本文内容

在尝试安装或运行 .NET Core 工具（可能是全局工具，也可能是本地工具）时，可能会遇到问题。本文介绍了常见的根本原因及一些可能的解决方案。

安装的 .NET Core 工具未能运行Installed .NET Core tool fails to run

当 .NET Core 工具未能运行时，你最可能遇到下述问题之一：

  • 找不到工具的可执行文件。
  • 找不到 .NET Core 运行时的正确版本。

找不到可执行文件Executable file not found

如果找不到可执行文件，则将看到如下所示的消息：

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

可执行文件的名称决定了调用工具的方式。相关格式请参见下表：

可执行文件名称的格式调用格式
dotnet-<toolName>.exedotnet <toolName>
<toolName>.exe<toolName>
  • 全局工具

全局工具可安装在默认目录中，也可安装在特定位置中。默认目录为：

(OS)路径Linux/macOS$HOME/.dotnet/toolsWindows%USERPROFILE%.dotnet\tools

如果要尝试运行全局工具，请检查计算机上的 PATH 环境变量是否包含安装该全局工具的路径且可执行文件是否位于该路径中。

.NET Core CLI 在首次使用时尝试将默认位置添加到 PATH 环境变量。但在一些情况下，位置不会自动添加到 PATH，因此你必须编辑 PATH，针对以下情况对其进行配置：

  • 如果要使用 Linux，并且已使用 .tar.gz 文件（而非 apt-get 或 rpm）安装 .NET Core SDK 。
  • 如果使用的是 macOS 10.15“Catalina”或更高版本。
  • 如果要使用 macOS 10.14“Mojave”或更低版本，并且已使用 .tar.gz 文件（而非 .pkg）安装 .NET Core SDK 。
  • 如果已安装 .NET Core 3.0 SDK，并且已将 DOTNET_ADD_GLOBAL_TOOLS_TO_PATH 环境变量设置为 false。
  • 如果已安装 .NET Core 2.2 SDK 或更低版本，并且已将 DOTNET_SKIP_FIRST_TIME_EXPERIENCE 环境变量设置为 true。有关全局工具的详细信息，请参阅 .NET Core 全局工具概述。
  • 本地工具

如果要尝试运行本地工具，请验证当前目录或其任何父目录中是否存在一个名为 dotnet-tools.json 的清单文件 。此文件还可位于项目文件夹层次结构中任意位置的 .config 文件夹下，而不是位于根文件夹中 。如果存在 dotnet-tools.json，请将其打开，检查是否存在你要尝试运行的工具 。如果该文件不包含 "isRoot": true 的条目，则还要进一步检查文件层次结构中是否存在其他工具清单文件。

如果要尝试运行已通过指定的路径安装的 .NET Core 工具，则需要在使用该工具时包含该路径。下面是使用安装了工具路径的工具的示例：

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

找不到运行时Runtime not found

.NET Core 工具是依赖框架的应用程序，也就是说它们依赖于计算机上安装的 .NET Core 运行时。如果找不到所需的运行时，则遵循常规的 .NET Core 运行时前滚规则，例如：

  • 应用程序前滚至指定的主要版本和次要版本的最高修补程序版本。
  • 如果主要版本号和次要版本号没有匹配的运行时，则使用下一个较高的次要版本。

  • 前滚不会发生在运行时的预览版之间，也不会发生在预览版和发行版之间。因此，使用预览版创建的 .NET Core 工具必须由作者重新生成和重新发布，再重新安装。在下面两种常见场景中，默认不进行前滚：

  • 只有运行时的较低版本可用。前滚仅选择运行时的较高版本。

  • 只有运行时的较高版本可用。前滚不跨越主要版本边界。如果应用程序找不到合适的运行时，则它无法运行并报告错误。

要查看计算机上安装了哪些 .NET Core 运行时，可使用下述命令之一：

  1. dotnet --list-runtimes
  2. dotnet --info

如果你认为此工具应支持你当前安装的运行时版本，可联系工具作者，询问他们是否可更新版本号或实现多目标。在工具作者编译其工具包并使用更新后的版本号将其重新发布到 NuGet 之后，你可更新你的副本。虽然这种情况不会发生，但最快捷的解决方案是安装适合你要尝试运行的工具的运行时版本。要下载特定的 .NET Core 运行时版本，请访问 .NET Core 下载页。

如果将 .NET Core SDK 安装到非默认位置，则需要将环境变量 DOTNET_ROOT 设置到包含 dotnet 可执行文件的目录。

.NET Core 工具安装失败.NET Core tool installation fails

.NET Core 全局或本地工具安装失败的原因有很多。当工具安装失败时，你将看到如下所示的消息：

  1. Tool '{0}' failed to install. This failure may have been caused by:
  3. * You are attempting to install a preview release and did not use the --version option to specify the version.
  4. * A package by this name was found, but it was not a .NET Core tool.
  5. * The required NuGet feed cannot be accessed, perhaps because of an Internet connection problem.
  6. * You mistyped the name of the tool.
  8. For more reasons, including package naming enforcement, visit https://aka.ms/failure-installing-tool

为帮助诊断这些失败情况，会随同之前的消息直接向用户显示 NuGet 消息。NuGet 消息可帮助你确定问题。

包命名强制Package naming enforcement

Microsoft 针对工具的包 ID 更改了相关指导，导致没法用预测出的名称找到很多工具。新的指导是所有 Microsoft 工具均附上“Microsoft”这一前缀。此前缀已预留，仅用于使用 Microsoft 授权证书签名的包。

在过渡期间，一些 Microsoft 工具将采用包 ID 的旧格式，而另外一些将采用新格式：

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

更新包 ID 后，你将需要更改到新的包 ID 以获取最新更新。带简化工具名称的包将遭到弃用。

预览版本Preview releases

  • 你正在尝试安装预览版本，但未使用 —version 选项来指定该版本。必须用名称的一部分指定处于预览版状态的 .NET Core 工具，这样才能指示它们现为预览版。不需要包含整个预览版。假定版本号都采用预期的格式，则你可使用与下例类似的内容：
  1. dotnet tool install -g --version 1.1.0-pre <toolName>

备注

.NET Core CLI 正计划在未来版本中添加一个 —preview 开关来简化此操作。

包不是 .NET Core 工具Package isn't a .NET Core tool

  • 已按此名称找到 NuGet 包，但它不是 .NET Core 工具。如果尝试安装是常规 NuGet 包（而非 .NET Core 工具）的 NuGet 包，你将看到如下所示的错误：

NU1212: Invalid project-package combination for. DotnetToolReference project style can only contain references of the DotnetTool type.

无法访问 NuGet 源NuGet feed can't be accessed

  • 无法访问必需的 NuGet 源，这可能是由 Internet 连接问题造成的。需要访问包含工具包的 NuGet 源才能安装工具。如果源不可用，则安装将失败。可使用 nuget.config 修改源、请求特定的 nuget.config 文件，也可使用 —add-source 开关指定其他源。默认情况下，对于无法连接的任何源，NuGet 都将引发错误。标志 —ignore-failed-sources 可跳过这些不可访问的源。

包 ID 错误Package ID incorrect

  • 工具的名称拼写错误。常见的失败原因是工具名称不正确。原因可能是拼写错误，或者工具已移动或已被弃用。对于 NuGet.org 上的工具，确保名称正确的一种方式是在 NuGet.org 处搜索该工具并复制安装命令。

请参阅See also