Поделиться через

Использование LibMan с ASP.NET Core в Visual Studio

  • Статья

Автор: Скотт Адди (Scott Addie)

В Visual Studio имеется встроенная поддержка LibMan в проектах ASP.NET Core, которая включает в себя:

  • поддержку настройки и выполнения операций восстановления LibMan при сборке;
  • пункты меню для запуска операций восстановления и очистки LibMan;
  • диалоговое окно для поиска библиотек и добавления файлов в проект;
  • Поддержка libman.jsonредактирования файла манифеста LibMan.

Просмотреть или скачать образец кода (описание загрузки)

Необходимые компоненты

  • Visual Studio 2019 с рабочей нагрузкой ASP.NET и веб-разработка.

Добавление файлов библиотеки

Файлы библиотек можно добавлять в проект ASP.NET Core двумя разными способами:

  1. Используйте диалоговое окно "Добавьте клиентские библиотеки".
  2. Настройте записи в файле манифеста LibMan вручную.

Использование диалогового окна "Добавьте клиентские библиотеки"

Чтобы установить клиентскую библиотеку, выполните указанные ниже действия.

  • В обозревателе решений щелкните правой кнопкой мыши папку проекта, в которую нужно добавить файлы. Выберите пункты Добавить>Клиентская библиотека. Появится диалоговое окно Добавьте клиентские библиотеки.

    Диалоговое окно

  • В раскрывающемся списке Поставщик выберите поставщика библиотеки. CDNJS является поставщиком по умолчанию.

  • В текстовом поле Библиотека введите имя библиотеки, которую нужно получить. IntelliSense предлагает список библиотек, имена которых начинаются с введенного текста.

  • Выберите библиотеку в списке IntelliSense. Обратите внимание, что после имени библиотеки стоит символ @ и номер последней стабильной версии, известной выбранному поставщику.

  • Решите, какие файлы следует включить.

    • Установите переключатель в положение Включить все файлы библиотеки, чтобы включить все файлы библиотеки.
    • Установите переключатель в положение Выбрать определенные файлы, чтобы включить часть файлов библиотеки. После этого станет доступно дерево выбора файлов. Установите флажки слева от имен файлов, которые нужно скачать.

  • В текстовом поле Целевое расположение укажите папку проекта, в которой необходимо сохранить файлы. Каждую библиотеку рекомендуется хранить в отдельной папке.

    Предлагаемое целевое расположение зависит от того, откуда было запущено диалоговое окно.

    • При запуске из корневого каталога проекта:
      • используется папка wwwroot/lib, если wwwroot существует;
      • используется папка lib, если wwwroot не существует.
    • При запуске из папки проекта используется соответствующее имя папки.

    После папки указывается имя библиотеки. В приведенной ниже таблице показаны папки, предлагаемые при установке jQuery в проекте Razor Pages.

    Место запуска Предлагаемая папка
    корневой каталог проекта (если wwwroot существует) wwwroot/lib/jquery/
    корневой каталог проекта (если wwwroot не существует) lib/jquery/
    Папка Pages проекта Pages/jquery/

  • Нажмите кнопку "Установить ", чтобы скачать файлы в конфигурации libman.json.

  • Ознакомьтесь со сведениями об установке в канале Диспетчер библиотек окна Выходные данные. Например:

    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 вручную

Все операции LibMan в Visual Studio основаны на содержимом манифеста LibMan корневого проекта (libman.json). Вы можете вручную изменить libman.json файлы библиотеки для проекта. Visual Studio восстанавливает все файлы библиотеки после libman.json сохранения.

Чтобы открыть libman.json для редактирования, существуют следующие параметры:

  • Дважды щелкните libman.json файл в Обозреватель решений.
  • В обозревателе решений щелкните проект правой кнопкой мыши и выберите пункт Управление клиентскими библиотеками. †
  • В меню Проект в Visual Studio выберите пункт Управление клиентскими библиотеками. †

† Если libman.json файл еще не существует в корневом каталоге проекта, он будет создан с содержимым шаблона элемента по умолчанию.

В Visual Studio предлагаются широкие возможности для редактирования JSON, в том числе раскраска, форматирование, IntelliSense и проверка схемы. Схему манифеста LibMan в формате JSON можно найти на странице https://json.schemastore.org/libman.

При использовании приведенного ниже файла манифеста LibMan извлекает файлы в соответствии с конфигурацией, определенной в свойстве libraries. Далее приводится описание объектных литералов, определенных в libraries.

  • От поставщика CDNJS принимается подмножество файлов jQuery версии 3.3.1. Это подмножество определено в свойстве files — jquery.min.js, jquery.js и jquery.min.map. Файлы помещаются в папку wwwroot/lib/jquery проекта.
  • Все файлы Bootstrap версии 4.1.3 получаются и помещаются в папку wwwroot/lib/bootstrap. Свойство provider объектного литерала переопределяет значение свойства defaultProvider. LibMan получает файлы Bootstrap от поставщика unpkg.
  • Подмножество файлов Lodash утверждается руководством организации. Файлы lodash.js извлекаются из локальной файловой системы в C:\temp\lodash\.lodash.min.js Они копируются в папку wwwroot/lib/lodash проекта.
{
  "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.json завершает проверку схемы, если он содержит две библиотеки с одинаковым именем библиотеки для данного поставщика.

Восстановление файлов библиотек

Чтобы восстановить файлы библиотеки из Visual Studio, в корневом каталоге проекта должен быть допустимый libman.json файл. Восстановленные файлы помещаются в проект в расположение, указанное для каждой библиотеки.

Файлы библиотек можно восстановить в проекте ASP.NET Core двумя способами:

  1. Восстановление файлов во время сборки
  2. Восстановление файлов вручную

Восстановление файлов во время сборки

LibMan может восстанавливать определенные файлы библиотек в процессе сборки. По умолчанию восстановление при сборке отключено.

Чтобы включить и протестировать восстановление при сборке, выполните указанные ниже действия.

  • Щелкните правой кнопкой мыши libman.json Обозреватель решений и выберите "Включить клиентские библиотеки" в контекстном меню.

  • При появлении запроса на установку пакета NuGet нажмите кнопку Да. Пакет NuGet Microsoft.Web.LibraryManager.Build добавится в проект:

    <PackageReference Include="Microsoft.Web.LibraryManager.Build" Version="1.0.113" />

  • Выполните сборку проекта, чтобы убедиться в том, что диспетчер LibMan восстановил файлы. Пакет Microsoft.Web.LibraryManager.Build внедряет целевой объект MSBuild, который запускает LibMan во время операции сборки проекта.

  • В канале Сборка окна Выходные данные просмотрите журнал действий LibMan:

    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 контекстное меню отображает параметр "Отключить клиентские библиотеки" для сборки . При его выборе ссылка на пакет Microsoft.Web.LibraryManager.Build удаляется из файла проекта. В результате клиентские библиотеки больше не будут восстанавливаться при каждой сборке.

Независимо от параметра сборки восстановления можно вручную восстановить в любое время из контекстного libman.json меню. Дополнительные сведения см. в разделе Восстановление файлов вручную.

Восстановление файлов вручную

Чтобы вручную восстановить файлы библиотек, выполните указанные ниже действия.

  • Для всех проектов в решении:
    • В обозревателе решений щелкните правой кнопкой мыши имя решения.
    • Выберите пункт Восстановить клиентские библиотеки.
  • Для конкретного проекта:
    • Щелкните правой libman.json кнопкой мыши файл в Обозреватель решений.
    • Выберите пункт Восстановить клиентские библиотеки.

Во время операции восстановления происходит следующее:

  • В строке состояния Visual Studio будет анимироваться значок Центра состояния задач (TSC) с сообщением Операция восстановления начата. Если щелкнуть значок, откроется подсказка со списком известных фоновых задач.

  • В строку состояния и канал Диспетчер библиотек окна Выходные данные будут передаваться сообщения. Например:

    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

Удаление файлов библиотек

Чтобы произвести операцию очистки, которая удаляет файлы библиотек, восстановленные ранее в Visual Studio, выполните указанные ниже действия.

  • Щелкните правой libman.json кнопкой мыши файл в Обозреватель решений.
  • Выберите пункт Очистить клиентские библиотеки.

Во избежание непреднамеренного удаления файлов, не относящихся к библиотекам, операция очистки не удаляет каталоги полностью. Она удаляет только те файлы, которые были включены в предыдущую операцию восстановления.

Во время операции очистки происходит следующее:

  • В строке состояния Visual Studio будет анимироваться значок Центра состояния задач с сообщением Начата операция с клиентскими библиотеками. Если щелкнуть значок, откроется подсказка со списком известных фоновых задач.
  • В строку состояния и канал Диспетчер библиотек окна Выходные данные передаются сообщения. Например:
Clean libraries operation started...
Clean libraries operation completed
2 libraries were successfully deleted in 1.91 secs

Операция очистки удаляет файлы только из проекта. При этом файлы библиотек остаются в кэше для более быстрого извлечения при последующих операциях восстановления. Для управления файлами библиотек, хранящимися в кэше локального компьютера, используйте интерфейс командной строки LibMan.

Удаление файлов библиотек

Чтобы удалить файлы библиотек, выполните указанные ниже действия.

  • Открыть libman.json.

  • Поместите курсор внутри соответствующего объектного литерала libraries.

  • Щелкните значок лампочки, появившийся в левом поле, а затем выберите пункт Удалить <имя_библиотеки>@<версия_библиотеки>.

    Команда удаления библиотеки в контекстном меню

Кроме того, можно вручную изменить и сохранить манифест LibMan (libman.json). Операция восстановления выполняется при сохранении файла. Файлы библиотеки, которые больше не определены в libman.json проекте, удаляются из проекта.

Обновление версии библиотеки

Чтобы проверить наличие новой версии библиотеки, выполните указанные ниже действия.

  • Открыть libman.json.
  • Поместите курсор внутри соответствующего объектного литерала libraries.
  • Щелкните значок лампочки, появившийся в левом поле. Наведите указатель на пункт Проверить обновления.

LibMan проверит наличие версии библиотеки, более поздней, чем установленная. Возможен один из следующих результатов:

  • Если установлена последняя версия, появится сообщение Обновления не найдены.

  • Будет показана последняя стабильная версия, если она еще не установлена.

    Пункт

  • Если имеется предварительный выпуск, более поздний, чем установленная версия, он будет показан.

Чтобы перейти на более раннюю версию библиотеки, вручную измените libman.json файл. При сохранении этого файла операция восстановления LibMan выполняет следующие действия:

  • удаляет лишние файлы из предыдущей версии;
  • добавляет новые и обновленные файлы из новой версии.

Дополнительные ресурсы