在 Visual Studio 中将 LibMan 与 ASP.NET Core 配合使用Use LibMan with ASP.NET Core in Visual Studio
- 本文内容
先决条件Prerequisites
添加库文件Add library files
- 使用“添加客户端库”对话框Use the Add Client-Side Library dialog
- 手动配置 LibMan 清单文件项Manually configure LibMan manifest file entries
还原库文件Restore library files
- 在生成过程中还原文件Restore files during build
- 手动还原文件Restore files manually
删除库文件Delete library files
卸载库文件Uninstall library files
更新库版本Update library version
其他资源Additional resources

在 Visual Studio 中将 LibMan 与 ASP.NET Core 配合使用Use LibMan with ASP.NET Core in Visual Studio

本文内容

作者：Scott Addie

Visual Studio 对 ASP.NET Core 项目中的 LibMan 提供内置支持，包括：

支持在生成时配置和运行 LibMan 还原操作。
用于触发 LibMan 还原和清理操作的菜单项。
用于查找库并将文件添加到项目的搜索对话框。
编辑对 libman.json（LibMan 清单文件）的支持。

查看或下载示例代码（如何下载）

先决条件Prerequisites

Visual Studio 2019 与 ASP.NET 和 Web 开发工作负载

添加库文件Add library files

可以通过两种不同的方式将库文件添加到 ASP.NET Core 项目中：

使用“添加客户端库”对话框
手动配置 LibMan 清单文件项

使用“添加客户端库”对话框Use the Add Client-Side Library dialog

按照以下步骤安装客户端库：

在“解决方案资源管理器”中，右键单击要在其中添加文件的项目文件夹。选择“添加” > “客户端库” 。此时将显示“添加客户端库”对话框：

从“提供程序”下拉列表中选择库提供程序。CDNJS 是默认提供程序。
在“库”文本框中键入要提取的库名称。IntelliSense 提供以所提供文本开头的库的列表。
从 IntelliSense 列表中选择库。请注意，库名称后缀带有 @ 符号和所选提供程序的已知最新稳定版本。
确定要包含的文件：
- 选择“包含所有库文件”单选按钮以包含所有库文件。
- 选择“选择特定文件”单选按钮以包含库文件的子集。选中此单选按钮后，将启用文件选择器树。选中要下载的文件名左侧的框。
在“目标位置”文本框中指定项目文件夹以存储文件。建议将每个库存储在单独的文件夹中。

建议的“目标位置”文件夹基于启动对话框的位置：

如果从项目根启动：
- 如果 wwwroot 存在，则使用 wwwroot/lib 。
- 如果 wwwroot 不存在，则使用 lib 。
如果从项目文件夹启动，则使用相应的文件夹名称。
文件夹建议带有库名称后缀。下表说明了在 Razor Pages 项目中安装 jQuery 时的文件夹建议。

启动位置建议的文件夹项目根（如果 wwwroot 存在）wwwroot/lib/jquery/ 项目根（如果 wwwroot 不存在）lib/jquery/ 项目中的 Pages 文件夹 Pages/jquery/

单击“安装”按钮，根据 libman.json 中的配置下载文件。
有关安装详细信息，请查看“输出”窗口的“库管理器”源。例如：

Restore operation started...
Restoring libraries for project LibManSample
Restoring library jquery@3.3.1... (LibManSample)
wwwroot/lib/jquery/jquery.min.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.min.map written to destination (LibManSample)
Restore operation completed
1 libraries restored in 2.32 seconds

手动配置 LibMan 清单文件项Manually configure LibMan manifest file entries

Visual Studio 中的所有 LibMan 操作都基于项目根的 LibMan 清单 (libman.json) 的内容。可以手动编辑 libman.json，以配置项目的库文件。保存 libman.json 后，Visual Studio 将还原所有库文件。

若要打开 libman.json 进行编辑，可以选择以下选项：

在“解决方案资源管理器”中双击 libman.json 文件。
右键单击“解决方案资源管理器”中的项目，然后选择“管理客户端库” 。†
从 Visual Studio“项目”菜单中选择“管理客户端库” 。†

† 如果项目根中不存在 libman.json 文件，则将使用默认项模板内容创建该文件。

Visual Studio 提供丰富的 JSON 编辑支持，如着色、格式设置、IntelliSense 和架构验证。LibMan 清单的 JSON 架构位于 https://json.schemastore.org/libman。

对于下面的清单文件，LibMan 根据 libraries 属性中定义的配置检索文件。libraries 中定义的对象文字的说明如下所示：

从 CDNJS 提供程序检索 jQuery 版本 3.3.1 的子集。子集在 files 属性中定义—jquery node.js、jquery.js 和 jquery.min.map 。文件位于项目的 wwwroot/lib/jquery 文件夹中。
检索整个启动版本 4.1.3，并放入 wwwroot/lib/bootstrap 文件夹中。对象文字的 provider 属性将覆盖 defaultProvider 属性值。LibMan 从 unpkg 提供程序检索启动文件。
组织内的管理正文已批准 Lodash 的子集。从本地文件系统 C:\temp\lodash\ 检索 lodash.js 和 lodash.min.js 文件。文件将复制到项目的 wwwroot/lib/lodash 文件夹中。

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": [
    {
      "library": "jquery@3.3.1",
      "files": [
        "jquery.min.js",
        "jquery.js",
        "jquery.min.map"
      ],
      "destination": "wwwroot/lib/jquery/"
    },
    {
      "provider": "unpkg",
      "library": "bootstrap@4.1.3",
      "destination": "wwwroot/lib/bootstrap/"
    },
    {
      "provider": "filesystem",
      "library": "C:\\temp\\lodash\\",
      "files": [
        "lodash.js",
        "lodash.min.js"
      ],
      "destination": "wwwroot/lib/lodash/"
    }
  ]
}

备注

LibMan 仅支持每个提供程序的每个库的一个版本。如果 libman.json 文件包含两个库，并且库名称与给定提供程序的库名称相同，则架构验证失败。

还原库文件Restore library files

若要从 Visual Studio 中还原库文件，项目根中必须有一个有效的 libman.json 文件。还原的文件放置在项目中每个库指定的位置。

可以通过两种方式在 ASP.NET Core 项目中还原库文件：

在生成过程中还原文件
手动还原文件

在生成过程中还原文件Restore files during build

LibMan 可以在生成过程中还原定义的库文件。默认情况下，禁用 restore-on-build 行为。

启用和测试 restore-on-build 行为：

右键单击“解决方案资源管理器”中的 libman.json，然后从上下文菜单中选择“生成时启用还原客户端库” 。
系统提示安装 NuGet 包时，单击“是”按钮。将 Microsoft.Web.LibraryManager.Build NuGet 包添加到项目中：

<PackageReference Include="Microsoft.Web.LibraryManager.Build" Version="1.0.113" />

生成项目以确认 LibMan 文件已还原。Microsoft.Web.LibraryManager.Build 包将插入在项目的生成操作期间运行 LibMan 的 MSBuild 目标。
查看 LibMan 活动日志“输出”窗口的“生成”源：

1>------ Build started: Project: LibManSample, Configuration: Debug Any CPU ------
1>
1>Restore operation started...
1>Restoring library jquery@3.3.1...
1>Restoring library bootstrap@4.1.3...
1>
1>2 libraries restored in 10.66 seconds
1>LibManSample -> C:\LibManSample\bin\Debug\netcoreapp2.1\LibManSample.dll
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

当启用 restore-on-build 行为时，libman.json 上下文菜单将显示“生成时禁用还原客户端库”选项。选择此选项将从项目文件中删除 Microsoft.Web.LibraryManager.Build 包引用。因此，在每次生成时将不再还原客户端库。

无论 restore-on-build 设置如何，都可以随时从 libman.json 上下文菜单中手动进行还原。有关详细信息，请参阅还原文件。

手动还原文件Restore files manually

手动还原库文件：

对于解决方案中的所有项目：
- 右键单击“解决方案资源管理器”中的解决方案名称。
- 选择“还原客户端库”选项。
对于特定项目：
- 右键单击“解决方案资源管理器”中的 libman.json 文件。
- 选择“还原客户端库”选项。

正在运行还原操作时：

将对 Visual Studio 状态栏上的任务状态中心 (TSC) 图标进行动画处理，并将显示“已启动还原操作” 。单击该图标将打开一个工具提示，其中列出了已知的后台任务。
消息将发送到状态栏和“输出”窗口的“库管理器”源。例如：

Restore operation started...
Restoring libraries for project LibManSample
Restoring library jquery@3.3.1... (LibManSample)
wwwroot/lib/jquery/jquery.min.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.min.map written to destination (LibManSample)
Restore operation completed
1 libraries restored in 2.32 seconds

删除库文件Delete library files

执行清理操作，该操作将删除之前在 Visual Studio 中还原的库文件：

右键单击“解决方案资源管理器”中的 libman.json 文件。
选择“清理客户端库”选项。

为防止意外删除非库文件，清理操作不会删除整个目录。它仅删除先前还原中包含的文件。

正在运行清理操作时：

将对 Visual Studio 状态栏上的 TSC 图标进行动画处理，并将显示“已启动客户端库操作” 。单击该图标将打开一个工具提示，其中列出了已知的后台任务。
将消息发送到状态栏和“输出”窗口的“库管理器”源。例如：

Clean libraries operation started...
Clean libraries operation completed
2 libraries were successfully deleted in 1.91 secs

清理操作仅从项目中删除文件。库文件保留在缓存中，以便在将来的还原操作中更快地检索。若要管理存储在本地计算机缓存中的库文件，请使用 LibMan CLI。

卸载库文件Uninstall library files

卸载库文件：

打开 libman.json 。
将插入符号置于相应的 libraries 对象文字内。
单击左边距中显示的灯泡图标，然后选择“卸载 @” ：

或者可以手动编辑并保存 LibMan 清单 (libman.json) 。保存文件后将运行还原操作。libman.json 中不再定义的库文件将从项目中删除。

更新库版本Update library version

检查更新的库版本：

打开 libman.json 。
将插入符号置于相应的 libraries 对象文字内。
单击左边距中显示的灯泡图标。将鼠标悬停在“检查更新”上。

LibMan 检查库版本是否比安装的版本更新。可能出现以下结果：

如果已安装最新版本，则不会显示“找不到更新”消息。
如果尚未安装，则会显示最新的稳定版本。

如果有比已安装版本更新的预发行版可用，则会显示该预发行版。

若要降级到较旧的库版本，请手动编辑 libman.json 文件。保存文件后，LibMan 还原操作将执行以下操作：

删除先前版本中的冗余文件。
从新版本添加新文件和更新文件。

Visual Studio