SharePoint - Déploiement sélectif d'assets web provenant de paquets NuGet via un module

La solution conseillée pour déployer des fichiers dans une projet SharePoint est de créer un module et d’inclure dans celui-ci les différents fichiers à envoyer sur le site SharePoint ciblé. C’est facile, propre, efficace et tous les fichiers se retrouvent ainsi dans un répertoire choisi, par exemple au nom de notre solution, ou celui du module.

Mais aujourd’hui, une question m’est venue : comment déployer des bibliothèques JavaScript téléchargées et maintenues par NuGet, et les utiliser dans, par exemple, une “WebPart” ?

Je pensais que simplement référencer le chemin relatif dans le fichier “Elements.xml” de mon module suffirait mais : non.

Des recherches sur Google m’ont suggérées beaucoup de choses comme l’utilisation de dossiers mappés, simplement copier/coller les fichiers depuis le dossier “Scripts” dans un module, passer par des CDN, … Rien qui ne me convenait.

Du coup, je me suis mis à réfléchir, à tester… Et pour finir par trouver une solution propre, satisfaisante et qui devrait tenir la route. Je vais tout expliquer en partant d’un projet SharePoint complètement vide, on évitera la moindre confusion ainsi 😃

Le principe

Vu que les modules sont parfaits pour le déploiement des fichiers, je vais en utiliser un. On va gruger NuGet et appeler ce module “Scripts”, ainsi le dossier créé portera ce nom et NuGet déposera simplement les fichiers dedans. Pour le contexte, j’utilise ici un environnement de développement (une VM) avec Visual Studio 2015 et SharePoint 2016. En premier lieu, on va créer un nouveau projet SharePoint vide avec un nom qui indique bien que c’est uniquement pour des tests :

Ensuite, ciblez le site SharePoint sur lequel tester le projet. Pour le niveau de sécurité demandé, j’ai choisi “Deploy as farm solution”.

Après, on crée le module qui contiendra les scripts. Clic droit sur le projet “DeployNuGet” --> Add Item --> SharePoint Module.

Ici, il est important d’écrire “Scripts” comme nom de module (vu que ce sera le nom du dossier créé). Le dossier Features ainsi que la feature Feature1 seront également créés en même temps ; pratique !

Les features sont ce qui indiquent à Visual Studio quels fichiers exporter, quelles fonctionnalités activer, etc…

Une fois le module créé, on va passer sur NuGet et télécharger jQuery. Donc… Clic droit sur le projet puis “Manage NuGet Packages…”. De là, on prend la dernière version de jQuery et, après l’installation, on peut remarquer que le module “Scripts” s’est bien vu recevoir quelques fichiers supplémentaires - la librairie jQuery.

La sélection

Quand de nouveaux fichiers sont ajoutés à un module, ceux-ci sont directement insérés dans le fichier “Elements.xml”. Il donne des instructions à effectuer avec les fichiers présents dans le module : leur chemin local, leur destination sur le serveur SharePoint, s’il faut les ajouter à une liste, … On se retrouve donc avec un fichier ayant ce contenu :

1
2
3
4
5
6
7
8
9
10
11
12
13
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Module Name="Scripts">
<File Path="Scripts\Sample.txt" Url="Scripts/Sample.txt" />
<File Path="Scripts\jquery-3.2.1.slim.min.map" Url="Scripts/jquery-3.2.1.slim.min.map" />
<File Path="Scripts\jquery-3.2.1.slim.min.js" Url="Scripts/jquery-3.2.1.slim.min.js" />
<File Path="Scripts\jquery-3.2.1.slim.js" Url="Scripts/jquery-3.2.1.slim.js" />
<File Path="Scripts\jquery-3.2.1.min.map" Url="Scripts/jquery-3.2.1.min.map" />
<File Path="Scripts\jquery-3.2.1.min.js" Url="Scripts/jquery-3.2.1.min.js" />
<File Path="Scripts\jquery-3.2.1.js" Url="Scripts/jquery-3.2.1.js" />
<File Path="Scripts\jquery-3.2.1.intellisense.js" Url="Scripts/jquery-3.2.1.intellisense.js" />
</Module>
</Elements>

On va directement retirer les lignes inutiles pour ne garder que jquery-3.2.1.js (ce n’est de toute façon que pour l’exemple).

Ensuite, par souci de propreté, on va cibler la bibliothèque “Style Library” et mettre le fichier dans un dossier spécifique (pour éviter d’écraser d’éventuels autres fichiers, autant être prudent-e), tout en indiquant que l’on copie bien le fichier dans ce dossier…

Pour accomplir tout ceci on va :

  • Modifier le tag Module et lui ajouter l’attribut “Url” avec la valeur “Style Library”

  • Changer l’attribut “Url” du tag “File” de jQuery en remplaçant “Scripts/” par “TestAssets/js”

  • Ajouter à ce même tag l’attribut “Type” avec la valeur “GhostableInLibrary”

Pour plus d’infos sur ce que fait “GhostableInLibrary”: https://sharepoint.stackexchange.com/a/186407/52016

Ce qui nous donne ceci :

1
2
3
4
5
6
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Module Name="Scripts" Url="Style Library">
<File Path="Scripts\jquery-3.2.1.js" Url="TestAssets/js/jquery-3.2.1.js" Type="GhostableInLibrary" />
</Module>
</Elements>

Si on déploie le projet et qu’on se rend dans la Style Library (http://<url de déploiement>/Style Library/), on pourra y voir un tout nouveau dossier “TestAssets” dans lequel se trouve un dossier “js”, dans lequel se trouve notre bibliothèque jQuery :

Note : si le fichier n’a pas été déployé

Quand on déploie le projet, on déploie en réalité des Features. Notre module est référencé dans la feature nommée Feature1 et il se peut que cette dernière ne soit pas synchronisée avec l’état actuel du module. Pour régler ce problème, il suffit d’ouvrir la Feature1 et d’appuyer sur CTRL+S pour sauvegarder (et surtout resynchroniser) la feature avec le module.

Maintenance du module

“Mais que se passe-t-il si on ajoute une autre bibliothèque ?” était la première question qui m’est venue à l’esprit. Et bien, découvrons ensemble ce qu’il se passe… Nous avons jQuery, alors pourquoi ne pas prendre Boostrap ?

L’installation se déroule tranquillement et une fois finie, on peut découvrir que le fichier “Elements.xml” de notre module a été modifié…

1
2
3
4
5
6
7
8
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Module Name="Scripts" Url="Style Library">
<File Path="Scripts\jquery-3.2.1.js" Url="TestAssets/js/jquery-3.2.1.js" Type="GhostableInLibrary" />
<File Path="Scripts\bootstrap.min.js" Url="Scripts/bootstrap.min.js" />
<File Path="Scripts\bootstrap.js" Url="Scripts/bootstrap.js" />
</Module>
</Elements>

On peut donc en conclure deux choses : les lignes précédemment supprimées pointant vers les autres fichiers du module ne sont pas réapparues (yay!) et les nouveaux fichiers, ceux de bootstrap, ont été ajoutés.

Il ne reste plus qu’à retirer la première ligne de bootstrap (pour ne garder que la version minifiée), changer l’attribut Url comme précédemment ainsi qu’ajouter l’attribut Type avec la valeur GhostableInLibrary.

Et si on déploie à nouveau le projet puis que l’on se rend dans la Style Library à nouveau…

C’est exactement le résultat attendu 😃

Mais, bootstrap a aussi ajouté des fichiers CSS, dans un autre dossier ?

Oups. Je n’ai absolument pas fait exprès de prendre le cas de bootstrap pour montrer comme adapter un dossier déjà existant en module, non non. 😉

Dans le cas de bootstrap, un autre dossier nommé “Content” a été créé et contient une petite dizaine de fichiers. On en a bien évidemment besoin pour le bon fonctionnement de boostrap et nous allons donc, par conséquent, également les inclure dans un module pour pouvoir les exporter dans la Style Library, eux aussi.

La méthode la plus simple pour ce faire est la suivante :

  • Renommer le dossier “Content” en “ContentTMP” pour ne rien perdre

  • Créer un nouveau module du nom de "Content"

  • Déplacer tous les fichiers de “ContentTMP” dans "Content"

  • Supprimer le dossier "ContentTMP"

  • Adapter le fichier “Elements.xml” du module “Content” de la même façon que pour le module "Scripts"

  • Mettre à jour la feature “Feature1” en la sauvegardant

Et voilà ! Nous avons maintenant aussi accès aux fichiers CSS. Si d’autres modules NuGet créent d’autres dossiers, il suffira de simplement répéter cette même procédure pour chaque dossier ajouté.

Et si un paquet est supprimé de NuGet ?

Les fichiers référencés dans les différents Elements.xml disparaîtront de ces ceux-ci également, c’est aussi simple que cela.

Accéder aux fichiers déployés

En laissant le curseur sur un des fichiers de la Style Library, on peut voir quel est son lien absolu. Ce sera donc, par exemple, pour boostrap :

1
http(s)://<votre site>/Style Library/TestAssets/js/bootstrap.js

Il est bien évidemment possible de le référencer avec un lien relatif à partir de, par exemple, une WebPart. J’espère que cet article vous aura été aussi utile que possible 😃