Débogage de solutions SharePoint Framework sur des pages SharePoint modernes

Lorsque vous développez des solutions SharePoint Framework, vous pouvez les tester sur des pages SharePoint modernes. Pour créer des extensions SharePoint Framework, le test sur des pages modernes est la seule option, étant donné que pour l’instant le workbench SharePoint ne prend pas en charge le chargement d’extensions. Toutefois, le test sur des pages modernes peut également être utilisé pour le débogage de composants WebPart afin de proposer aux développeurs des avantages supplémentaires.

Important

Bien qu’il n’existe aucune restriction technique pour le débogage de solutions SharePoint Framework locales sur des pages SharePoint modernes, vous devez faire attention lorsque vous les utilisez dans votre client de production. Cette fonctionnalité vous permet d’exécuter du code qui n’a pas été testé et vérifié par rapport aux stratégies de votre organisation et peut nuire à vos données de production.

Débogage d’extensions SharePoint Framework sur des pages SharePoint modernes

Actuellement, l’extension SharePoint Framework peut être déboguée uniquement sur des pages SharePoint modernes. Le workbench SharePoint ne prend pas en charge les extensions de test. Selon la version de SharePoint Framework que vous utilisez, il existe différentes manières de déboguer des extensions sur des pages modernes.

Débogage d’extensions à l’aide d’une configuration d’utilisation

Lorsque vous ajoutez une extension SharePoint Framework à votre projet, le générateur Yeoman SharePoint Framework étend la configuration de votre projet. À l’aide de cette configuration, vous pouvez lancer automatiquement une page SharePoint moderne dans votre navigateur web avec tous les paramètres requis pour déboguer l’extension sur la page déjà présente.

Fonctionnement

Lorsque vous ajoutez une nouvelle extension SharePoint Framework à votre projet, le générateur Yeoman SharePoint Framework ajoute une nouvelle entrée au fichier config/serve.json dans votre projet. Un exemple d’entrée se présente comme suit :

{
  "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
  "port": 4321,
  "https": true,
  "serveConfigurations": {
    "default": {
      "pageUrl": "https://contoso.sharepoint.com/sites/mySite/SitePages/myPage.aspx",
      "customActions": {
        "d7678bd7-b58a-44fc-b9fa-a621a89edcad": {
          "location": "ClientSideExtension.ApplicationCustomizer",
          "properties": {
            "testMessage": "Test message"
          }
        }
      }
    },
    "helloWorld": {
      "pageUrl": "https://contoso.sharepoint.com/sites/mySite/SitePages/myPage.aspx",
      "customActions": {
        "d7678bd7-b58a-44fc-b9fa-a621a89edcad": {
          "location": "ClientSideExtension.ApplicationCustomizer",
          "properties": {
            "testMessage": "Test message"
          }
        }
      }
    }
  }
}

En regard de la configuration par défaut, le générateur Yeoman SharePoint Framework crée une entrée pour chaque extension que vous ajoutez à votre projet. Chaque entrée contient une URL de la page moderne qui doit être utilisée pour tester une extension spécifique, la liste des extensions devant être chargées et la liste des propriétés devant être définies sur chaque extension. Pour utiliser une configuration d’utilisation spécifique, exécutez la ligne de commande suivante :

gulp serve --config=<name>

par exemple :

gulp serve --config=helloWorld

Après avoir exécuté cette commande, Gulp lance votre navigateur web avec la page moderne spécifiée dans votre configuration. La page affiche une fenêtre contextuelle qui vous invite à confirmer que vous chargez désormais les scripts de débogage.

Fenêtre contextuelle permettant de confirmer le chargement des scripts de débogage sur une page moderne dans SharePoint Online

Une fois la vérification effectuée, la page se charge avec les extensions spécifiées dans votre configuration d’utilisation.

Désactivation des scripts de débogage

Par défaut, lorsque les scripts de débogage sont activés et autorisés une fois sur une page, ils sont autorisés pendant toute la session du navigateur. Pour désactiver le chargement des scripts de débogage sans mettre fin à votre session de navigateur ou supprimer manuellement les données de session, inclure le paramètre d’URL reset=true dans la demande.

Extensions de débogage en créant manuellement l’URL de débogage

Si vous travaillez avec une version de SharePoint Framework antérieure à la version 1.3.0, et que vous voulez déboguer une extension sur une page moderne, vous devez créer manuellement l’URL avec les paramètres requis. D’abord, démarrez le serveur Gulp local en définissant le répertoire de travail sur votre dossier de projet dans la ligne de commande, puis en exécutant la commande suivante :

gulp serve --nobrowser

Ensuite, dans le navigateur web, accédez à la page moderne, sur laquelle vous voulez tester l’extension. Une fois que la page est chargée, copiez son URL. Selon le type d’extension que vous souhaitez tester, il existe différents paramètres que vous devez ajouter à l’URL.

Débogage du personnalisateur d’application

Pour déboguer un personnalisateur d’application, ajoutez ce qui suit à l’URL de votre page moderne :

Attention

Des sauts de ligne et une mise en retrait ont été ajoutés à l’extrait de code suivant pour améliorer la lisibilité. Le texte suivant doit se trouver sur une seule ligne sans espace vide.

?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js
&customActions={"<extensionId>":{
    "location":"<extensionType>",
    "properties":<propertiesJSON>
}}

Par exemple :

https://contoso.sharepoint.com/sites/team-a/sitepages/news.aspx
    ?loadSPFX=true
    &debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={
        "e5625e23-5c5a-4007-a335-e6c2c3afa485":{
          "location":"ClientSideExtension.ApplicationCustomizer",
          "properties":{
            "testMessage":"Hello as property!"
          }
        }
    }

Voici les paramètres de chaîne de requête que vous devez ajouter :

Paramètre Description
loadSPFX=true permet de s’assurer que SharePoint Framework est chargé sur la page. Pour des raisons de performances, l’infrastructure ne se charge pas à moins d’avoir au moins une extension enregistrée. Comme aucun composant n’est enregistré, vous devez charger explicitement l’infrastructure.
debugManifestsFile Permet d’indiquer que vous souhaitez charger les composants qui sont distribués localement. Le chargeur recherche uniquement les composants dans le catalogue d’applications (pour votre solution déployée) et le serveur de manifeste SharePoint (pour les bibliothèques système).
customActions permet de reproduire une action personnalisée. Lorsque vous déployez et enregistrez ce composant dans un site, vous devez créer cet objet CustomAction et décrire toutes les différentes propriétés que vous pouvez définir sur ce dernier.

Le paramètre customActions possède les jetons suivants qui doivent être remplacés :

Jeton Description
<extensionId> utilisez le GUID de l’extension comme clé à associer à l’action personnalisée. Cela doit correspondre à la valeur ID de votre extension, qui est disponible dans le fichier d'extension manifest.json.
<extensionType> type d’action personnalisée. Utilisez ClientSideExtension.ApplicationCustomizer pour l’extension du personnalisateur d’application.
<propertiesJSON> Un objet JSON facultatif qui contient des propriétés disponibles via le this.properties membre.

Avec les paramètres ajoutés à l’URL, rechargez la page dans le navigateur web. La page affiche une fenêtre contextuelle qui vous invite à confirmer que vous chargez désormais les scripts de débogage.

Fenêtre contextuelle permettant de confirmer le chargement des scripts de débogage sur une page moderne dans SharePoint Online

Une fois la vérification effectuée, la page se charge avec les extensions spécifiées dans votre configuration d’utilisation.

Débogage d’un personnalisateur de champ

Pour déboguer un personnalisateur de champ, ajoutez ce qui suit à l’URL de votre page moderne :

Attention

Des sauts de ligne et une mise en retrait ont été ajoutés à l’extrait de code suivant pour améliorer la lisibilité. Le texte suivant doit se trouver sur une seule ligne sans espace vide.

?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js&fieldCustomizers={
    "<fieldName>":{
      "id":"<fieldCustomizerId>",
      "properties":<propertiesJSON>
    }
}

Par exemple :

https://contoso.sharepoint.com/sites/team-a/Lists/Orders/AllItems.aspx
  ?loadSPFX=true
  &debugManifestsFile=https://localhost:4321/temp/manifests.js
  &fieldCustomizers={
    "Percent":{
      "id":"45a1d299-990d-4917-ba62-7cb67158be16",
      "properties":{
        "sampleText":"Hello!"
      }
    }
  }

Voici les paramètres de chaîne de requête que vous devez ajouter :

Paramètre Description
loadSPFX=true permet de s’assurer que SharePoint Framework est chargé sur la page. Pour des raisons de performances, l’infrastructure ne se charge pas à moins d’avoir au moins une extension enregistrée. Comme aucun composant n’est enregistré, vous devez charger explicitement l’infrastructure.
debugManifestsFile Permet d’indiquer que vous souhaitez charger les composants qui sont distribués localement. Le chargeur recherche uniquement les composants dans le catalogue d’applications (pour votre solution déployée) et le serveur de manifeste SharePoint (pour les bibliothèques système).
fieldCustomizers Indique les champs de votre liste dont le rendu doit être contrôlé par le personnalisateur de champs. Le paramètre ID spécifie le GUID de l’extension qui doit être utilisé pour contrôler le rendu du champ. Le paramètre des propriétés est une chaîne de texte facultative contenant un objet JSON qui est désérialisé dans this.properties pour votre extension.

Le paramètre fieldCustomizers possède les jetons suivants qui doivent être remplacés :

Jeton Description
<fieldName> Nom interne du champ.
<fieldCustomizerId> GUID de l’extension du personnalisateur de champ associée à ce champ.
<propertiesJSON> Valeurs de propriétés définies dans l’extension. Dans cet exemple, sampleText est une propriété définie par l’extension.

Avec les paramètres ajoutés à l’URL, rechargez la page dans le navigateur web. La page affiche une fenêtre contextuelle qui vous invite à confirmer que vous chargez désormais les scripts de débogage.

Fenêtre contextuelle permettant de confirmer le chargement des scripts de débogage sur une page moderne dans SharePoint Online

Une fois la vérification effectuée, la page se charge avec les extensions spécifiées dans votre configuration d’utilisation.

Débogage de jeu de commandes de vue de liste

Pour déboguer un ensemble de commandes d’affichage de liste, ajoutez ce qui suit à l’URL de votre page moderne :

Attention

Des sauts de ligne et une mise en retrait ont été ajoutés à l’extrait de code suivant pour améliorer la lisibilité. Le texte suivant doit se trouver sur une seule ligne sans espace vide.

?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js
&customActions={"<extensionId>":{
  "location":"<extensionType>",
  "properties":<propertiesJSON>
}}

Par exemple :

https://contoso.sharepoint.com/sites/team-a/Lists/Orders/AllItems.aspx
  ?loadSPFX=true
  &debugManifestsFile=https://localhost:4321/temp/manifests.js
  &customActions={"a8047e2f-30d5-40fc-b880-b2890c7c16d6":{
    "location":"ClientSideExtension.ListViewCommandSet.CommandBar",
    "properties":{
      "sampleTextOne":"One item is selected in the list.",
      "sampleTextTwo":"This command is always visible."
    }
  }}

Voici les paramètres de chaîne de requête que vous devez ajouter :

Paramètre Description
loadSPFX=true permet de s’assurer que SharePoint Framework est chargé sur la page. Pour des raisons de performances, l’infrastructure ne se charge pas à moins d’avoir au moins une extension enregistrée. Comme aucun composant n’est enregistré, vous devez charger explicitement l’infrastructure.
debugManifestsFile Permet d’indiquer que vous souhaitez charger les composants qui sont distribués localement. Le chargeur recherche uniquement les composants dans le catalogue d’applications (pour votre solution déployée) et le serveur de manifeste SharePoint (pour les bibliothèques système).
customActions permet de reproduire une action personnalisée. Vous pouvez définir de nombreuses propriétés sur cet objet CustomAction qui affectent l'apparence, la convivialité et l'emplacement de votre bouton ; nous les couvrirons tous plus tard.

Le paramètre customActions possède les jetons suivants qui doivent être remplacés :

Jeton Description
<extensionId> GUID de l’extension.
<extensionType> Endroit où les commandes sont affichées. Les valeurs possibles sont les suivantes :
ClientSideExtension.ListViewCommandSet.ContextMenu : menu contextuel de l’élément/des éléments,
ClientSideExtension.ListViewCommandSet.CommandBar : le menu supérieur de jeu de commande dans une liste ou une bibliothèque.
ClientSideExtension.ListViewCommandSet : menu contextuel et barre de commandes (correspondant à SPUserCustomAction.Location="CommandUI.Ribbon").
<propertiesJSON> Un objet JSON facultatif contenant des propriétés disponibles via le this.properties membre.

Avec les paramètres ajoutés à l’URL, rechargez la page dans le navigateur web. La page affiche une fenêtre contextuelle qui vous invite à confirmer que vous chargez désormais les scripts de débogage.

Fenêtre contextuelle permettant de confirmer le chargement des scripts de débogage sur une page moderne dans SharePoint Online

Une fois la vérification effectuée, la page se charge avec les extensions spécifiées dans votre configuration d’utilisation.

Débogage de composants WebPart SharePoint Framework sur des pages SharePoint modernes

Pour tester les versions locales de vos composants WebPart côté client SharePoint Framework sur des pages SharePoint modernes dans votre client, commencez par démarrer le serveur Gulp local en définissant le répertoire de travail sur votre dossier de projet et en exécutant l’élément suivant dans la ligne de commande :

gulp serve --nobrowser

Ensuite, dans le navigateur web, accédez à la page moderne, sur laquelle vous voulez tester les composants WebPart. Après le chargement de la page, ajoutez le code suivant à l’URL :

?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js

Par exemple :

Attention

Des sauts de ligne et une mise en retrait ont été ajoutés à l’extrait de code suivant pour améliorer la lisibilité. Le texte suivant doit se trouver sur une seule ligne sans espace vide.

https://contoso.sharepoint.com/sites/team-a/sitepages/news.aspx
  ?loadSPFX=true
  &debugManifestsFile=https://localhost:4321/temp/manifests.js

La page se charge de nouveau et affiche une fenêtre contextuelle qui vous invite à confirmer que vous chargez désormais les scripts de débogage.

Fenêtre contextuelle permettant de confirmer le chargement des scripts de débogage sur une page moderne dans SharePoint Online

Une fois que vous avez confirmé le chargement des composants WebPart que vous développez, vous pouvez modifier la page, puis sélectionner un de vos composants WebPart local dans la boîte à outils.

Boîte à outils SharePoint avec un composant WebPart local mis en évidence

Avantage du test de composants WebPart SharePoint Framework sur des pages modernes

Lorsque vous créez des composants WebPart SharePoint Framework, vous pouvez les tester à l’aide du workbench local. Ce n’est pas uniquement pratique, mais également efficace : chaque fois que vous modifiez le code, le workbench local recharge automatiquement le code et affiche vos dernières modifications.

Dans certains cas, comme lors de la création de composants WebPart communiquant avec SharePoint, vous ne pouvez pas utiliser le workbench SharePoint local, car vous devez accéder aux API SharePoint pouvant être appelées uniquement dans le contexte d’un site SharePoint. Dans ce cas, au lieu d’utiliser le workbench local, vous pouvez utiliser le workbench SharePoint hébergé auquel vous pouvez accéder en ajoutant /_layouts/15/workbench.aspx à l’URL de votre site (exemple : https://contoso.sharepoint.com/sites/team-a/_layouts/15/workbench.aspx).

Contraintes liées à l’interface utilisateur

SharePoint Framework workbench imite facilement le canevas des pages SharePoint modernes. Mais il n’imite pas tous leurs aspects. La largeur du canevas est différente, toutes les couleurs de thème ne sont pas reflétées, et workbench ne vous permet pas de tester l’expérience complète où un composant WebPart s’étend sur toute la largeur du navigateur web sans marge horizontale ni remplissage.

Fonctionnement avec d’autres extensions et composants WebPart

À l’aide du workbench SharePoint, vous pouvez tester uniquement des composants WebPart à partir de votre solution. Comment voir la manière dont votre composant WebPart fonctionne avec d’autres composants WebPart sur la page ? Le test de votre solution locale sur des pages modernes à l’aide de l’approche décrite dans cet article constitue une méthode plus efficace que celle consistant à empaqueter le projet, à le déployer dans le catalogue d’applications et à ajouter le composant WebPart à la page.

Déboguer des composants WebPart de SharePoint Framework : une autre approche

Si vous créez votre solution de composant WebPart sans l'argument --ship comme suit :

gulp bundle
gulp package-solution

les packs générés feront référence au code de votre ordinateur local (https://localhost:4321). Vous pouvez déployer la solution dans le catalogue d’applications comme vous le feriez normalement.

Vous pouvez ensuite démarrer votre serveur local en exécutant :

gulp serve --nobrowser

Vous pouvez maintenant revenir à un site SharePoint dans lequel la solution a été déployée et ajouter des composants WebPart à la page, modernes ou classiques, et le code WebPart sera chargé à partir de votre environnement de développement local. Vous pouvez déboguer vos composants WebPart comme vous le feriez si vous exécutiez gulp serve et ajoutiez votre composant WebPart au plan de travail.

Cette approche ne doit être utilisée que lorsque vous êtes en mode développement. Si vous déployez une application dans le catalogue d'applications qui pointe vers votre hôte local, elle ne s'exécutera pas si votre environnement de développement n'est pas en cours d'exécution.

Voir aussi