Używanie programu LibMan z platformą ASP.NET Core w programie Visual Studio

Autor: Scott Addie

Program Visual Studio ma wbudowaną obsługę biblioteki LibMan w projektach ASP.NET Core, w tym:

• Obsługa konfigurowania i uruchamiania operacji przywracania LibMan na kompilacji.
• Elementy menu służące do wyzwalania operacji przywracania i czyszczenia biblioteki LibMan.
• Okno dialogowe wyszukiwania umożliwia znajdowanie bibliotek i dodawanie plików do projektu.
• Obsługa edycji dla libman.jsonpliku manifestu LibMan.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Wymagania wstępne

• Program Visual Studio 2019 z pakietem roboczym tworzenia aplikacji internetowych i ASP.NET

Dodawanie plików biblioteki

Pliki biblioteki można dodać do projektu ASP.NET Core na dwa różne sposoby:

1. Okno dialogowe Dodawanie biblioteki po stronie klienta
2. Ręczne konfigurowanie wpisów pliku manifestu LibMan

Okno dialogowe Dodawanie biblioteki po stronie klienta

Wykonaj następujące kroki, aby zainstalować bibliotekę po stronie klienta:

• W Eksplorator rozwiązań kliknij prawym przyciskiem myszy folder projektu, w którym mają zostać dodane pliki. Wybierz pozycję Dodaj>bibliotekę po stronie klienta. Zostanie wyświetlone okno dialogowe Dodawanie biblioteki po stronie klienta:

  

• Wybierz dostawcę biblioteki z listy rozwijanej Dostawca . CDNJS jest domyślnym dostawcą.

• Wpisz nazwę biblioteki, która ma być pobierana w polu tekstowym Biblioteka . Funkcja IntelliSense udostępnia listę bibliotek rozpoczynających się od dostarczonego tekstu.

• Wybierz bibliotekę z listy Funkcji IntelliSense. Zwróć uwagę, że nazwa biblioteki jest sufiksem z symbolem @ i najnowszą stabilną wersją znaną wybranemu dostawcy.

• Zdecyduj, które pliki mają zawierać:

  • Wybierz przycisk radiowy Uwzględnij wszystkie pliki biblioteki, aby uwzględnić wszystkie pliki biblioteki.
  • Wybierz przycisk radiowy Wybierz określone pliki, aby dołączyć podzbiór plików biblioteki. Po wybraniu przycisku radiowego jest włączone drzewo selektora plików. Zaznacz pola po lewej stronie nazw plików do pobrania.

• Określ folder projektu do przechowywania plików w polu tekstowym Lokalizacja docelowa . Zalecane jest przechowywanie każdej biblioteki w osobnym folderze.

  Sugerowany folder Lokalizacja docelowa jest oparty na lokalizacji, z której uruchomiono okno dialogowe:

  • Jeśli zostanie uruchomiona z poziomu katalogu głównego projektu:
    • Wwwroot/lib jest używany, jeśli wwwroot istnieje.
    • biblioteka jest używana, jeśli katalog wwwroot nie istnieje.
  • W przypadku uruchomienia z folderu projektu używana jest odpowiednia nazwa folderu.

  Sugestia folderu jest sufiksowana nazwą biblioteki. W poniższej tabeli przedstawiono sugestie dotyczące folderów podczas instalowania zapytania jQuery w projekcie Razor Pages.

  Lokalizacja uruchamiania	Sugerowany folder
  katalog główny projektu (jeśli katalog wwwroot istnieje)	wwwroot/lib/jquery/
  katalog główny projektu (jeśli katalog wwwroot nie istnieje)	lib/jquery/
  Folder Pages w projekcie	Strony/jquery/

• Kliknij przycisk Zainstaluj, aby pobrać pliki zgodnie z konfiguracją w pliku libman.json.

• Przejrzyj źródło danych menedżera biblioteki w oknie Dane wyjściowe, aby uzyskać szczegółowe informacje o instalacji. Na przykład:

  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
  

Ręczne konfigurowanie wpisów pliku manifestu LibMan

Wszystkie operacje LibMan w programie Visual Studio są oparte na zawartości manifestu LibMan katalogu głównego projektu (libman.json). Możesz ręcznie edytować libman.json , aby skonfigurować pliki biblioteki dla projektu. Program Visual Studio przywraca wszystkie pliki biblioteki po libman.json zapisaniu.

Aby otworzyć libman.json edycję, istnieją następujące opcje:

• libman.json Kliknij dwukrotnie plik w Eksplorator rozwiązań.
• Kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań i wybierz pozycję Zarządzaj bibliotekami po stronie klienta. †
• Wybierz pozycję Zarządzaj bibliotekami po stronie klienta z menu Projekt programu Visual Studio. †

† Jeśli libman.json plik jeszcze nie istnieje w katalogu głównym projektu, zostanie utworzony z domyślną zawartością szablonu elementu.

Program Visual Studio oferuje rozbudowaną obsługę edycji JSON, takich jak kolorowanie, formatowanie, IntelliSense i walidacja schematu. Schemat JSON manifestu LibMan znajduje się pod adresem https://json.schemastore.org/libman.

Przy użyciu następującego pliku manifestu LibMan pobiera pliki zgodnie z konfiguracją zdefiniowaną libraries we właściwości . Wyjaśnienie literałów obiektu zdefiniowanych w libraries następujący sposób:

• Podzestaw zestawu jQuery w wersji 3.3.1 jest pobierany z dostawcy USŁUGI CDNJS. Podzestaw jest zdefiniowany we files właściwości —jquery.min.js , jquery.jsi jquery.min.map. Pliki są umieszczane w folderze wwwroot/lib/jquery projektu.
• Cały plik Bootstrap w wersji 4.1.3 jest pobierany i umieszczany w folderze wwwroot/lib/bootstrap . Właściwość literału provider obiektu zastępuje defaultProvider wartość właściwości. LibMan pobiera pliki Bootstrap z dostawcy unpkg.
• Podzbiór Lodash został zatwierdzony przez organ zarządzający w organizacji. Pliki lodash.js i lodash.min.js są pobierane z lokalnego systemu plików w lokalizacji C:\temp\lodash\. Pliki są kopiowane do folderu wwwroot/lib/lodash projektu.

{
  "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/"
    }
  ]
}

Uwaga

Biblioteka LibMan obsługuje tylko jedną wersję każdej biblioteki od każdego dostawcy. Sprawdzanie libman.json poprawności schematu pliku kończy się niepowodzeniem, jeśli zawiera dwie biblioteki o tej samej nazwie biblioteki dla danego dostawcy.

Przywracanie plików biblioteki

Aby przywrócić pliki biblioteki z poziomu programu Visual Studio, musi istnieć prawidłowy libman.json plik w katalogu głównym projektu. Przywrócone pliki są umieszczane w projekcie w lokalizacji określonej dla każdej biblioteki.

Pliki biblioteki można przywrócić w projekcie ASP.NET Core na dwa sposoby:

1. Przywracanie plików podczas kompilacji
2. Ręczne przywracanie plików

Przywracanie plików podczas kompilacji

Biblioteka LibMan może przywrócić zdefiniowane pliki biblioteki w ramach procesu kompilacji. Domyślnie zachowanie przywracania w kompilacji jest wyłączone.

Aby włączyć i przetestować zachowanie przywracania na kompilacji:

• Kliknij prawym przyciskiem myszy libman.json Eksplorator rozwiązań i wybierz pozycję Włącz przywracanie bibliotek po stronie klienta w menu kontekstowym.

• Po wyświetleniu monitu o zainstalowanie pakietu NuGet kliknij przycisk Tak . Pakiet NuGet Microsoft.Web.LibraryManager.Build jest dodawany do projektu:

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

• Skompiluj projekt w celu potwierdzenia przywrócenia pliku LibMan. Pakiet Microsoft.Web.LibraryManager.Build wprowadza docelowy program MSBuild, który uruchamia bibliotekę LibMan podczas operacji kompilacji projektu.

• Przejrzyj zestawienie kompilacji okna Dane wyjściowe dla dziennika aktywności 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 ==========
  

Po włączeniu libman.json zachowania przywracania do kompilacji w menu kontekstowym zostanie wyświetlona opcja Wyłącz biblioteki po stronie klienta po stronie klienta w kompilacji . Wybranie tej opcji powoduje Microsoft.Web.LibraryManager.Build usunięcie odwołania do pakietu z pliku projektu. W związku z tym biblioteki po stronie klienta nie są już przywracane w każdej kompilacji.

Niezależnie od ustawienia przywracania do kompilacji można ręcznie przywrócić w dowolnym momencie z menu kontekstowego libman.json . Aby uzyskać więcej informacji, zobacz Ręczne przywracanie plików.

Ręczne przywracanie plików

Aby ręcznie przywrócić pliki biblioteki:

• Dla wszystkich projektów w rozwiązaniu:
  • Kliknij prawym przyciskiem myszy nazwę rozwiązania w Eksplorator rozwiązań.
  • Wybierz opcję Przywróć biblioteki po stronie klienta.
• W przypadku określonego projektu:
  • Kliknij prawym przyciskiem libman.json myszy plik w Eksplorator rozwiązań.
  • Wybierz opcję Przywróć biblioteki po stronie klienta.

Podczas wykonywania operacji przywracania:

• Ikona Centrum stanu zadania (TSC) na pasku stanu programu Visual Studio będzie animowana i zostanie uruchomiona operacja przywracania. Kliknięcie ikony powoduje otwarcie etykietki narzędzia zawierającej listę znanych zadań w tle.

• Komunikaty będą wysyłane do paska stanu i kanału informacyjnego Menedżera biblioteki w oknie Dane wyjściowe . Na przykład:

  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
  

Usuwanie plików biblioteki

Aby wykonać operację czyszczenia , która usuwa pliki biblioteki, które zostały wcześniej przywrócone w programie Visual Studio:

• Kliknij prawym przyciskiem libman.json myszy plik w Eksplorator rozwiązań.
• Wybierz opcję Wyczyść biblioteki po stronie klienta.

Aby zapobiec przypadkowemu usunięciu plików innych niż biblioteka, operacja czyszczenia nie usuwa całych katalogów. Usuwa tylko pliki, które zostały uwzględnione w poprzednim przywracaniu.

Gdy operacja czyszczenia jest uruchomiona:

• Ikona TSC na pasku stanu programu Visual Studio będzie animowana i będzie odczytywać operację Biblioteki klienckie uruchomione. Kliknięcie ikony powoduje otwarcie etykietki narzędzia zawierającej listę znanych zadań w tle.
• Komunikaty są wysyłane do paska stanu i kanału informacyjnego Menedżera biblioteki w oknie Dane wyjściowe . Na przykład:

Clean libraries operation started...
Clean libraries operation completed
2 libraries were successfully deleted in 1.91 secs

Operacja czyszczenia usuwa tylko pliki z projektu. Pliki bibliotek pozostają w pamięci podręcznej w celu szybszego pobierania w przyszłych operacjach przywracania. Aby zarządzać plikami biblioteki przechowywanymi w pamięci podręcznej komputera lokalnego, użyj interfejsu wiersza polecenia LibMan.

Odinstalowywanie plików biblioteki

Aby odinstalować pliki biblioteki:

• Otwórz libman.json.

• Umieść daszek wewnątrz odpowiedniego libraries literału obiektu.

• Kliknij ikonę żarówki wyświetlaną na lewym marginesie, a następnie wybierz pozycję Odinstaluj <library_name>@<library_version>:

  

Alternatywnie możesz ręcznie edytować i zapisać manifest LibMan (libman.json). Operacja przywracania jest uruchamiana po zapisaniu pliku. Pliki biblioteki, które nie są już zdefiniowane w programie libman.json , są usuwane z projektu.

Aktualizowanie wersji biblioteki

Aby sprawdzić zaktualizowaną wersję biblioteki:

• Otwórz libman.json.
• Umieść daszek wewnątrz odpowiedniego libraries literału obiektu.
• Kliknij ikonę żarówki wyświetlaną na lewym marginesie. Zatrzymaj wskaźnik myszy nad pozycją Sprawdź dostępność aktualizacji.

Narzędzie LibMan sprawdza, czy wersja biblioteki jest nowsza niż zainstalowana wersja. Mogą wystąpić następujące wyniki:

• Jeśli zainstalowano już najnowszą wersję, zostanie wyświetlony komunikat Brak znalezionych aktualizacji.

• Jeśli nie zainstalowano jeszcze najnowszej stabilnej wersji, zostanie wyświetlona najnowsza stabilna wersja.

  

• Jeśli wersja wstępna jest nowsza niż zainstalowana wersja, zostanie wyświetlona wersja wstępna.

Aby zmienić starszą wersję biblioteki na starszą, należy ręcznie edytować libman.json plik. Po zapisaniu pliku operacja przywracania LibMan:

• Usuwa nadmiarowe pliki z poprzedniej wersji.
• Dodaje nowe i zaktualizowane pliki z nowej wersji.

Dodatkowe zasoby

• Używanie interfejsu wiersza polecenia programu LibMan z platformą ASP.NET Core
• Repozytorium programu LibMan w serwisie GitHub