使用 Visual Studio 中的 ASP.NET Core 使用 LibManUse LibMan with ASP.NET Core in Visual Studio

作者:Scott AddieBy Scott Addie

Visual Studio 的內建支援LibMan在 ASP.NET Core 專案中,包括:Visual Studio has built-in support for LibMan in ASP.NET Core projects, including:

  • 設定和執行組建 LibMan 還原作業的支援。Support for configuring and running LibMan restore operations on build.
  • 觸發 LibMan 還原和清除作業的功能表項目。Menu items for triggering LibMan restore and clean operations.
  • 尋找程式庫及將檔案新增至專案的 [搜尋] 對話方塊。Search dialog for finding libraries and adding the files to a project.
  • 編輯支援libman.json—LibMan 資訊清單檔案。Editing support for libman.json—the LibMan manifest file.

檢視或下載範例程式碼 (如何下載)View or download sample code (how to download)

必要條件Prerequisites

  • Visual Studio 2017 版 15.8 或更新版本以及ASP.NET 和 web 開發工作負載Visual Studio 2017 version 15.8 or later with the ASP.NET and web development workload

新增程式庫檔案Add library files

程式庫檔案可以新增至 ASP.NET Core 專案中,兩個不同的方式:Library files can be added to an ASP.NET Core project in two different ways:

  1. 使用 [新增用戶端程式庫] 對話方塊Use the Add Client-Side Library dialog
  2. 手動設定 LibMan 資訊清單檔案項目Manually configure LibMan manifest file entries

使用 [新增用戶端程式庫] 對話方塊Use the Add Client-Side Library dialog

請遵循下列步驟來安裝用戶端程式庫:Follow these steps to install a client-side library:

  • 在 [方案總管] 中,以滑鼠右鍵按一下專案資料夾中的檔案應該新增。In Solution Explorer, right-click the project folder in which the files should be added. 選擇新增 > 用戶端程式庫Choose Add > Client-Side Library. 新增用戶端程式庫對話方塊隨即出現:The Add Client-Side Library dialog appears:

    新增用戶端程式庫 對話方塊

  • 選取 從程式庫提供者提供者下拉式清單。Select the library provider from the Provider drop down. CDNJS 是預設提供者。CDNJS is the default provider.

  • 類型程式庫名稱,在擷取程式庫文字方塊。Type the library name to fetch in the Library text box. IntelliSense 提供一份文件庫開始提供的文字。IntelliSense provides a list of libraries beginning with the provided text.

  • 從 [IntelliSense] 清單中選取程式庫。Select the library from the IntelliSense list. 請注意,程式庫名稱會加上@符號和已知的所選的提供者的最新穩定版本。Notice the library name is suffixed with the @ symbol and the latest stable version known to the selected provider.

  • 決定要包含哪些檔案:Decide which files to include:

    • 選取 包括所有的程式庫檔選項按鈕,以包含所有的程式庫的檔案。Select the Include all library files radio button to include all of the library's files.
    • 選取 選擇特定的檔案選項按鈕,以包含程式庫檔案的子集。Select the Choose specific files radio button to include a subset of the library's files. 選取選項按鈕時,會啟用檔案選取器樹狀目錄。When the radio button is selected, the file selector tree is enabled. 請檢查要下載的檔案名稱的左邊的方塊。Check the boxes to the left of the file names to download.
  • 指定儲存在檔案的專案資料夾目標位置文字方塊。Specify the project folder for storing the files in the Target Location text box. 建議,另一個資料夾中儲存每個程式庫。As a recommendation, store each library in a separate folder.

    建議目標位置資料夾以啟動 [] 對話方塊的位置為基礎:The suggested Target Location folder is based on the location from which the dialog launched:

    • 如果從專案根目錄中啟動:If launched from the project root:
      • wwwroot/lib如果使用wwwroot存在。wwwroot/lib is used if wwwroot exists.
      • lib如果使用wwwroot不存在。lib is used if wwwroot doesn't exist.
    • 如果啟動專案資料夾中,會使用對應的資料夾名稱。If launched from a project folder, the corresponding folder name is used.

    程式庫名稱會加上資料夾的建議。The folder suggestion is suffixed with the library name. 下表說明資料夾建議,Razor 頁面專案中安裝 jQuery 時。The following table illustrates folder suggestions when installing jQuery in a Razor Pages project.

    啟動位置Launch location 建議的資料夾Suggested folder
    專案根目錄 (如果wwwroot存在)project root (if wwwroot exists) wwwroot/lib/jquery /wwwroot/lib/jquery/
    專案根目錄 (如果wwwroot不存在)project root (if wwwroot doesn't exist) lib/jquery /lib/jquery/
    頁面專案中的資料夾Pages folder in project 頁面/jquery /Pages/jquery/
  • 按一下 [安裝] 按鈕,下載的檔案,每個在組態libman.jsonClick the Install button to download the files, per the configuration in libman.json.

  • 檢閱程式庫管理員摘要輸出安裝詳細資料 視窗。Review the Library Manager feed of the Output window for installation details. 例如: For example:

    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)。All LibMan operations in Visual Studio are based on the content of the project root's LibMan manifest (libman.json). 您可以手動編輯libman.json設定專案的程式庫檔案。You can manually edit libman.json to configure library files for the project. Visual Studio 中還原所有的程式庫檔案一次libman.json儲存。Visual Studio restores all library files once libman.json is saved.

若要開啟 libman.json進行編輯,有下列選項:To open libman.json for editing, the following options exist:

  • 按兩下libman.json中的檔案方案總管 中Double-click the libman.json file in Solution Explorer.
  • 中的專案上按一下滑鼠右鍵方案總管,然後選取管理用戶端程式庫Right-click the project in Solution Explorer and select Manage Client-Side Libraries.
  • 選取 管理的用戶端程式庫從 Visual Studio專案功能表。Select Manage Client-Side Libraries from the Visual Studio Project menu.

如果libman.json檔案不存在的專案根目錄中,將會使用預設項目範本內容建立。 If the libman.json file doesn't already exist in the project root, it will be created with the default item template content.

Visual Studio 提供豐富編輯支援,像是顏色標示、 格式、 IntelliSense 和結構描述驗證的 JSON。Visual Studio offers rich JSON editing support such as colorization, formatting, IntelliSense, and schema validation. LibMan 資訊清單的 JSON 結構描述位於 http://json.schemastore.org/libman The LibMan manifest's JSON schema is found at http://json.schemastore.org/libman.

下列資訊清單檔案時,LibMan 擷取檔案中定義的組態每libraries屬性。With the following manifest file, LibMan retrieves files per the configuration defined in the libraries property. 物件常值中定義的說明libraries遵循:An explanation of the object literals defined within libraries follows:

  • 子集jQuery 3.3.1 版會從 CDNJS 提供者。A subset of jQuery version 3.3.1 is retrieved from the CDNJS provider. 中所定義的子集files屬性—jquery.min.jsjquery.js,以及jquery.min.mapThe subset is defined in the files property—jquery.min.js, jquery.js, and jquery.min.map. 檔案會放在專案的wwwroot/lib/jquery資料夾。The files are placed in the project's wwwroot/lib/jquery folder.
  • 將整個Bootstrap 4.1.3 版會擷取並放置於wwwroot/lib/啟動程序資料夾。The entirety of Bootstrap version 4.1.3 is retrieved and placed in a wwwroot/lib/bootstrap folder. 物件常值provider屬性會覆寫defaultProvider屬性值。The object literal's provider property overrides the defaultProvider property value. LibMan 擷取 unpkg 提供者的啟動程序的檔案。LibMan retrieves the Bootstrap files from the unpkg provider.
  • 子集Lodash已核准的組織內的控管主體。A subset of Lodash was approved by a governing body within the organization. Lodash.jslodash.min.js檔案會從本機檔案系統中擷取c:\temp\lodash\The lodash.js and lodash.min.js files are retrieved from the local file system at C:\temp\lodash\. 檔案會複製到專案的wwwroot/lib/lodash資料夾。The files are copied to the project's wwwroot/lib/lodash folder.
{
  "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 only supports one version of each library from each provider. Libman.json檔案無法通過結構描述驗證,如果它包含具有相同的程式庫名稱,指定提供者的兩個程式庫。The libman.json file fails schema validation if it contains two libraries with the same library name for a given provider.

將程式庫檔案還原Restore library files

若要還原從 Visual Studio 內的程式庫檔案,必須有有效libman.json專案根目錄中的檔案。To restore library files from within Visual Studio, there must be a valid libman.json file in the project root. 已還原的檔案會放置在專案中指定的每個程式庫的位置。Restored files are placed in the project at the location specified for each library.

您可以在 ASP.NET Core 專案中有兩種還原程式庫檔案:Library files can be restored in an ASP.NET Core project in two ways:

  1. 在建置時還原檔案Restore files during build
  2. 以手動方式還原檔案Restore files manually

在建置時還原檔案Restore files during build

LibMan 可以還原的已定義的程式庫檔案做為建置程序的一部分。LibMan can restore the defined library files as part of the build process. 根據預設,還原上建置停用行為。By default, the restore-on-build behavior is disabled.

若要啟用並測試還原上建置行為:To enable and test the restore-on-build behavior:

  • 以滑鼠右鍵按一下libman.json方案總管,然後選取啟用還原用戶端程式庫建置從內容功能表。Right-click libman.json in Solution Explorer and select Enable Restore Client-Side Libraries on Build from the context menu.

  • 按一下 按鈕時提示您安裝 NuGet 套件。Click the Yes button when prompted to install a NuGet package. Microsoft.Web.LibraryManager.Build NuGet 封裝加入至專案:The Microsoft.Web.LibraryManager.Build NuGet package is added to the project:

    <PackageReference Include="Microsoft.Web.LibraryManager.Build" Version="1.0.113" />
    
  • 建置專案,以確認 LibMan 檔案還原,就會發生。Build the project to confirm LibMan file restoration occurs. Microsoft.Web.LibraryManager.Build套件插入專案的建立作業期間執行 LibMan MSBuild 目標。The Microsoft.Web.LibraryManager.Build package injects an MSBuild target that runs LibMan during the project's build operation.

  • 檢閱建置摘要輸出LibMan 活動記錄 視窗:Review the Build feed of the Output window for a LibMan activity log:

    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操作功能表會顯示停用還原用戶端程式庫建置選項。When the restore-on-build behavior is enabled, the libman.json context menu displays a Disable Restore Client-Side Libraries on Build option. 選取此選項會移除Microsoft.Web.LibraryManager.Build套件從專案檔的參考。Selecting this option removes the Microsoft.Web.LibraryManager.Build package reference from the project file. 因此,用戶端程式庫不再會在每個組建上還原。Consequently, the client-side libraries are no longer restored on each build.

不論還原上組建設定中,您可以手動還原的任何時候libman.json操作功能表。Regardless of the restore-on-build setting, you can manually restore at any time from the libman.json context menu. 如需詳細資訊,請參閱 < 以手動方式還原檔案For more information, see Restore files manually.

以手動方式還原檔案Restore files manually

若要以手動方式還原程式庫檔案:To manually restore library files:

  • 在方案中的所有專案:For all projects in the solution:
    • 中的方案名稱上按一下滑鼠右鍵方案總管 中Right-click the solution name in Solution Explorer.
    • 選取 還原用戶端程式庫選項。Select the Restore Client-Side Libraries option.
  • 針對特定專案:For a specific project:
    • 以滑鼠右鍵按一下libman.json中的檔案方案總管 中Right-click the libman.json file in Solution Explorer.
    • 選取 還原用戶端程式庫選項。Select the Restore Client-Side Libraries option.

雖然還原作業正在執行:While the restore operation is running:

  • 在 Visual Studio 的 [狀態] 列上的工作狀態中心 (TSC) 圖示會變成動畫,以及將讀取還原作業已開始The Task Status Center (TSC) icon on the Visual Studio status bar will be animated and will read Restore operation started. 按一下圖示即可開啟列出的已知的背景工作的工具提示。Clicking the icon opens a tooltip listing the known background tasks.

  • 會將訊息傳送至 [狀態] 列與程式庫管理員摘要輸出視窗。Messages will be sent to the status bar and the Library Manager feed of the Output window. 例如: For example:

    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 中的程式庫檔案:To perform the clean operation, which deletes library files previously restored in Visual Studio:

  • 以滑鼠右鍵按一下libman.json中的檔案方案總管 中Right-click the libman.json file in Solution Explorer.
  • 選取 全新的用戶端程式庫選項。Select the Clean Client-Side Libraries option.

若要防止意外移除程式庫檔案,清除作業並不會刪除整個目錄。To prevent unintentional removal of non-library files, the clean operation doesn't delete whole directories. 它只會移除已包含在前一個還原的檔案。It only removes files that were included in the previous restore.

當正在執行清除的作業:While the clean operation is running:

  • Visual Studio 的 [狀態] 列 TSC 圖示項目建立動畫,並將讀取用戶端程式庫作業啟動The TSC icon on the Visual Studio status bar will be animated and will read Client libraries operation started. 按一下圖示即可開啟列出的已知的背景工作的工具提示。Clicking the icon opens a tooltip listing the known background tasks.
  • 訊息會傳送至 [狀態] 列與程式庫管理員摘要輸出視窗。Messages are sent to the status bar and the Library Manager feed of the Output window. 例如: For example:
Clean libraries operation started...
Clean libraries operation completed
2 libraries were successfully deleted in 1.91 secs

清除作業只會刪除從專案的檔案。The clean operation only deletes files from the project. 程式庫檔案保持在未來的還原作業上更快速地擷取的快取中。Library files stay in the cache for faster retrieval on future restore operations. 若要管理儲存在本機電腦的快取中的程式庫檔案,請使用LibMan CLITo manage library files stored in the local machine's cache, use the LibMan CLI.

解除安裝程式庫檔案Uninstall library files

若要解除安裝程式庫檔案:To uninstall library files:

  • 開啟libman.jsonOpen libman.json.

  • 放置在對應的插入號libraries物件常值。Position the caret inside the corresponding libraries object literal.

  • 按一下左邊界中,會出現燈泡圖示,然後選取解除安裝<library_name > @<library_version >:Click the light bulb icon that appears in the left margin, and select Uninstall <library_name>@<library_version>:

    解除安裝程式庫操作功能表選項

或者,您可以手動編輯並儲存 LibMan 資訊清單 (libman.json)。Alternatively, you can manually edit and save the LibMan manifest (libman.json). 還原作業時儲存檔案時執行。The restore operation runs when the file is saved. 不會再定義中的程式庫檔案libman.json從專案中移除。Library files that are no longer defined in libman.json are removed from the project.

更新程式庫版本Update library version

若要檢查有更新的程式庫版本:To check for an updated library version:

  • 開啟libman.jsonOpen libman.json.
  • 放置在對應的插入號libraries物件常值。Position the caret inside the corresponding libraries object literal.
  • 按一下燈泡圖示出現在左邊界中。Click the light bulb icon that appears in the left margin. 將滑鼠停留檢查是否有更新Hover over Check for updates.

LibMan 會檢查程式庫版本比安裝的版本還新。LibMan checks for a library version newer than the version installed. 可能會發生下列結果:The following outcomes can occur:

  • A找不到更新如果已安裝最新版本,就會顯示訊息。A No updates found message is displayed if the latest version is already installed.

  • 最新穩定版本會顯示如果沒有已安裝。The latest stable version is displayed if not already installed.

    檢查有更新快顯功能表選項

  • 如果可用的發行前版本比已安裝的版本還新,則會顯示發行前版本。If a pre-release newer than the installed version is available, the pre-release is displayed.

若要降級至較舊的程式庫版本,請以手動方式編輯libman.json檔案。To downgrade to an older library version, manually edit the libman.json file. 當儲存檔案時,LibMan還原作業:When the file is saved, the LibMan restore operation:

  • 從先前版本中移除多餘的檔案。Removes redundant files from the previous version.
  • 從新的版本中加入全新和更新的檔案。Adds new and updated files from the new version.

其他資源Additional resources