排查 .NET 工具使用情况问题

尝试安装或运行 .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，并且是通过 .tar.gz 文件安装了 .NET SDK，而不是使用 apt-get 或 rpm。
• 如果使用 macOS 10.15“Catalina”或更高版本。
• 如果使用的是 macOS 10.14“Mojave”或更低版本，并且已使用 .tar.gz 文件（而非 .pkg）安装 .NET SDK。
• 如果已安装 .NET Core 3.0 SDK，并且已将 DOTNET_ADD_GLOBAL_TOOLS_TO_PATH 环境变量设置为 false。
• 如果已安装 .NET Core 2.2 SDK 或早期版本，并且已将 DOTNET_SKIP_FIRST_TIME_EXPERIENCE 环境变量设置为 true。

在这些方案中，或者如果在安装 dotnet 工具 时指定了 --tool-path 选项，则计算机上的 PATH 环境变量不会自动包含安装全局工具的路径。 在这种情况下，请使用 shell 为更新环境变量提供的任何方法将工具位置（例如，$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 下载页。

如果将 .NET SDK 安装到非默认位置，则需要将环境变量 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 源
• 包 ID 错误
• 401 （未经授权）

包命名规则的强制执行

Microsoft更改了关于工具包ID的指导方针，导致许多工具无法以预期的名称找到。 新指南是，所有Microsoft工具都以“Microsoft”为前缀。此前缀是保留的，只能用于使用Microsoft授权证书签名的包。

在转换期间，某些 Microsoft 工具将使用包 ID 的旧格式，而其他工具将使用新格式。

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

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

预览版本

• 你尝试安装预览版，但未使用 --version 选项指定版本。

必须使用名称的一部分指定处于预览状态的 .NET 工具，以指示它们处于预览状态。 无需包含整个预览版。 假设版本号采用预期格式，则可以使用类似于以下示例的内容：

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

包不是 .NET 工具

• 找到此名称的 NuGet 包，但它不是 .NET 工具。

如果您尝试安装的 NuGet 包是常规的 NuGet 包，而不是 .NET 工具，则可能会遇到类似以下的错误：

NU1212：<toolName> 的项目包组合无效。 DotnetToolReference 项目样式只能包含 DotnetTool 类型的引用。

无法访问 NuGet 源

• 无法访问必需的 NuGet 源，这可能是由 Internet 连接问题造成的。

工具安装需要访问包含工具包的 NuGet 源。 如果源不可用，则安装将失败。 可以使用 nuget.config更改馈送、请求特定的 nuget.config 文件，或使用 --add-source 开关指定其他馈送。 默认情况下，对于无法连接的任何源，NuGet 都将引发错误。 标志 --ignore-failed-sources 可以跳过这些无法访问的源。

包 ID 不正确

• 你错误地键入了工具的名称。

失败的一个常见原因是工具名称不正确。 这可能由于输入错误，或者因为工具已被移动或弃用。 要确保在 NuGet.org 上使用工具的名称正确，其中一种方法是先在 NuGet.org 上搜索该工具，然后复制其安装命令。

401 （未授权）

很可能已指定备用 NuGet 源，并且该源需要身份验证。 可通过几种不同的方法来解决此问题：

• 添加 --ignore-failed-sources 参数以忽略专用源中的错误并使用公共 Microsoft 源。

  如果您从 Microsoft NuGet 源安装工具，那么在 Microsoft 的 NuGet 源返回结果之前，您的自定义源就会返回此错误。 该错误将终止请求，从而取消任何其他等待中的源请求，其中可能包括 Microsoft 的 NuGet 源。 添加 --ignore-failed-sources 选项会导致命令将此错误视为警告，并允许其他源处理请求。

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

• 利用 --add-source 参数强制使用 Microsoft NuGet 源。

  全局或本地 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> 参数。

  仅使用公共 Microsoft NuGet 源创建本地 nuget.config 文件，并使用 --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 配置文件中凭据的更多信息，请参阅 nuget.config 参考中的 packageSourceCredentials 部分。

另请参阅

• .NET 工具