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

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

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

先决条件

  • 完成本系列 的第一个教程。
  • .NET 10.0.100 SDK 或更高版本 （for dnx） - 可选但建议使用。

创建清单文件

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

在 dotnet-env 文件夹中，向上导航到 存储库 文件夹：

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的清单文件时结束。

将 dotnet-env 安装为本地工具（传统方法）

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

dotnet tool install --add-source ./dotnet-env/nupkg dotnet-env

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

You can invoke the tool from this directory using the following command:
'dotnet tool run dotnet-env' or 'dotnet dotnet-env'
Tool 'dotnet-env' (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": {
    "dotnet-env": {
      "version": "1.0.0",
      "commands": [
        "dotnet-env"
      ]
    }
  }
}

使用已安装的本地工具

安装为本地工具后，可以通过多种方式调用它：

  • 直接使用dnx运行该工具：

    dnx dotnet-env --add-source ./nupkg

    注释

    将 dnx 与本地工具清单一起使用时，它会自动使用清单中指定的版本。

  • 使用 dotnet dotnet-env：

    dotnet dotnet-env

  • 使用 dotnet tool run

    dotnet tool run dotnet-env

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

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

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

    {
  "version": 1,
  "isRoot": true,
  "tools": {
    "dotnet-env": {
      "version": "1.0.0",
      "commands": [
        "dotnet-env"
      ]
    },
    "dotnetsay": {
      "version": "2.1.3",
      "commands": [
        "dotnetsay"
      ]
    }
  }
}

  2. 保存更改。

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

  3. 运行 dotnet tool restore 命令。

    dotnet tool restore

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

    Tool 'dotnet-env' (version '1.0.0') was restored. Available commands: dotnet-env
Tool 'dotnetsay' (version '2.1.3') was restored. Available commands: dotnetsay
Restore was successful.

  4. 验证工具是否可用：

    dotnet tool list

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

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

  5. 测试工具：

    dotnet tool run dotnetsay hello from dotnetsay
dotnet tool run dotnet-env

更新本地工具

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

dotnet tool update dotnetsay

输出指示新的版本号：

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

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

删除本地工具

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

dotnet tool uninstall dotnet-env

dotnet tool uninstall dotnetsay

故障排除

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

另请参阅

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

  • Last updated on