Utiliser LibMan avec ASP.NET Core dans Visual Studio

Article
11/30/2023

Par Scott Addie

Visual Studio prend en charge LibMan dans les projets ASP.NET Core, avec notamment :

La prise en charge de la configuration et de l’exécution des opérations de restauration LibMan sur la build.
Les éléments de menu pour déclencher des opérations de restauration et de nettoyage LibMan.
La boîte de dialogue de recherche pour rechercher des bibliothèques et ajouter les fichiers à un projet.
La prise en charge de la modification de libman.json, le fichier manifeste LibMan.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)

Prérequis

Visual Studio 2019 avec la charge de travail ASP.NET et développement web

Ajouter des fichiers de bibliothèque

Les fichiers de bibliothèque peuvent être ajoutés à un projet ASP.NET Core de deux manières différentes :

Utiliser la boîte de dialogue Ajouter une bibliothèque côté client
Configurer manuellement les entrées de fichier manifeste LibMan

Utiliser la boîte de dialogue Ajouter une bibliothèque côté client

Procédez comme suit pour installer une bibliothèque côté client :

Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le dossier de projet dans lequel les fichiers doivent être ajoutés. Choisissez Ajouter>Bibliothèque côté client. La boîte de dialogue Ajouter une bibliothèque côté client s’affiche :
Sélectionnez le fournisseur de bibliothèque dans la liste déroulante Fournisseur. CDNJS est le fournisseur par défaut.
Tapez le nom de la bibliothèque à extraire dans la zone de texte Bibliothèque. IntelliSense fournit une liste de bibliothèques commençant par le texte fourni.
Sélectionnez la bibliothèque dans la liste IntelliSense. Notez que le nom de la bibliothèque comporte le symbole @ et la dernière version stable connue du fournisseur sélectionné en suffixe.
Déterminez les fichiers à inclure :
- Sélectionnez la case d’option Inclure tous les fichiers de bibliothèque pour inclure tous les fichiers de la bibliothèque.
- Sélectionnez la case d’option Choisir des fichiers spécifiques pour inclure un sous-ensemble des fichiers de la bibliothèque. Lorsque la case d’option est sélectionnée, l’arborescence du sélecteur de fichiers est activée. Cochez les cases situées à gauche des noms des fichiers à télécharger.

Spécifiez le dossier de projet pour le stockage des fichiers dans la zone de texte Emplacement cible. Comme recommandation, stockez chaque bibliothèque dans un dossier distinct.

Le dossier Emplacement cible suggéré est basé sur l’emplacement à partir duquel la boîte de dialogue a été lancée :

Si elle a été lancée à partir de la racine du projet :
- wwwroot/lib est utilisé si wwwroot existe.
- lib est utilisé si wwwroot n’existe pas.
Si elle est lancée à partir d’un dossier de projet, le nom de dossier correspondant est utilisé.

La suggestion de dossier présente le nom de la bibliothèque en suffixe. Le tableau suivant illustre les suggestions de dossier lors de l’installation de jQuery dans un projet Razor Pages.

Emplacement de lancement	Dossier suggéré
Racine du projet (si wwwroot existe)	wwwroot/lib/jquery/
Racine du projet (si wwwroot n’existe pas)	lib/jquery/
Dossier Pages dans le projet	Pages/jquery/

Cliquez sur le bouton Installer pour télécharger les fichiers, conformément à la configuration dans libman.json.

Pour plus d’informations sur l’installation, consultez le flux Gestionnaire de bibliothèques de la fenêtre Sortie. Par exemple :

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

Configurer manuellement les entrées de fichier manifeste LibMan

Toutes les opérations LibMan dans Visual Studio sont basées sur le contenu du manifeste LibMan de la racine du projet (libman.json). Vous pouvez modifier manuellement libman.json pour configurer les fichiers de bibliothèque pour le projet. Visual Studio restaure tous les fichiers de bibliothèque une fois libman.json enregistré.

Pour ouvrir libman.json pour modification, les options suivantes existent :

Double-cliquez sur le fichier libman.json dans l’Explorateur de solutions.
Cliquez avec le bouton droit sur le projet dans l’Explorateur de solutions, puis sélectionnez Gérer les bibliothèques côté client. †
Sélectionnez Gérer les bibliothèques côté client dans le menu Projet de Visual Studio. †

† Si le fichier libman.json n’existe pas encore à la racine du projet, il est créé avec le contenu du modèle d’élément par défaut.

Visual Studio offre une prise en charge complète de l’édition JSON enrichie, comme la colorisation, la mise en forme, IntelliSense et la validation de schémas. Le schéma JSON du manifeste LibMan se trouve à l’adresse https://json.schemastore.org/libman.

Avec le fichier manifeste suivant, LibMan récupère les fichiers selon la configuration définie dans la propriété libraries. Voici une explication des littéraux d’objet définis dans libraries :

Un sous-ensemble de jQuery version 3.3.1 est récupéré à partir du fournisseur CDNJS. Le sous-ensemble est défini dans la propriété files ; jquery.min.js, jquery.js et jquery.min.map. Les fichiers sont placés dans le dossier wwwroot/lib/jquery du projet.
L’intégralité de Bootstrap version 4.1.3 est récupérée et placée dans un dossier wwwroot/lib/bootstrap. La propriété provider du littéral d’objet remplace la valeur de la propriété defaultProvider. LibMan récupère les fichiers Bootstrap à partir du fournisseur unpkg.
Un sous-ensemble de Lodash a été approuvé par un organe directeur au sein de l’organisation. Les fichiers lodash.js et lodash.min.js sont récupérés à partir du système de fichiers local dans C:\temp\lodash\. Les fichiers sont copiés dans le dossier wwwroot/lib/lodash du projet.

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

Notes

LibMan ne prend en charge qu’une seule version de chaque bibliothèque de chaque fournisseur. Le fichier libman.json échoue à la validation du schéma s’il contient deux bibliothèques portant le même nom pour un fournisseur donné.

Restaurer des fichiers de bibliothèque

Pour restaurer des fichiers de bibliothèque à partir de Visual Studio, il doit y avoir un fichier libman.json valide dans la racine du projet. Les fichiers restaurés sont placés dans le projet à l’emplacement spécifié pour chaque bibliothèque.

Les fichiers de bibliothèque peuvent être restaurés dans un projet ASP.NET Core de deux manières :

Restaurer des fichiers pendant la génération
Restaurer des fichiers manuellement

Restaurer des fichiers pendant la génération

LibMan peut restaurer les fichiers de bibliothèque définis dans le cadre du processus de génération. Par défaut, le comportement de restauration sur build est désactivé.

Pour activer et tester le comportement de restauration sur build :

Cliquez avec le bouton droit sur libman.json dans l’Explorateur de solutions, puis sélectionnez Activer la restauration des bibliothèques côté client sur build dans le menu contextuel.
Cliquez sur le bouton Oui lorsque vous êtes invité à installer un package NuGet. Le package NuGet Microsoft.Web.LibraryManager.Build est ajouté au projet :
```
<PackageReference Include="Microsoft.Web.LibraryManager.Build" Version="1.0.113" />
```
Générez le projet pour confirmer que la restauration du fichier LibMan a lieu. Le package Microsoft.Web.LibraryManager.Build injecte une cible MSBuild qui exécute LibMan pendant l’opération de génération du projet.

Passez en revue le flux Build de la fenêtre Sortie pour un journal d’activité 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 ==========

Lorsque le comportement de restauration sur build est activé, le menu contextuel libman.json affiche une option Désactiver la restauration côté client bibliothèques sur build. La sélection de cette option supprime la référence de package Microsoft.Web.LibraryManager.Build du fichier projet. Par conséquent, les bibliothèques côté client ne sont plus restaurées sur chaque build.

Quel que soit le paramètre de restauration lors de la génération, vous pouvez effectuer une restauration manuelle à tout moment à partir du menu contextuel libman.json. Pour plus d’informations, consultez Restaurer des fichiers manuellement.

Restaurer des fichiers manuellement

Pour restaurer manuellement des fichiers de bibliothèque :

Pour tous les projets de la solution :
- Cliquez avec le bouton droit sur le nom de la solution dans l’Explorateur de solutions.
- Sélectionnez l’option Restaurer les bibliothèques côté client.
Pour un projet spécifique :
- Cliquez avec le bouton droit sur le fichier libman.json dans l’Explorateur de solutions.
- Sélectionnez l’option Restaurer les bibliothèques côté client.

Pendant l’exécution de l’opération de restauration :

L’icône du Centre d’état des tâches (TSC) dans la barre d’état de Visual Studio est animée et indique Opération de restauration démarrée. Cliquer sur l’icône ouvre une info-bulle répertoriant les tâches en arrière-plan connues.

Les messages sont envoyés à la barre d’état et au flux du Gestionnaire de bibliothèques de la fenêtre Sortie. Par exemple :

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

Supprimer des fichiers de bibliothèque

Pour effectuer l’opération de nettoyage, qui supprime les fichiers de bibliothèque précédemment restaurés dans Visual Studio :

Cliquez avec le bouton droit sur le fichier libman.json dans l’Explorateur de solutions.
Sélectionnez l’option Nettoyer les bibliothèques côté client.

Pour éviter la suppression involontaire de fichiers autres que ceux de la bibliothèque, l’opération de nettoyage ne supprime pas des répertoires entiers. Elle supprime uniquement les fichiers inclus dans la restauration précédente.

Pendant l’exécution de l’opération de nettoyage :

L’icône TSC dans la barre d’état de Visual Studio est animée et indique Opération de bibliothèques clientes démarrée. Cliquer sur l’icône ouvre une info-bulle répertoriant les tâches en arrière-plan connues.
Les messages sont envoyés à la barre d’état et au flux du Gestionnaire de bibliothèques de la fenêtre Sortie. Par exemple :

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

L’opération de nettoyage supprime uniquement les fichiers du projet. Les fichiers de bibliothèque restent dans le cache pour une récupération plus rapide lors des opérations de restauration futures. Pour gérer les fichiers de bibliothèque stockés dans le cache de l’ordinateur local, utilisez l’interface CLI LibMan.

Désinstaller les fichiers de bibliothèque

Pour désinstaller des fichiers de bibliothèque :

Ouvrez libman.json.
Positionnez le caret à l’intérieur du littéral d’objet libraries correspondant.
Cliquez sur l’icône d’ampoule qui s’affiche dans la marge gauche, puis sélectionnez Désinstaller <nom_bibliothèque>@<version_bibliothèque> :

Vous pouvez également modifier et enregistrer manuellement le manifeste LibMan (libman.json). L’opération de restauration s’exécute lorsque le fichier est enregistré. Les fichiers de bibliothèque qui ne sont plus définis dans libman.json sont supprimés du projet.

Mettre à jour la version de la bibliothèque

Pour rechercher une version de bibliothèque mise à jour :

Ouvrez libman.json.
Positionnez le caret à l’intérieur du littéral d’objet libraries correspondant.
Cliquez sur l’icône d’ampoule qui s’affiche dans la marge gauche. Pointez sur Rechercher les mises à jour.

LibMan recherche une version de bibliothèque plus récente que la version installée. Les résultats suivants peuvent se produire :

Un message Aucune mise à jour trouvée s’affiche si la dernière version est déjà installée.
La dernière version stable s’affiche si elle n’est pas déjà installée.
Si une préversion plus récente que la version installée est disponible, la préversion s’affiche.

Pour passer à une version antérieure de la bibliothèque, modifiez manuellement le fichier libman.json. Lorsque le fichier est enregistré, l’opération de restauration LibMan :

Supprime les fichiers redondants de la version précédente.
Ajoute les fichiers nouveaux et mis à jour à partir de la nouvelle version.

Partager via