Use LibMan with ASP.NET Core in Visual Studio

Grein
09/21/2022

By Scott Addie

Visual Studio has built-in support for LibMan in ASP.NET Core projects, including:

Support for configuring and running LibMan restore operations on build.
Menu items for triggering LibMan restore and clean operations.
Search dialog for finding libraries and adding the files to a project.
Editing support for libman.json—the LibMan manifest file.

View or download sample code (how to download)

Prerequisites

Visual Studio 2019 with the ASP.NET and web development workload

Add library files

Library files can be added to an ASP.NET Core project in two different ways:

Use the Add Client-Side Library dialog
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 is the default provider.
Type the library name to fetch in the Library text box. IntelliSense provides a list of libraries beginning with the provided text.
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 is used if wwwroot exists.
  - 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. The following table illustrates folder suggestions when installing jQuery in a Razor Pages project.

Launch location Suggested folder

project root (if wwwroot exists) wwwroot/lib/jquery/

project root (if wwwroot doesn't exist) lib/jquery/

Pages folder in project Pages/jquery/
Click the Install button to download the files, per the configuration in libman.json.

Launch location	Suggested folder
project root (if wwwroot exists)	wwwroot/lib/jquery/
project root (if wwwroot doesn't exist)	lib/jquery/
Pages folder in project	Pages/jquery/

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

Manually configure LibMan manifest file entries

All LibMan operations in Visual Studio are based on the content of the project root's LibMan manifest (libman.json). You can manually edit libman.json to configure library files for the project. Visual Studio restores all library files once libman.json is saved.

To open libman.json for editing, the following options exist:

Double-click the libman.json file in Solution Explorer.
Right-click the project in Solution Explorer and select Manage Client-Side Libraries. †
Select Manage Client-Side Libraries from the Visual Studio Project menu. †

† 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 offers rich JSON editing support such as colorization, formatting, IntelliSense, and schema validation. The LibMan manifest's JSON schema is found at https://json.schemastore.org/libman.

With the following manifest file, LibMan retrieves files per the configuration defined in the libraries property. An explanation of the object literals defined within libraries follows:

A subset of jQuery version 3.3.1 is retrieved from the CDNJS provider. The subset is defined in the files property—jquery.min.js, jquery.js, and jquery.min.map. The files are placed in the project's wwwroot/lib/jquery folder.
The entirety of Bootstrap version 4.1.3 is retrieved and placed in a wwwroot/lib/bootstrap folder. The object literal's provider property overrides the defaultProvider property value. LibMan retrieves the Bootstrap files from the unpkg provider.
A subset of Lodash was approved by a governing body within the organization. The lodash.js and lodash.min.js files are retrieved from the local file system at C:\temp\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/"
    }
  ]
}

Note

LibMan only supports one version of each library from each provider. The libman.json file fails schema validation if it contains two libraries with the same library name for a given provider.

Restore library files

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.

Library files can be restored in an ASP.NET Core project in two ways:

Restore files during build
Restore files manually

Restore files during build

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:

Right-click libman.json in Solution Explorer and select Enable Restore Client-Side Libraries on Build from the context menu.
Click the Yes button when prompted to install a NuGet package. The Microsoft.Web.LibraryManager.Build NuGet package is added to the project:
```
<PackageReference Include="Microsoft.Web.LibraryManager.Build" Version="1.0.113" />
```
Build the project to confirm LibMan file restoration occurs. The Microsoft.Web.LibraryManager.Build package injects an MSBuild target that runs LibMan during the project's build operation.

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

When the restore-on-build behavior is enabled, the libman.json context menu displays a Disable Restore Client-Side Libraries on Build option. 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.

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:
- Right-click the libman.json file in Solution Explorer.
- Select the Restore Client-Side Libraries option.

While the restore operation is running:

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

To perform the clean operation, which deletes library files previously restored in Visual Studio:

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:

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. To manage library files stored in the local machine's cache, use the LibMan CLI.

Uninstall library files

To uninstall library files:

Open libman.json.
Position the caret inside the corresponding libraries object literal.
Click the light bulb icon that appears in the left margin, and select Uninstall <library_name>@<library_version>:

Alternatively, you can manually edit and save the LibMan manifest (libman.json). The restore operation runs when the file is saved. 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:

Open libman.json.
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 checks for a library version newer than the version installed. The following outcomes can occur:

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.

To downgrade to an older library version, manually edit the libman.json file. 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.

Deila með