如何管理 .NET 工具

项目
07/25/2023

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

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

作为全局工具。

工具二进制文件安装在添加到 PATH 环境变量的默认目录中。无需指定工具位置即可从计算机上的任何目录调用该工具。工具的一个版本用于计算机上的所有目录。
作为自定义位置中的全局工具（也称为工具路径工具）。

工具二进制文件安装在你指定的位置中。可以通过提供具有命令名称的目录从安装目录调用该工具，也可以将目录添加到 PATH 环境变量来调用该工具。工具的一个版本用于计算机上的所有目录。
作为本地工具（适用于 .NET Core SDK 3.0 及更高版本）。

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

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

重要

.NET 工具在完全信任环境中运行。除非你信任工具作者，否则请勿安装 .NET 工具。

如果通过 Snap 安装 .NET，.NET 工具可能无法正常工作。

查找工具

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

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

查看作者和统计信息

.NET 工具的功能十分强大，因为它们在完全信任的环境中运行，并且全局工具已添加到 PATH 环境变量中。请勿下载不信任的人提供的工具。

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

安装全局工具

若要将工具作为全局工具安装，请使用 dotnet tool install 的 -g 或 --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.

注意

默认情况下，要安装的 .NET 二进制文件的体系结构表示当前运行的 OS 体系结构。若要指定不同的 OS 体系结构，请参阅 dotnet tool install, --arch option。

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

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

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

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

安装自定义位置中的全局工具

若要将工具作为自定义位置中的全局工具安装，请使用 dotnet tool install 的 --tool-path 选项，如以下示例中所示：

在 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 tool install 命令并省略 --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 tool list 命令：

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 tool list <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 tool uninstall 命令卸载工具：

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

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

获取帮助和疑难解答

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

dotnet tool --help

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

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

通过