如何管理 .NET 工具

本文适用于： ✔️.NET Core 2.1 SDK 及更高版本。

.NET 工具是包含控制台应用程序的特殊 NuGet 包。 可以通过以下方式在计算机上安装工具：

• 作为全局工具。

  工具二进制文件安装在添加到 PATH 环境变量的默认目录中。 可以从计算机上的任何目录中调用该工具，而无需指定其位置。 工具的一个版本用于计算机上的所有目录。

• 作为自定义位置（也称为工具路径工具）中的全局工具。

  工具二进制文件安装在指定的位置。 可以通过向目录提供命令名称或将目录添加到 PATH 环境变量，从安装目录中调用该工具。 工具的一个版本用于计算机上的所有目录。

• 作为本地工具（适用于 .NET Core SDK 3.0 及更高版本）。

  工具二进制文件安装在默认目录中。 可以从安装目录或其任何子目录中调用该工具。 不同的目录可以使用相同工具的不同版本。

  .NET CLI 使用清单文件跟踪作为目录本地安装的工具。 当清单文件保存在源代码存储库的根目录中时，参与者可以克隆存储库并调用单个 .NET CLI 命令来安装清单文件中列出的所有工具。

查找工具

下面是查找工具的一些方法：

• 使用 dotnet 工具搜索 命令查找发布到 NuGet.org 的工具。
• 使用“.NET 工具”包类型筛选器搜索 NuGet 网站。 有关详细信息，请参阅查找和选择包。
• 请参阅 在 dotnet/aspnetcore GitHub 存储库的工具目录中创建 ASP.NET 核心团队的工具的源代码。
• 了解 .NET 诊断工具的诊断工具。

检查作者和统计信息

.NET 工具可能很强大，因为它们完全信任运行，并且全局工具将添加到 PATH 环境变量。 不要从不信任的人员下载工具。

如果该工具托管在 NuGet 上，可以通过搜索该工具来检查作者和统计信息。

安装全局工具

若要将工具安装为全局工具，请使用 -gdotnet 工具安装的或--global选项，如以下示例所示：

dotnet tool install -g dotnetsay

输出显示用于调用该工具和已安装的版本的命令，类似于以下示例：

You can invoke the tool using the following command: dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.

工具二进制文件的默认位置取决于作系统：

首次运行 SDK 时，此位置将添加到用户的路径。 因此，可以从任何目录中调用全局工具，而无需指定工具位置。

工具访问权限特定于用户，而不是计算机全局访问。 全局工具仅适用于安装该工具的用户。

在自定义位置安装全局工具

若要在自定义位置将工具安装为全局工具，请使用 --tool-pathdotnet 工具安装选项，如以下示例所示：

在 Windows 上：

dotnet tool install dotnetsay --tool-path c:\dotnet-tools

在 Linux 或 macOS 上：

dotnet tool install dotnetsay --tool-path ~/bin

.NET SDK 不会自动将此位置添加到 PATH 环境变量。 若要 调用工具路径工具，必须使用下列方法之一来确保命令可用：

• 将安装目录添加到 PATH 环境变量。
• 调用该工具时指定工具的完整路径。
• 从安装目录中调用该工具。

安装本地工具

适用于 .NET Core 3.0 SDK 及更高版本。

如果要仅安装用于本地访问的工具（对于当前目录和子目录），必须将该工具添加到工具清单文件。 若要创建工具清单文件，请 dotnet new tool-manifest 运行以下命令：

dotnet new tool-manifest

此命令在 .config 目录下创建一个名为 dotnet-tools.json 的清单文件。 若要将本地工具添加到清单文件，请使用 dotnet 工具安装命令并省略--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 工具列表 命令：

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 工具列表 <PACKAGE_ID> 命令：

dotnet tool list dotnetsay

输出将仅列出该工具（如果已安装），类似于以下示例：

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

调用全局工具

对于全局工具，请单独使用该工具命令。 例如，如果命令是 dotnetsay 或 dotnet-doc用于调用全局工具的命令：

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 会在当前目录和父目录中查找包含包 ID 的第一个清单文件。 如果任何清单文件中没有此类包 ID，SDK 会将新条目添加到最近的清单文件中。

卸载工具

使用 dotnet 工具卸载命令卸载 工具，该命令与用于安装该工具的选项相同：

dotnet tool uninstall --global <packagename>
dotnet tool uninstall --tool-path <packagename>
dotnet tool uninstall <packagename>

对于本地工具，SDK 会在当前目录和父目录中查找包含包 ID 的第一个清单文件。

获取帮助和故障排除

如果工具无法安装或运行，请参阅 排查 .NET 工具使用情况问题。 可以使用参数获取可用 dotnet tool 命令和参数 --help 的列表：

dotnet tool --help

若要获取工具使用说明，请输入以下命令之一或查看该工具的网站：

<command> --help
dotnet <command> --help

另请参阅

• 教程：使用 .NET CLI 创建 .NET 工具
• 教程：使用 .NET CLI 安装和使用 .NET 全局工具
• 教程：使用 .NET CLI 安装和使用 .NET 本地工具