aspnetcore/client-side/libman/libman-vs.md
By Scott Addie
Visual Studio has built-in support for LibMan in ASP.NET Core projects, including:
libman.json—the LibMan manifest file.View or download sample code (how to download)
Library files can be added to an ASP.NET Core project in two different ways:
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:
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:
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.
Review the Library Manager feed of the Output window for installation details. For example:
Restore operation started...
Restoring libraries for project LibManSample
Restoring library [email protected]... (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
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:
libman.json file in Solution Explorer.† 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:
files property—jquery.min.js, jquery.js, and jquery.min.map. The files are placed in the project's wwwroot/lib/jquery folder.provider property overrides the defaultProvider property value. LibMan retrieves the Bootstrap files from the unpkg provider.[!NOTE] LibMan only supports one version of each library from each provider. The
libman.jsonfile fails schema validation if it contains two libraries with the same library name for a given provider.
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:
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:
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 [email protected]...
1>Restoring library [email protected]...
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.
To manually restore library files:
libman.json file in Solution Explorer.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 [email protected]... (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
To perform the clean operation, which deletes library files previously restored in Visual Studio:
libman.json file in Solution Explorer.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:
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.
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.
To check for an updated library version:
libman.json.libraries object literal.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: