SharePoint Framework (SPfx) : getting started and Deep Dive (Partie 3/3)

SPfx et Azure Devops (VSTS) pour l’intégration/livraison continue (CI/CD)

L’automatisation des processus de compilation et/ou de déploiement CI/CD de tout type de solutions est extrêmement puissant . Azure Devops ( nommé avant VSTS “Visual Studio Team Services”) permet de le faire via des modèles (templates) prédéfinis pilotés par des tâches (étapes) permettant l’exécution d’un processus complet pour industrialiser la chaîne de compilation et/ou l’installation des environnements. (Pour plus d’info Cliquez ici)

Pour la plupart des solutions SharePoint Framework (SPfx) qu’on veut mettre en place, on peut avoir une chaîne d’intégration continue CI/C. Une fois la solution prête et compilée, elle se déploiera automatiquement dans l’environnement souhaité (Développement, Recette et Production).

Dans les deux parties qui précèdent, je vous ai présenté l’historique concernant les évolutions de la plateforme SharePoint/Office 365 et les bonnes pratiques pour ceux qui veulent bien s’y mettre sur le nouveau framework SPfx :

• Partie 1 : SharePoint Sites modernes et la nouvelle expérience utilisateur !
• Partie 2 : Bonnes pratiques et optimisations SPfx, intégrer Office Fabric UI et les tests unitaires
• Partie 3 : SPfx et VSTS/DevOps pour l’intégration/livraison continue

Le but de cette dernière partie est de se focaliser sur l’industrialisation des solutions SPfx depuis la compilation jusqu’à l’installation et la mise en oeuvre. En effet, je vais expliquer également comment parvenir à construire une chaîne d’intégration et de livraison continue via Gulp.js ou Office 365 CLI.

Utiliser Gulp dans votre chaîne CI/CD

Pour commencer, j’ai utilisé un nouveau projet SPfx hébergé sur Azure Devops en utilisant Git. Une fois créé, on doit configurer la solution elle-même en créant des tâches Gulp et en les ajoutant dans le fichier gulpfile.js du projet SPfx (pour ceux qui ne connaissent pas les tâches Gulp, je vous invite à consulter cet article introductif sur Gulp).

• Configurer les tâches Gulp :

 1) Tâche de mise à jour du manifest (cela sera utilisé pendant l’étape de build) :

La première tâche à ajouter au fichier gulpfile.js consiste à mettre à jour le fichier “write-manifests.json” en remplaçant le chemin CDN où on va exporter nos fichiers sources du projet.

💡 Pourquoi un CDN ? En effet, il existe plusieurs options d’hébergement très différentes pour vos composants WebPart. On peut soit opter pour l’option CDN Office 365, mais vous pouvez aussi utiliser le CDN Azure ou simplement héberger vos ressources statiques dans la bibliothèque SharePoint de votre client. (plus d’info)

💡 La tâche utilise un argument cdnpath pour que vous puissiez le passer en argument via la ligne de commande :gulp update-manifest --cdnpath https://<your-cdn-location>

2) Exporter les fichiers de script et le package de la solution & déploiement (cela sera utilisé pendant l’étape de Release) :

La prochaine étape consiste à créer les deux tâches permettant d’exporter les fichiers javascript et le package de solution sur SharePoint. La dernière tâche permet de déployer le package de la solution précédemment téléchargée dans le catalogue SharePoint pour l’activer.

💡 Désormais, les tâches Gulp utilisent des arguments de ligne de commande que vous pouvez transmettre en exécutant la tâche. De cette façon, vous pouvez gérer la configuration de vos environnements dans la chaîne d’intégration continue Azure Devops.

Voilà les étapes à suivre :

1. Installer gulp-spsync-creds et node-sppkg-deploy comme étant des DevDependencies (pour plus d’info) du package.json dans votre projet: npm install gulp-spsync-creds node-sppkg-deploy -D -E
2. Ajouter le script des tâches ci-dessous dans votre fichier gulpfile.js :

Pour exécuter et tester ces tâches, lancez les commandes ci-dessous :

• gulp upload-to-sharepoint --ship --username $(username) --password $(password) --tenant $(tenant) --cdnsite $(cdnsite) --cdnlib $(cdnlib)
• gulp upload-app-pkg --ship --username $(username) --password $(password) --tenant $(tenant) --catalogsite $(catalogsite)

• gulp deploy-sppkg --ship --username $(username) --password $(password) --tenant $(tenant) --catalogsite $(catalogsite)

• Configurer la définition de compilation (Build) dans Azure Devops :

Dans votre projet, sur Azure Devops, accédez à la section Pipeline -> Build. Là, vous aurez la possibilité de créer une nouvelle définition de build. Lorsque vous créez une nouvelle définition, plusieurs modèles vous seront présentés. Dans la barre de recherche, vous devriez avoir le template “NodeJS with Gulp”.

Une fois créé, vous devez ajouter deux tâches de groupe supplémentaires en cliquant sur le lien Ajouter une tâche.

💡 Pour la définition de Build, vous ne devez configurer que les tâches Gulp. Toutes les autres tâches peuvent être configurées par défaut.

La tâche de mise à jour de la version du package qui va être déployée :

• Tâche Gulp : version-sync
• Arguments : –BuildNumber $(Build.BuildNumber)

💡 Il est recommandé d’affecter une version appropriée de votre projet SPfx en lui appliquant une version unique à la création du package compilé. Ci-dessous la tâche que j’utilise souvent pour me créer une nouvelle version à chaque compilation :

La tâche de mise à jour du CDN doit être configurée comme suit:

• Tâche Gulp : Update-manifest
• Arguments : –cdnpath votre-emplacement-cdn

La tâche de création du Bundle doit être configurée comme suit:

• Tâche Gulp : bundle
• Arguments : –ship

La dernière tâche consiste à préparer le package de la solution et doit être configurée comme suit:

• Tâche Gulp : package-solution
• Arguments : –ship

 Pour déclencher automatiquement le processus de Build dès que vous poussez le code vers le système de contrôle de source, vous devez configurer l’onglet Triggers (déclencheur de lancement) :

Sauvegardez cette configuration et passez maintenant à la configuration de la Release.

• Configurer la définition de publication (Release) dans Azure DevOps :

Dès que la définition de Build est prête, la dernière étape consiste à configurer la définition de publication.

La première étape consiste à accéder à l’onglet des “Release”, que vous pouvez trouver sous l’onglet “Pipeline”, et à créer une nouvelle définition de Release comme suit :

Une fois la définition de la Release créée, cliquez sur le menu Environnement et choisissez de configurer les variables :

En définissant des variables pour la Release, qui représentent les arguments d’entrés pour les tâches Gulp, la maintenance est simplifiée car vous pouvez les modifier facilement pour tous vos environnements. Ci-dessous les variables que vous devez créer :

• username : Le nom d’utilisateur qui sera utilisé pour télécharger les fichiers sur SharePoint
• password : Le mot de passe du compte
• tenant : Uniquement le nom du tenant qui sera utilisé pour construire le chemin du CDN: https://<tenant>.sharepoint.com
• cdnlib : Nom du CDN dans le site du cdn
• catalogsite : Chemin relatif de votre catalogue des applications sur Office 365.
• cdnsite : Chemin relatif du site où le CDN est localisé (Attention, ne mettez rien si c’est un site parent !).

Passons maintenant à la création des tâches pour la définition de la Release !

La tâche d’exportation du Bundle dans une bibliothèque Sharepoint doit être configurée comme suit :

• Tâche Gulp: Upload-to-Sharepoint
• Arguments:  –ship –username $(username) –password $(password) –tenant $(tenant) –cdnsite $(cdnsite) –cdnlib $(cdnlib)

La tâche du téléchargement du package dans le catalogue du tenant Office 365 doit être configurée comme suit :

• Tâche Gulp : Upload-app-Package
• Arguments :  –ship –username $(username) –password $(password) –tenant $(tenant) –catalogsite $(catalogsite)

La tâche de déploiement du package dans le catalogue du tenant Office 365 doit être configurée comme suit :

• Tâche Gulp : Deploy-sppkg
• Arguments : –ship –username $(username) –password $(password) –tenant $(tenant) –catalogsite $(catalogsite)

Et voilà ! La définition de la Release est maintenant terminée. Après cette étape, il est temps de la tester en transmettant une nouvelle version sur Git et en vérifiant que le processus de construction et de publication est automatiquement déclenché.

Utiliser Office 365 CLI dans votre chaîne CI/CD

Office 365 CLI est une Interface en Ligne de Commande multi-plateforme permettant de gérer divers paramètres de configuration sur Office 365. La CLI a évolué rapidement, et il ne manquait qu’une seule chose pour l’intégrer facilement dans un pipeline de CI/CD : l’authentification via un nom d’utilisateur et mot de passe.

A partir de la version 1.2.0 de la CLI Office 365, il est désormais possible de s’authentifier en fournissant des informations d’identification permettant de simplifier l’utilisation de la CLI dans Azure DevOps. (Pour plus d’informations sur la CLI Cliquez ici)

⚠️ Il faut noter qu’on va utiliser Office 365 CLI uniquement pour la définition de Release. Pour la définition de Build il faut toujours utiliser des tâches Gulp comme indiqué dans la première partie ci-dessus.

💡 En revanche Office 365 CLI est plus commode et maintenable pour mettre en place une définition de Release au lieu des tâches Gulp qui doivent être dans la solution et qui nécessitent si besoin des modifications dans le projet, les pousser après sur Git et le lancement automatique du Build en l’occurrence.

• Mettre en place la définition de compilation (les blocs de Build) par défaut

La première chose à créer est votre pipeline de compilation dans lequel vous allez installer les dépendances du projet et créer un package de solution SPfx. Ce processus est similaire à celui décrit dans la première partie ci-dessus.

⚠️ Il est recommandé d’utiliser la version Node 8.x à partir de la version 1.4.1 du générateur du framework SPfx (Pour plus d’info Cliquez Ici).

💡 La seule différence par rapport à ce qui a été décrit précédemment, c’est qu’on va ajouter une nouvelle tâche dans notre modèle qui consiste à installer Node 8.x, cette tâche permet de spécifier la version du Node à utiliser pendant le processus de compilation.

Et dans la configuration de cette tâche il suffit de bien configurer la bonne version comme indiqué ci-dessous :

• Utilisation de la CLI Office 365 dans la définition de Release

Maintenant qu’on a terminé la définition de Build et qu’en flux de sortie on a l’archive du package SPfx, la prochaine étape consiste à définir les tâches qui utiliseront l’interface de ligne de commande Office 365.

A la fin, vous aurez, comme présenté ci-dessous, une liste des tâches nécessaires pour ajouter et déployer le package de solution sur votre tenant :

1) Tâche d’installation d’Office 365 CLI :

Ceci est une tâche npm (Node Package Manager) définie avec une commande personnalisée. La commande permet d’installer la CLI Office 365 :

2) Tâche de connexion au catalogue des applications SharePoint :

Il s’agit d’une tâche de ligne de commande qui utilise la CLI Office 365 pour se connecter au site du catalogue à l’aide de la commande suivante : o365 spo connect https://[TENANT].sharepoint.com/sites/catalog –authType password –userName $(username) –password $(password)

💡  $(username) et $(password) sont des variables que j’ai configurées dans ma pipeline de Build précédemment.

3) Tâche de téléchargement de la solution SPfx dans le catalogue du tenant :

Il s’agit d’une tâche de ligne de commande qui ajoute le package de solution SharePoint créé au catalogue du tenant Office 365 à l’aide de la commande suivante: o365 spo app add -p $(System.DefaultWorkingDirectory)/sharepoint/solution/my-solution-name.sppkg –overwrite

💡 $(System.DefaultWorkingDirectory) est une variable d’environnement du système créée automatiquement qui représente le chemin local de l’agent dans lequel vos fichiers de code source sont archivés après la fin d’exécution de la chaîne de build.

4) Tâche de déploiement du package de la solution SPfx :

Cette tâche de type ligne de commande consiste à parcourir la liste des applications SharePoint disponibles dans le catalogue du tenant, trouvez celle qui nous intéresse actuellement et la déployer :

Et voilà ! La définition de Release est maintenant terminée. Après cette étape, il est temps de tester en transmettant une nouvelle version sur Git, en vérifiant que le processus de build et de publication s’exécutent bien et que votre solution a été bien déployée sur votre tenant 

Conclusion

Dans cette dernière partie de la série qui a pour but de bien se pencher sur le nouveau framework Sharepoint SPfx, j’ai abordé la dernière étape qui consiste à industrialiser vos composants depuis la compilation jusqu’à l’installation dans l’environnement de production.

L’automatisation des processus d’installation et de déploiement (Devops) de tout type de solution est une partie importante que le développeur doit connaître afin qu’il ait une vue globale sur le cycle de vie de son code et par la suite il pourra prendre les mesures adéquates pour la consolidation des composants maintenables et productifs dans le futur.

J’espère que cette suite vous sera utile pour vos développements, Good luck !