Using LibMan in Visual Studio
Visual Studio has built-in support for using LibMan in Web Projects, including:
- support for configuring and running LibMan restore operation on build
- menu items for triggering LibMan restore and clean operations
- dialog that helps you search for libraries and add the files to your project
- editing support for the LibMan manifest file (libman.json)
Though LibMan can work from any folder or any project type (via CLI or a CI build script), within Visual Studio, LibMan features are only available Web Projects.
Open a Web Project in Visual Studio 2017 (v15.8 Preview 3 and above).
! If you're looking to get started with a new Web Project, see the Getting Started - Razor MVC guide.
You can add files to your web project two ways:
- Use the "Add Client-Side Library" dialog
- Edit the libman.json file in the root of the project
-
Choose a folder that you want to add files to (or a parent thereof).
-
Right-click the folder and select Add->Client-Side Library...
The "Add Client-Side Library" dialog will open with focus in the Library field.
-
Type the name of a library you want to fetch (ie. "jquery", "twitter-bootstrap")
IntelliSense will provide a list of libraries starting with the name given. -
Select the correct item then press Tab.
The library ID will be completed with the "@" symbol followed by the latest version known to that provider.
Focus will move to the files selection radio buttons. -
To include all files in the specified library, set the radio button to "Include all library files".
-
To specify a smaller set of files from the library, choose the "Choose specific files:" option, which will enable the file selector tree with a smaller set selected by default.
Use the checkboxes to the left of the files to select the files to download.
-
Specify the location of the new files within your web project. (Where do you want the files to go?)
Note: It is recommended to keep each library in a separate folder. The default location suggested for the new files will be a folder with the same name as the library under the directory the dialog was launched from.
Modify the Target Location as necessary. -
Press Install.
The configuration will be written to libman.json in the project root and the files will be downloaded into the project.
-
Messages will appear in the Output window
All LibMan operations are based on the content of the LibMan manifest, which is the libman.json at the root of the project.
You can manually edit this file to define the library files that should be downloaded into the project.
Visual Studio offers editing support for the libman.json file, including coloring, formatting, IntelliSense and schema validation.
Note: LibMan only supports one version of each library from each provider. The libman.json file will be invalid if it contains two libraries with the same library name for a given provider.
There are several Library Manager operations you can perform with Visual Studio. Some actions are available from the context menu on the LibMan config file (libman.json)
If your project has a valid LibMan config file (libman.json), the Restore Client-Side Libraries operation will download all the defined library files and place them in your project at the locations specified for each library. You can also kick off a restore operation for all projects in the solution by choosing the restore option that appears on the Solution context menu.
While the operation is running, the Task Status Center icon on the status bar will be animated. Clicking the icon will open a pop-up window listing the known background tasks.
Messages will be sent to the Library Manager feed in the Output window as well as the status bar.
The Clean Client-Side Libraries operation will remove all the library files that were previously restored by LibMan in Visual Studio. So that additional non-library files are not unintentionally removed, the Clean operation will not delete whole directories. It will only remove the files that were included in the previous restore.
If you'd like the project to be configured so that it automatically triggers a LibMan Restore operation whenever the project is built, you can choose to Enable Restore Client-Side Libraries on Build....
This will download a NuGet package and add it to your project so LibMan will run as part of the build operation for that project in future builds.
When Restore on Build is enabled, the menu item will offer to Disable Restore Client-Side Libraries on Build. If you choose this option, the LibMan NuGet package will be removed from the project and the client-side libraries will no longer be restored on each build.
Regardless of the Restore on Build setting, you can manually restore by activating the Restore Client-Side Libraries command at any time.
To uninstall library files from within Visual Studio, edit the libman.json and press Save. The restore operation runs on Save and will remove the library files that are no longer part of the LibMan config.
To update the version of a library, edit the libman.json - changing to the version required. When the file is saved, the LibMan restore operation will remove redundant files from the previous version and add new and updated files from the new version.