Chaîne d’outils de SharePoint Framework
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.
Important
Le service Workbench local ne prend pas en charge Internet Explorer 11.
Utilisation des packages npm
Avant de vous plonger dans les différents composants de la chaîne d’outils, il ’ est important de comprendre comment SharePoint Framework utilise npm pour gérer différents modules dans le projet. npm est l’un des gestionnaires de package open source préférés pour le développement côté client JavaScript.
Un paquetage npm typique se compose d'un ou plusieurs fichiers de code JavaScript réutilisables, appelés modules, ainsi que d'une liste de paquets de dépendances. Lorsque vous installez le paquet, 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 n’utilise pas uniquement certains packages npm de la chaîne d’outils, mais publie également 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 pour tester et déboguer des 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 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 pour l’utilisation avec les projets côté client SharePoint.
- @microsoft/office-ui-fabric-react-bundle. Fournit une offre groupée personnalisée de office-ui-fabric-react optimisé pour une utilisation avec le chargeur de module 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 :
- @microsoft/sp-build-core-tasks : ensemble de tâches pour le système de génération de SharePoint Framework, fondé sur Gulp. Le package sp-build-core-tasks implémente des opérations propres à SharePoint, telles que le package de solutions et l’écriture de manifestes.
- @microsoft/sp-build-web : importe et configure un ensemble de tâches de génération qui sont adaptées à une cible de génération exécutée dans un navigateur web (et non dans un environnement Node.js). Ce package est conçu pour être importé directement par un fichier Gulp qui utilise le système de génération de SharePoint Framework.
- @microsoft/gulp-core-build : tâches de génération Gulp principales nécessaires pour utiliser les formats de génération TypeScript, HTML, less et autres. Ce package dépend de plusieurs autres packages npm qui contiennent les tâches suivantes :
- @microsoft/gulp-core-build-typescript
- @microsoft/gulp-core-build-sass
- @microsoft/gulp-core-build-webpack
- @microsoft/gulp-core-build-serve
- @microsoft/gulp-core-build-karma
- @microsoft/gulp-core-build-mocha @microsoft/loader-cased-file. wrapper pour le chargeur de fichiers de webpack, qui peut être utilisé pour modifier la casse du nom du fichier obtenu. Cette fonctionnalité est utile dans certains scénarios, par exemple quand vous utilisez un réseau de distribution de contenu (CDN) qui autorise uniquement les noms de fichiers en minuscules.
- @microsoft/loader-load-themed-styles : chargeur qui inclut le chargement de feuilles CSS dans un script équivalent à
require('load-themed-styles').loadStyles( /* css text */ ). Il est conçu pour remplacer le chargeur de styles. - @microsoft/loader-raw-script. Chargeur qui charge le contenu d’un fichier de script directement dans un bundle webpack à l’aide d’un
eval(…). - @microsoft/loader-set-webpack-public-path. Chargeur qui définit la variable webpack_public_path sur une valeur spécifiée dans les arguments, éventuellement ajoutée à la propriété SystemJS baseURL.
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 paquets npm requis localement dans le dossier du projet. npm vous permet d'installer un paquet soit localement dans votre projet, soit globalement. Les deux options présentent des avantages, mais le conseil général est d'installer les packages npm localement si votre code dépend de ces modules. Dans le cas d'un projet de composant Web, le code de votre composant Web dépend de divers paquets SharePoint et de paquets de construction communs, et nécessite donc que ces paquets 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 principaux packages SharePoint Framework se trouvent sous le dossier node_modules@microsoft. La @microsoft est une étendue npm qui représente collectivement 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 SharePoint Framework 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 interférer avec les autres projets qui se trouvent 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 indiqué précédemment, chaque dépendance peut en contenir plusieurs autres. npm vous permet de définir à la fois les dépendances de runtime et de génération de votre package à l’aide des propriétés dependencies et devDependencies. La propriété devDependencies s’utilise lorsque vous souhaitez utiliser ce module dans votre code, par exemple pour créer 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. Vous ne devez pas archiver le dossier node_modules, qui contient toutes les dépendances, dans votre système de contrôle de code source. Vous devez exclure la propriété node_modules de la liste des fichiers à ignorer au cours des 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.
Important
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.
Important
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
Notes
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.

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.
Habituellement, lorsque votre projet de composant Web est prêt à être expédié ou déployé dans un serveur de production, vous ciblez SHIP. Pour d'autres scénarios, tels que les tests et le débogage, vous ciblez BUILD. La cible SHIP permet également de s'assurer que la version miniaturisée du bundle web part est construite.
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.