教程：使用 .NET CLI 安装和使用 .NET 本地工具

项目
01/29/2025

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

本教程介绍如何安装和使用本地工具。使用在本系列的第一个教程中创建的工具。

先决条件

完成本系列的第一个教程。
安装 .NET Core 2.1 运行时。

在本教程中，你将安装和使用面向 .NET Core 2.1 的工具，因此需要在计算机上安装该运行时。若要安装 2.1 运行时，请转到 .NET Core 2.1 下载页，并在 “运行应用 - 运行时”列中查找运行时安装链接。

创建清单文件

若要仅安装本地访问的工具（对于当前目录和子目录），必须将其添加到清单文件中。

在 microsoft.botsay 文件夹中，向上导航到 存储库 文件夹：

cd ..

通过运行 dotnet new 命令创建清单文件：

dotnet new tool-manifest

输出说明文件成功创建。

The template "Dotnet local tool manifest file" was created successfully.

.config/dotnet-tools.json 文件中尚没有工具：

{
  "version": 1,
  "isRoot": true,
  "tools": {}
}

清单文件中列出的工具可用于当前目录和子目录。当前目录是包含清单文件的 .config 目录的目录。

使用引用本地工具的 CLI 命令时，SDK 会在当前目录和父目录中搜索清单文件。如果找到清单文件，但该文件不包含引用的工具，它会继续通过父目录进行搜索。搜索在找到引用的工具或找到将 isRoot 设置为 true的清单文件时结束。

将 botsay 安装为本地工具

请从第一个教程中创建的包中安装此工具：

dotnet tool install --add-source ./microsoft.botsay/nupkg microsoft.botsay

此命令将该工具添加到在上一步中创建的清单文件。命令输出显示新安装工具所在的清单文件：

You can invoke the tool from this directory using the following command:
'dotnet tool run botsay' or 'dotnet botsay'
Tool 'microsoft.botsay' (version '1.0.0') was successfully installed.
Entry is added to the manifest file /home/name/repository/.config/dotnet-tools.json

.config/dotnet-tools.json 文件现在有一个工具：

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "microsoft.botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    }
  }
}

使用该工具

通过从 存储库 文件夹中运行 dotnet tool run 命令来调用该工具：

dotnet tool run botsay hello from the bot

还原其他人安装的本地工具

通常，在存储库的根目录中安装本地工具。将清单文件签入存储库后，其他开发人员可以获取最新的清单文件。若要安装清单文件中列出的所有工具，可以运行单个 dotnet tool restore 命令。

打开 .config/dotnet-tools.json 文件，并将内容替换为以下 JSON：

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "microsoft.botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    },
    "dotnetsay": {
      "version": "2.1.3",
      "commands": [
        "dotnetsay"
      ]
    }
  }
}

保存更改。

进行此更改就像在其他人安装了项目目录中的包 dotnetsay 之后，从存储库获取最新版本一样。

运行 dotnet tool restore 命令。

dotnet tool restore

该命令生成如下例所示的输出：

Tool 'microsoft.botsay' (version '1.0.0') was restored. Available commands: botsay
Tool 'dotnetsay' (version '2.1.3') was restored. Available commands: dotnetsay
Restore was successful.

验证工具是否可用：

dotnet tool list

输出是包和命令的列表，类似于以下示例：

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

测试工具：

dotnet tool run dotnetsay hello from dotnetsay
dotnet tool run botsay hello from botsay

更新本地工具

本地工具 dotnetsay 的已安装版本为 2.1.3。使用 dotnet 工具更新命令将该工具更新到最新版本。

dotnet tool update dotnetsay

输出指示新的版本号：

Tool 'dotnetsay' was successfully updated from version '2.1.3' to version '2.1.7'
(manifest file /home/name/repository/.config/dotnet-tools.json).

update 命令查找包含包 ID 的第一个清单文件并对其进行更新。如果在搜索范围内的任何清单文件中没有此类包 ID，SDK 会将一个新条目添加到最近的清单文件中。搜索范围向上穿过父目录，直到找到具有 isRoot = true 的清单文件。

删除本地工具

通过运行命令 dotnet tool uninstall 来移除已安装的工具：

dotnet tool uninstall microsoft.botsay

dotnet tool uninstall dotnetsay

故障排除

如果在遵循本教程时收到错误消息，请参阅排查 .NET 工具使用问题。

另请参阅

有关详细信息，请参阅 .NET 工具。

通过