Using LibMan in Visual Studio

Justin Clareburt edited this page Jun 28, 2018 · 26 revisions

Visual Studio support for LibMan

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.

Getting started with LibMan

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:

  1. Use the "Add Client-Side Library" dialog
  2. Edit the libman.json file in the root of the project

Add Client-Side Libraries

  • Choose a folder that you want to add files to (or a parent thereof).

  • Right-click the folder and select Add->Client-Side Library...
    Add Client-side Library via Solution Explorer context menu

    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. Add Client-Side Library dialog with query files selected

  • 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.
    Web project in Solution Explorer with libman.json and jquery files added

  • Messages will appear in the Output window Library Manager output in the Visual Studio Output window

Edit the LibMan Manifest (libman.json)

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.

Editing libman.json in Visual Studio

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.

LibMan Operations

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)

LibMan operations available on libman.json context menu

Restoring library files into your project

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.

LibMan restore operation running in the Task Status Center

Messages will be sent to the Library Manager feed in the Output window as well as the status bar.

Clean library files from your project

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.

Enable/Disable Restore Client-Side Libraries on Build

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.

Enable Restore On Build: Adds a NuGet package to your project

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.

Disable Restore on Build menu item

Regardless of the Restore on Build setting, you can manually restore by activating the Restore Client-Side Libraries command at any time.

Uninstalling Library Files

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.

Updating Library versions

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.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.