Chaîne d’outils de SharePoint Framework

  • Article

La chaîne d’outils de SharePoint Framework est un ensemble d’outils de génération, de packages d’infrastructure et d’autres éléments qui vous permettent de gérer la création et le déploiement de vos projets côté client.

Que vous apporte la chaîne d’outils ?

  • Elle vous aide à générer des composants côté client, tels que des composants WebPart.
  • Elle vous aide à tester des composants côté client dans votre environnement de développement local avec des outils tels que SharePoint Workbench.
  • Elle vous permet de mettre en package et de déployer vos projets sur SharePoint.
  • Elle vous fournit un ensemble de commandes de génération qui vous aident à effectuer des tâches de génération clés, telles que la compilation de code, l’empaquetage de votre projet côté client dans un package d’application SharePoint, et bien plus encore.

Importante

Le service Workbench local ne prend pas en charge Internet Explorer 11.

Utilisation des packages npm

Avant de plonger dans les différents composants de la chaîne d’outils, il est important de comprendre comment l’infrastructure SharePoint utilise npm pour gérer différents modules dans le projet. npm est l’un des principaux gestionnaires de packages open source pour le développement JavaScript côté client.

Un package npm classique se compose d’un ou de plusieurs fichiers de code JavaScript réutilisables, appelés modules, ainsi que d’une liste des packages de dépendances. Lorsque vous installez le package, npm installe également ces dépendances.

Le registre npm officiel se compose de centaines de packages que vous pouvez télécharger pour créer votre application. Vous pouvez également publier vos propres packages dans npm et les partager avec d’autres développeurs. SharePoint Framework utilise certains packages npm de la chaîne d’outils et publie ses propres packages dans le registre npm.

Packages SharePoint Framework

SharePoint Framework est composé de plusieurs packages npm combinables qui vous aident à créer des expériences côté client dans SharePoint.

SharePoint Framework comprend les packages npm suivants :

  • @microsoft/generator-sharepoint : plug-in Yeoman à utiliser avec SharePoint Framework. À l’aide de ce générateur, les développeurs peuvent configurer rapidement un projet de composant WebPart côté client avec des valeurs par défaut adaptées et des pratiques recommandées.
  • @microsoft/sp-client-base : définit les bibliothèques principales pour les applications côté client créées à l’aide de SharePoint Framework.
  • @microsoft/sp-webpart-workbench : SharePoint Workbench est un environnement autonome permettant de tester et de déboguer les composants WebPart côté client.
  • @microsoft/sp-module-loader : chargeur de modules qui gère le contrôle des versions et le chargement des composants côté client, WebPart et autres. Il fournit également des services de diagnostic de base. Conçu selon des normes bien connues, comme SystemJS et WebPack, il correspond à la première partie de SharePoint Framework à charger sur une page.
  • @microsoft/sp-module-interfaces : définit plusieurs interfaces de module qui sont partagées par le chargeur de module de SharePoint Framework et par le système de génération.
  • @microsoft/sp-lodash-subset : fournit un fichier groupé lodash personnalisé à utiliser avec le chargeur de modules de SharePoint Framework. Pour améliorer les performances du runtime, il inclut uniquement un sous-ensemble des fonctions Lodash essentielles.
  • @microsoft/sp-tslint-rules : définit des règles tslint personnalisées à utiliser avec les projets côté client SharePoint.
  • @microsoft/office-ui-fabric-react-bundle : fournit un fichier groupé office-ui-fabric-react personnalisé, optimisé pour une utilisation avec le chargeur de modules de SharePoint Framework.

Packages d’outils de génération communs

Outre les packages SharePoint Framework, un ensemble commun d’outils est également utilisé pour effectuer des tâches de création, telles que la compilation de code TypeScript en code JavaScript et la conversion SCSS-CSS.

Les packages d’outils de génération npm communs suivants sont inclus dans SharePoint Framework :

Génération automatique de modèles pour un nouveau projet côté client

Le générateur SharePoint structure un projet côté client avec un composant WebPart. Le générateur télécharge et configure également les composants requis de la chaîne d’outils pour le projet côté client spécifié.

Installer des packages npm

Le générateur installe les packages npm requis localement dans le dossier du projet. Npm vous permet d’installer un package, soit localement sur votre projet, soit globalement. Les deux options ont leurs avantages, mais la solution généralement recommandée est d’installer les packages npm localement, si votre code dépend de ces modules de package. Dans le cas d’un projet de composant WebPart, le code de votre composant WebPart dépend des différents packages de génération SharePoint et communs, et requiert donc que ces packages soient installés localement.

Comme les packages sont installés localement, npm installe également les dépendances associées à chacun. Vous pouvez trouver les packages installés sous le dossier node_modules dans le dossier de votre projet. Ce dossier contient les packages, ainsi que toutes leurs dépendances. Dans l’idéal, ce dossier doit contenir des dizaines ou des centaines de dossiers, car les packages npm sont toujours décomposés en modules plus petits, ce qui entraîne l’installation de dizaines ou de centaines de packages. Les packages de clé SharePoint Framework se trouvent sous le dossier node_modules@microsoft. Le @microsoft est une étendue npm qui représente collectivement les packages publiés par Microsoft.

Chaque fois que vous créez un projet à l’aide du générateur, ce dernier installe localement les packages d’infrastructure SharePoint correspondant à ce projet spécifique, ainsi que leurs dépendances. De cette façon, npm facilite la gestion de vos projets de composant WebPart sans affecter d’autres projets dans l’environnement de développement local.

Spécifier les dépendances avec le fichier package.json

Le fichier package.json du projet côté client spécifie la liste des dépendances dont dépend le projet. La liste définit les dépendances à installer. Comme décrit précédemment, chaque dépendance peut contenir d’autres dépendances. Npm vous permet de définir des dépendances de runtime et de génération pour votre package à l’aide des propriétés dependencies et devDependencies. La propriété devDependencies est utile quand vous souhaitez utiliser ce module dans votre code, par exemple pour générer des composants WebPart.

Vous trouverez ci-dessous la propriété package.json du composant helloworld-webpart.

{
  "name": "helloword-webpart",
  "version": "0.0.1",
  "private": true,
  "engines": {
    "node": ">=0.10.0"
  },
  "dependencies": {
    "@microsoft/sp-client-base": "~1.0.0",
    "@microsoft/sp-core-library": "~1.0.0",
    "@microsoft/sp-webpart-base": "~1.0.0",
    "@types/webpack-env": ">=1.12.1 <1.14.0"
  },
  "devDependencies": {
    "@microsoft/sp-build-web": "~1.0.0",
    "@microsoft/sp-module-interfaces": "~1.0.0",
    "@microsoft/sp-webpart-workbench": "~1.0.0",
    "gulp": "~3.9.1",
    "@types/chai": ">=3.4.34 <3.6.0",
    "@types/mocha": ">=2.2.33 <2.6.0"
  },
  "scripts": {
    "build": "gulp bundle",
    "clean": "gulp clean",
    "test": "gulp test"
  }
}

Bien qu’il existe de nombreux packages installés pour le projet, ils sont uniquement nécessaires pour la création du composant WebPart dans l’environnement de développement. Ces packages vous permettent d’utiliser ces modules, ainsi que de générer, de compiler et d’insérer votre composant WebPart dans un fichier groupé et dans un package pour le déploiement. La dernière version incluse dans un fichier groupé et réduite du composant WebPart que vous déployez sur un serveur CDN ou sur SharePoint n’inclut aucun de ces packages. Cela dit, vous pouvez également configurer le déploiement de manière à inclure certains modules selon vos besoins. Pour en savoir plus, consultez l’article Ajouter une bibliothèque externe à votre composant WebPart côté client SharePoint.

Utiliser les systèmes de contrôle de code source

À mesure que les dépendances du projet augmentent, le nombre de packages à installer augmente également. N’archivez pas le dossier node_modules, contenant toutes les dépendances, dans votre système de contrôle de code source. Excluez plutôt le dossier node_modules de la liste des fichiers à ignorer pendant les archivages.

Si vous utilisez git comme système de contrôle source, les modèles du projet de composant WebPart générés par Yeoman comprennent un fichier .gitignore qui exclut le dossier node_modules, entre autres.

Lorsque vous consultez ou clonez pour la première fois le projet de composant WebPart à partir de votre système de contrôle de code source, exécutez la commande suivante pour initialiser et installer toutes les dépendances du projet localement :

npm install

Une fois cette commande exécutée, npm analyse le fichier package.json et installe les dépendances requises.

Mise à jour des informations pour les développeurs

Depuis la version 1,11, le manifeste de la solution défini dans le fichier package-solution. JSON a été étendu avec la section developer qui vous permet de stocker des informations supplémentaires sur votre organisation. Les informations de cette section sont validées lorsque vous publiez votre solution sur Marketplace. Même si vous créez une solution pour une utilisation interne, nous vous recommandons de remplir les différentes propriétés dans votre manifeste de solution. Si vous spécifiez ces informations, vous pourrez peut-être accéder à des informations supplémentaires sur l’utilisation de votre application.

Importante

Si vous choisissez d’exposer vos composants WebPart dans Microsoft Teams, les utilisateurs verront les informations de la section developer lors de l’installation de votre application dans Teams.

Importante

La section développeur doit contenir des informations valides pour toute solution SharePoint Framework qui sera disponible à partir de l’Office Store ou de AppSource.

Les propriétés suivantes sont disponibles dans la section developer :

Attribut Description Obligatoire
name Nom de l’organisation ayant créé l’application. Oui
websiteUrl URL d’un site web contenant des informations supplémentaires sur l’application Oui
mpnId ID Microsoft Partner Network (plus de détails sur réseau de partenaires MS) Non (mais vivement recommandé)
privacyUrl URL de déclaration de confidentialité. Oui
termsOfUseUrl URL des conditions d'utilisation Oui

Création de tâches

SharePoint Framework utilise Gulp en tant qu’outil d’exécution de tâches pour gérer les processus suivants, entre autres :

  • Regrouper et réduire les fichiers JavaScript et CSS.
  • Exécuter des outils pour appeler les tâches de regroupement et de réduction avant chaque génération.
  • Compiler les fichiers LESS ou Sass dans un fichier CSS.
  • Compiler les fichiers TypeScript dans un fichier JavaScript.

La chaîne d’outils comprend les tâches Gulp suivantes, définies dans le package @microsoft/sp-build-core-tasks :

  • build : génère le projet de solution côté client.
  • bundle : regroupe le point d’entrée du projet de solution côté client et toutes ses dépendances dans un seul fichier JavaScript.
  • serve : fournit le projet de solution côté client et ses ressources sur l’ordinateur local.
  • clean : supprime les artefacts de génération du projet de solution côté client de la génération précédente et des répertoires de génération cible (lib et dist).
  • test : exécute des tests d’unité, si l’option est disponible, pour le projet de solution côté client.
  • package-solution : inclut la solution côté client dans un package SharePoint.
  • deploy-azure-storage : déploie les composants du projet de solution côté client dans le stockage Azure.

Pour lancer des tâches différentes, ajoutez le nom de la tâche à la commande Gulp. Par exemple, pour compiler votre composant WebPart et en afficher un aperçu dans SharePoint Workbench, exécutez la commande suivante :

gulp serve

Remarque

vous ne pouvez pas exécuter plusieurs tâches simultanément.

La tâche serve exécute les différentes sous-tâches et lance SharePoint Workbench.

Tâches Gulp « serve »

Cibles de génération

Dans la capture d’écran précédente, vous pouvez voir que la tâche indique votre cible de génération comme suit :

Build target: DEBUG

Si aucun paramètre n’est spécifié, les commandes ciblent le mode BUILD. Si le paramètre ship est spécifié, les commandes ciblent le mode SHIP.

En règle générale, quand votre projet de composant WebPart est prêt à être livré ou déployé dans un serveur de production, ciblez SHIP. Dans d’autres scénarios, par exemple pour des opérations de test ou de débogage, ciblez plutôt BUILD. La cible SHIP garantit également que la version réduite du fichier groupé de composants WebPart est générée.

Pour cibler le mode SHIP, ajoutez --ship à la tâche :

gulp --ship

En mode DEBUG, les tâches de génération (build) copient toutes les ressources de composant WebPart, y compris le fichier groupé de composants WebPart, dans le dossier dist.

En mode SHIP, les tâches de génération (build) copient toutes les ressources de composant WebPart, y compris le fichier groupé de composants WebPart, dans le dossier temp\deploy.

Voir aussi