搭配使用 LibMan CLI 與 ASP.NET Core

發行項
01/12/2024

程式庫管理員 (LibMan) 是輕量型的用戶端程式庫取得工具。 LibMan 會從檔案系統或內容傳遞網路 (CDN)下載熱門的程式庫和架構。支援的 CDN 包含 CDNJS、jsDelivr 和 unpkg。所選程式庫檔會擷取並放置在 ASP.NET Core 專案中的適當位置。

必要條件

最新的 .NET SDK

安裝

下列命令會安裝 LibMan：

dotnet tool install -g Microsoft.Web.LibraryManager.Cli

注意

根據預設，要安裝的 .NET 二進位檔架構代表目前執行的 OS 架構。若要指定不同的 OS 架構，請參閱 dotnet tool install, --arch option。如需詳細資訊，請參閱 GitHub 問題 dotnet/AspNetCore.Docs #29262。

.NET Core 全域工具是從 Microsoft.Web.LibraryManager.Cli NuGet 套件安裝的。

使用方式

libman

若要檢視已安裝的 LibMan 版本：

libman --version

若要檢視可用的 CLI 命令：

libman --help

上述命令顯示的輸出，類似如下：

 1.0.163+g45474d37ed

Usage: libman [options] [command]

Options:
  --help|-h  Show help information
  --version  Show version information

Commands:
  cache      List or clean libman cache contents
  clean      Deletes all library files defined in libman.json from the project
  init       Create a new libman.json
  install    Add a library definition to the libman.json file, and download the 
             library to the specified location
  restore    Downloads all files from provider and saves them to specified 
             destination
  uninstall  Deletes all files for the specified library from their specified 
             destination, then removes the specified library definition from 
             libman.json
  update     Updates the specified library

Use "libman [command] --help" for more information about a command.

下列各節將概述可用的 CLI 命令。

在專案中初始化 LibMan

如果檔案不存在，libman init 命令會建立 libman.json 檔案。檔案是使用預設項目範本內容建立的。

概要

libman init [-d|--default-destination] [-p|--default-provider] [--verbosity]
libman init [-h|--help]

選項。

以下是使用 libman init 命令時可用的選項：

-d|--default-destination <PATH>

相對於目前資料夾的路徑。如果 libman.json 中沒有為程式庫定義的 destination 屬性，則程式庫檔會安裝在此位置。 <PATH> 值寫入 libman.json 的 defaultDestination 屬性。
-p|--default-provider <PROVIDER>

如果沒有為指定的程式庫定義提供者，則使用該提供者。 <PROVIDER> 值寫入 libman.json 的 defaultProvider 屬性。將 <PROVIDER> 取代為下列其中一個值：
- cdnjs
- filesystem
- jsdelivr
- unpkg

-h|--help

顯示說明資訊。
--verbosity <LEVEL>

設定輸出的詳細程度。將 <LEVEL> 取代為下列其中一個值：
- quiet
- normal
- detailed

範例

若要在 ASP.NET Core 專案中建立 libman.json 檔案：

瀏覽至專案根目錄。
執行以下命令：
```
libman init
```
輸入預設提供者的名稱，或按下 Enter 以使用預設 CDNJS 提供者。有效值包括：
- cdnjs
- filesystem
- jsdelivr
- unpkg

libman.json 檔案會新增至具有下列內容的專案根目錄：

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": []
}

新增程式庫檔

libman install 命令會將程式庫檔下載並安裝到專案中。如果 libman.json 檔案不存在，則會新增該檔案。 libman.json 檔案會修改為儲存程式庫檔的設定詳細資料。

概要

libman install <LIBRARY> [-d|--destination] [--files] [-p|--provider] [--verbosity]
libman install [-h|--help]

引數

LIBRARY

要安裝的程式庫名稱。此名稱可能包含版本號碼標記法 (例如，@1.2.0)。

選項。

以下是使用 libman install 命令時可用的選項：

-d|--destination <PATH>

安裝程式庫的位置。如果未指定，則會使用預設的位置。如果未在 libman.json 中指定 defaultDestination 屬性，則需要此選項。

注意： 目的地路徑有一個限制。例如，當套件來源具有完整的項目結構，而不只是散發資料夾時，您無法指定行動資料夾。如需詳細資訊，請參閱問題 #407 和問題 #702
--files <FILE>

指定要從程式庫安裝之檔案的名稱。如果未指定，則安裝程式庫中的所有檔案。為每個要安裝的檔案提供一個 --files 選項。也支援相對路徑。例如： --files dist/browser/signalr.js 。
-p|--provider <PROVIDER>

要用於程式庫擷取的提供者名稱。將 <PROVIDER> 取代為下列其中一個值：
- cdnjs
- filesystem
- jsdelivr
- unpkg
如果未指定，則會使用 libman.json 中的 defaultProvider 屬性。如果未在 libman.json 中指定 defaultProvider 屬性，則需要此選項。

-h|--help

顯示說明資訊。
--verbosity <LEVEL>

設定輸出的詳細程度。將 <LEVEL> 取代為下列其中一個值：
- quiet
- normal
- detailed

範例

請考量下列 libman.json 檔案：

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": []
}

若要使用 CDN JS 提供者將 jQuery 3.2.1 版 jquery.min.js 檔案安裝到 wwwroot/scripts/jquery 資料夾：

libman install jquery@3.2.1 --provider cdnjs --destination wwwroot/scripts/jquery --files jquery.min.js

libman.json 檔案如下所示：

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": [
    {
      "library": "jquery@3.2.1",
      "destination": "wwwroot/scripts/jquery",
      "files": [
        "jquery.min.js"
      ]
    }
  ]
}

若要使用檔案系統提供者，從 C：\temp\contosoCalendar\ 安裝 calendar.js 和 calendar.css 檔案：

libman install C:\temp\contosoCalendar\ --provider filesystem --files calendar.js --files calendar.css

出現下列提示有兩個原因：

libman.json 檔案不包含 defaultDestination 屬性。
libman install 命令不包含 -d|--destination 選項。

libman install command - destination

接受預設目的地之後，libman.json 檔案會如下所示：

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": [
    {
      "library": "jquery@3.2.1",
      "destination": "wwwroot/scripts/jquery",
      "files": [
        "jquery.min.js"
      ]
    },
    {
      "library": "C:\\temp\\contosoCalendar\\",
      "provider": "filesystem",
      "destination": "wwwroot/lib/contosoCalendar",
      "files": [
        "calendar.js",
        "calendar.css"
      ]
    }
  ]
}

還原程式庫檔

libman restore 命令會安裝 libman.json 中定義的程式庫檔。適用的規則如下：

如果專案根目錄中沒有 libman.json 檔案，則會傳回錯誤。
如果程式庫指定提供者，則會忽略 libman.json 中的 defaultProvider 屬性。
如果程式庫指定目的地，則會忽略 libman.json 中的 defaultDestination 屬性。

概要

libman restore [--verbosity]
libman restore [-h|--help]

選項。

以下是使用 libman restore 命令時可用的選項：

-h|--help

顯示說明資訊。
--verbosity <LEVEL>

設定輸出的詳細程度。將 <LEVEL> 取代為下列其中一個值：
- quiet
- normal
- detailed

範例

若要還原 libman.json 中定義的程式庫檔：

libman restore

刪除程式庫檔

libman clean 命令刪除之前透過 LibMan 還原的程式庫檔。刪除此作業之後變成空白的資料夾。 libman.json 的 libraries 屬性中程式庫檔的相關聯組態不會被移除。

概要

libman clean [--verbosity]
libman clean [-h|--help]

選項。

以下是使用 libman clean 命令時可用的選項：

-h|--help

顯示說明資訊。
--verbosity <LEVEL>

設定輸出的詳細程度。將 <LEVEL> 取代為下列其中一個值：
- quiet
- normal
- detailed

範例

若要刪除透過 LibMan 安裝的程式庫檔：

libman clean

解除安裝程式庫檔

libman uninstall 命令：

從 libman.json 中的目的地刪除與指定程式庫相關聯的所有檔案。
從 libman.json 移除相關聯的程式庫設定。

在以下情況會發生錯誤：

專案根目錄中沒有 libman.json 檔案。
指定的程式庫不存在。

如果已安裝多個相同名稱的程式庫，則系統會提示您選擇一個。

概要

libman uninstall <LIBRARY> [--verbosity]
libman uninstall [-h|--help]

引數

LIBRARY

要解除安裝的程式庫名稱。此名稱可能包含版本號碼標記法 (例如，@1.2.0)。

選項。

以下是使用 libman uninstall 命令時可用的選項：

-h|--help

顯示說明資訊。
--verbosity <LEVEL>

設定輸出的詳細程度。將 <LEVEL> 取代為下列其中一個值：
- quiet
- normal
- detailed

範例

請考量下列 libman.json 檔案：

{
  "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/"
    }
  ]
}

若要解除安裝 jQuery，以下任一命令均會成功：
```
libman uninstall jquery
```
```
libman uninstall jquery@3.3.1
```
若要解除安裝透過 filesystem 提供者安裝的 Lodash 檔案：
```
libman uninstall C:\temp\lodash\
```

更新程式庫版本

libman update 命令會透過 LibMan 安裝的程式庫更新為指定的版本。

在以下情況會發生錯誤：

專案根目錄中沒有 libman.json 檔案。
指定的程式庫不存在。

如果已安裝多個相同名稱的程式庫，則系統會提示您選擇一個。

概要

libman update <LIBRARY> [-pre] [--to] [--verbosity]
libman update [-h|--help]

引數

LIBRARY

要更新的程式庫名稱。

選項。

以下是使用 libman update 命令時可用的選項：

-pre

取得程式庫的最新發行前版本。
--to <VERSION>

取得程式庫的特定版本。

-h|--help

顯示說明資訊。
--verbosity <LEVEL>

設定輸出的詳細程度。將 <LEVEL> 取代為下列其中一個值：
- quiet
- normal
- detailed

範例

若要將 jQuery 更新為最新版本：
```
libman update jquery
```
若要將 jQuery 更新為 3.3.1 版：
```
libman update jquery --to 3.3.1
```
若要將 jQuery 更新為最新的發行前版本：
```
libman update jquery -pre
```

管理程式庫快取

libman cache 命令會管理 LibMan 程式庫快取。 filesystem 提供者不會使用程式庫快取。

概要

libman cache clean [<PROVIDER>] [--verbosity]
libman cache list [--files] [--libraries] [--verbosity]
libman cache [-h|--help]

引數

PROVIDER

僅與 clean 命令搭配使用。指定要清除的提供者快取。有效值包括：

cdnjs
filesystem
jsdelivr
unpkg

選項。

以下是使用 libman cache 命令時可用的選項：

--files

列出快取的檔案名稱。
--libraries

列出快取的程式庫名稱。

-h|--help

顯示說明資訊。
--verbosity <LEVEL>

設定輸出的詳細程度。將 <LEVEL> 取代為下列其中一個值：
- quiet
- normal
- detailed

範例

若要檢視每個提供者的快取程式庫名稱，請使用下列其中一個命令：

libman cache list

libman cache list --libraries

會顯示類似下列的輸出：

Cache contents:
---------------
unpkg:
    knockout
    react
    vue
cdnjs:
    font-awesome
    jquery
    knockout
    lodash.js
    react

若要檢視每個提供者的快取程式庫檔名稱：

libman cache list --files

會顯示類似下列的輸出：

Cache contents:
---------------
unpkg:
    knockout:
        <list omitted for brevity>
    react:
        <list omitted for brevity>
    vue:
        <list omitted for brevity>
cdnjs:
    font-awesome
        metadata.json
    jquery
        metadata.json
        3.2.1\core.js
        3.2.1\jquery.js
        3.2.1\jquery.min.js
        3.2.1\jquery.min.map
        3.2.1\jquery.slim.js
        3.2.1\jquery.slim.min.js
        3.2.1\jquery.slim.min.map
        3.3.1\core.js
        3.3.1\jquery.js
        3.3.1\jquery.min.js
        3.3.1\jquery.min.map
        3.3.1\jquery.slim.js
        3.3.1\jquery.slim.min.js
        3.3.1\jquery.slim.min.map
    knockout
        metadata.json
        3.4.2\knockout-debug.js
        3.4.2\knockout-min.js
    lodash.js
        metadata.json
        4.17.10\lodash.js
        4.17.10\lodash.min.js
    react
        metadata.json

請注意，上述輸出顯示 jQuery 3.2.1 和 3.3.1 版快取位於 CDNJS 提供者下。

若要清空 CDNJS 提供者的程式庫快取：
```
libman cache clean cdnjs
```
清空 CDNJS 提供者快取之後，libman cache list 命令會顯示下列內容：
```
Cache contents:
---------------
unpkg:
    knockout
    react
    vue
cdnjs:
    (empty)
```
若要清空所有支援提供者的快取：
```
libman cache clean
```
清空所有提供者快取之後，libman cache list 命令會顯示下列內容：
```
Cache contents:
---------------
unpkg:
    (empty)
cdnjs:
    (empty)
```

搭配使用 LibMan CLI 與 ASP.NET Core

必要條件

安裝

使用方式

在專案中初始化 LibMan

概要

選項。

範例

新增程式庫檔

概要

引數

選項。

範例

還原程式庫檔

概要

選項。

範例

刪除程式庫檔

概要

選項。

範例

解除安裝程式庫檔

概要

引數

選項。

範例

更新程式庫版本

概要

引數

選項。

範例

管理程式庫快取

概要

引數

選項。

範例

其他資源

意見反應

其他資源