在 Visual Studio 中搭配 ASP.NET Core 使用 LibMan

發行項
01/28/2023

作者：Scott Addie

Visual Studio 在 ASP.NET Core 專案中具有LibMan的內建支援，包括：

支援在建置時設定和執行 LibMan 還原作業。
觸發 LibMan 還原和清除作業的功能表項目。
搜尋對話方塊以尋找程式庫，並將檔案新增至專案。
編輯的支援 libman.json — LibMan 資訊清單檔案。

檢視或下載範例程式碼 (如何下載)

必要條件

具有ASP.NET 和 Web 開發工作負載的Visual Studio 2019

新增程式庫檔案

程式庫檔案可以透過兩種不同的方式新增至 ASP.NET Core專案：

使用 [新增Client-Side程式庫] 對話方塊
手動設定 LibMan 資訊清單檔專案

使用 [新增Client-Side程式庫] 對話方塊

請遵循下列步驟來安裝用戶端程式庫：

在方案總管中，以滑鼠右鍵按一下應該在其中新增檔案的專案資料夾。選擇[新增>用戶端程式庫]。 [ 新增Client-Side程式庫 ] 對話方塊隨即出現：
從 [ 提供者 ] 下拉式清單中選取程式庫提供者。 CDN JS 是預設提供者。
在 [程式庫] 文字方塊中輸入要擷取的連結庫名稱。 IntelliSense 提供以所提供文字開頭的程式庫清單。
從 IntelliSense 清單中選取程式庫。請注意，程式庫名稱後面會加上 @ 符號和所選提供者已知的最新穩定版本。
決定要包含哪些檔案：
- 選取 [ 包含所有程式庫檔案] 選項按鈕，以包含所有文件庫的檔案。
- 選取 [ 選擇特定檔案] 選項按鈕，以包含程式庫檔案的子集。選取選項按鈕時，會啟用檔案選取器樹狀結構。核取檔案名左邊要下載的方塊。

指定專案資料夾，以將檔案儲存在 [目標位置 ] 文字方塊中。建議將每個程式庫儲存在不同的資料夾中。

建議 的目標位置 資料夾是以對話方塊啟動的位置為基礎：

如果從專案根目錄啟動：
- 如果 wwwroot存在，則會使用wwwroot/lib。
- 如果wwwroot不存在，則會使用lib。
如果從專案資料夾啟動，則會使用對應的資料夾名稱。

資料夾建議會後綴為程式庫名稱。下表說明在 Pages 專案中安裝 jQuery Razor 時的資料夾建議。

啟動位置	建議的資料夾
如果 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 資訊清單檔專案

Visual Studio 中的所有 LibMan 作業都是以專案根目錄的 LibMan 資訊清單內容為基礎， (libman.json) 。您可以手動編輯 libman.json 來設定專案的程式庫檔案。 Visual Studio 會在儲存之後 libman.json 還原所有程式庫檔案。

若要開啟 libman.json 以進行編輯，下列選項存在：

按兩下 libman.json方案總管中的檔案。
以滑鼠右鍵按一下方案總管中的專案，然後選取[管理Client-Side程式庫]。 †
從 Visual Studio [專案] 功能表中選取[管理Client-Side程式庫]。 †

† 如果檔案 libman.json 尚未存在於專案根目錄中，則會使用預設專案範本內容來建立該檔案。

Visual Studio 提供豐富的 JS ON 編輯支援，例如色彩化、格式設定、IntelliSense 和架構驗證。 LibMan 資訊清單的 JS ON 架構位於 https://json.schemastore.org/libman 。

使用下列資訊清單檔，LibMan 會根據屬性中所 libraries 定義的組態擷取檔案。下列定義 libraries 之物件常值的說明：

jQuery 3.3.1 版的子集是從 CDN JS 提供者擷取。子集定義于 files 屬性中， jquery.min.js 也就是 jquery.js 、和 jquery.min.map。檔案會放在專案的 wwwroot/lib/jquery 資料夾中。
擷取並放置在wwwroot/lib/bootstrap資料夾中的Bootstrap 4.1.3 版。物件常值的 provider 屬性會 defaultProvider 覆寫屬性值。 LibMan 會從 unpkg 提供者擷取 Bootstrap 檔案。
Lodash的子集是由組織內的控管主體核准。和 lodash.jslodash.min.js 檔案是從 C：\temp\lodash\的本機檔案系統擷取。檔案會複製到專案的 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 就會失敗。

還原程式庫檔案

若要從 Visual Studio 內還原程式庫檔案，專案根目錄中必須有有效的 libman.json 檔案。還原的檔案會放在專案中的每個程式庫所指定的位置。

程式庫檔案可以透過兩種方式在 ASP.NET Core專案中還原：

在建置期間還原檔案
手動還原檔案

在建置期間還原檔案

LibMan 可以將定義的程式庫檔案還原為建置程式的一部分。根據預設， 還原建置 行為會停用。

若要啟用及測試建置上的還原行為：

以滑鼠右鍵按一下 libman.json方案總管，然後從操作功能表中選取 [在建置時啟用還原Client-Side程式庫]。
出現安裝 NuGet 套件的提示時，按一下 [ 是 ] 按鈕。 Microsoft.Web.LibraryManager.Build NuGet 套件會新增至專案：
```
<PackageReference Include="Microsoft.Web.LibraryManager.Build" Version="1.0.113" />
```
建置專案以確認發生 LibMan 檔案還原。封裝 Microsoft.Web.LibraryManager.Build 會插入 MSBuild 目標，以在專案的建置作業期間執行 LibMan。

檢閱 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 ==========

啟用還原建置行為時， libman.json 操作功能表會顯示 [ 在建置時停用還原Client-Side程式庫 ] 選項。選取此選項會 Microsoft.Web.LibraryManager.Build 從專案檔中移除套件參考。因此，用戶端程式庫不會再在每個組建上還原。

不論在建置時還原設定為何，您隨時都可以從 libman.json 操作功能表手動還原。如需詳細資訊，請參閱手動還原檔案。

手動還原檔案

若要手動還原程式庫檔案：

針對解決方案中的所有專案：
- 以滑鼠右鍵按一下方案總管中的方案名稱。
- 選取 [ 還原Client-Side程式庫 ] 選項。
針對特定專案：
- 以滑鼠右鍵按一下 libman.json方案總管中的檔案。
- 選取 [ 還原Client-Side程式庫 ] 選項。

還原作業執行時：

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

刪除程式庫檔案

若要執行清除作業，這會刪除先前在 Visual Studio 中還原的程式庫檔案：

以滑鼠右鍵按一下 libman.json方案總管中的檔案。
選取 [ 清除Client-Side程式庫 ] 選項。

為了避免意外移除非程式庫檔案，清除作業不會刪除整個目錄。它只會移除先前還原中包含的檔案。

當清除作業正在執行時：

Visual Studio 狀態列上的 TSC 圖示將會以動畫顯示，並讀取用戶端連結 庫作業已啟動。按一下圖示會開啟工具提示，其中列出已知的背景工作。
訊息會傳送至 [輸出] 視窗的狀態列和連結庫管理員摘要。例如：

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

清除作業只會刪除專案中的檔案。程式庫檔案會保留在快取中，以便日後還原作業的更快速擷取。若要管理儲存在本機電腦快取中的程式庫檔案，請使用 LibMan CLI。

卸載程式庫檔案

若要卸載程式庫檔案：

開啟 libman.json。
將插入號置於對應的 libraries 物件常值內。
按一下左邊界中顯示的燈泡圖示，然後選取 [卸載 < ] > library_name@ < library_version >：

或者，您也可以手動編輯並儲存 LibMan 資訊清單 (libman.json) 。還原作業會在儲存檔案時執行。已從專案中移除不再定義的 libman.json 程式庫檔案。

更新程式庫版本

若要檢查更新的程式庫版本：

開啟 libman.json。
將插入號置於對應的 libraries 物件常值內。
按一下左邊界中顯示的燈泡圖示。將滑鼠停留在 [檢查更新]上方。

LibMan 會檢查比安裝的版本還新的程式庫版本。可能會發生下列結果：

如果已安裝最新版本，則會顯示 [找不到更新 ] 訊息。
如果尚未安裝，則會顯示最新的穩定版本。
如果發行前版本比已安裝的版本還新，則會顯示發行前版本。

若要降級為較舊的程式庫版本，請手動編輯檔案 libman.json 。儲存檔案時，LibMan 還原作業：

從舊版移除備援檔案。
從新版本新增和更新的檔案。

在 Visual Studio 中搭配 ASP.NET Core 使用 LibMan

必要條件

新增程式庫檔案

使用 [新增Client-Side程式庫] 對話方塊

手動設定 LibMan 資訊清單檔專案

還原程式庫檔案

在建置期間還原檔案

手動還原檔案

刪除程式庫檔案

卸載程式庫檔案

更新程式庫版本

其他資源

其他資源

其他資源