Débogage de solutions d’infrastructure SharePoint dans Visual Studio Code

Visual Studio Code is a popular code editor frequently used for building SharePoint Framework solutions. By setting up debugging of your SharePoint Framework solution in Visual Studio Code, you can more efficiently step through your code and fix errors.

Vous pouvez également consulter les étapes requises pour activer le débogage dans Visual Studio Code en regardant cette vidéo sur la chaîne YouTube SharePoint PnP :

Conditions requises

Pour configurer facilement Visual Studio Code afin de déboguer les solutions SharePoint Framework, utilisez les extensions Visual Studio Code Débogueur pour Chrome et Débogueur pour Edge.

Les modèles de projet de composants WebPart et d’extensions SharePoint Framework par défaut incluent les prérequis et l’invite d’installation des extensions Visual Studio Code requises. Dans ce cas, vous êtes invité à installer l’extension Débogueur pour Chrome pour Visual Studio Code.

Vous avez également besoin de Google Chrome. Téléchargez et installez la dernière version de Google Chrome.

Conseil

Si vous utilisez une version du générateur Yeoman pour SharePoint Framework plus ancienne que la version 1.3.4, vous pouvez installer l’extension Débogueur pour Chrome pour Visual Studio Code disponible sur Visual Studio Marketplace.

Dans le cas où vous souhaiteriez déboguer vos projets avec Microsoft Edge, vous devez installer l'extension Débogueur pour Edge pour Visual Studio Code disponible sur Visual Studio Marketplace et suivre les étapes dans Débogage avec Microsoft Edge ou des projets plus anciens.

Configurations de débogage

Vous pouvez trouver les configurations de débogage dans le fichier ./vscode/launch.json sous le dossier de l’espace de travail Visual Studio Code. Le fichier launch.json contient deux configurations de débogage :

  • Configuration Workbench local
  • Configuration Workbench hébergé

Débogage d’une solution à l’aide de Workbench local

Quand vous générez des solutions SharePoint Framework, vous pouvez utiliser Workbench local pour vérifier le bon fonctionnement de votre composant WebPart. Workbench local vous permet de tester facilement tous les scénarios qui ne nécessitent aucune communication avec SharePoint, et d’effectuer des tâches de développement hors ligne.

En configurant le débogage des solutions SharePoint Framework dans Visual Studio Code à l’aide de Google Chrome et de Workbench local, vous pouvez vérifier que tout fonctionne comme prévu.

Important

Le service Workbench local ne prend pas en charge l’utilisation d’Internet Explorer 11. Veuillez utiliser un navigateur plus récent.

Configuration d’un point d’arrêt

  1. Dans Visual Studio Code, ouvrez le fichier source du composant WebPart principal et ajoutez un point d’arrêt sur la première ligne de la méthode render(), soit en sélectionnant la marge à gauche du numéro de ligne, soit en mettant en surbrillance la ligne de code dans l’éditeur et en sélectionnant la touche F9.

    Point d’arrêt configuré dans un composant WebPart côté client SharePoint Framework dans Visual Studio Code

  2. Dans Visual Studio Code, sélectionnez l’option Terminal intégré dans le menu Afficher ou sélectionnez les touches Ctrl+` du clavier.

  3. Dans le terminal, exécutez la commande suivante :

    gulp serve --nobrowser
    

    Running this command builds your SharePoint Framework solution and starts the local webserver to serve the output files. Because the debugger starts its own instance of the browser, you use the --nobrowser argument to prevent the serve task from opening a browser window.

    Commande gulp serve tapée dans le terminal intégré dans Visual Studio Code

Démarrage du débogage dans Visual Studio Code

Une fois la tâche Gulp terminée, déplacez le focus sur la zone de code dans Visual Studio Code et sélectionnez F5 (ou l’option Démarrer le débogage dans le menu Déboguer).

Le mode de débogage dans Visual Studio Code démarre. La couleur de la barre d’état devient orange et une nouvelle fenêtre Google Chrome s’ouvre, affichant la version locale de SharePoint Workbench.

Notes

At this point the breakpoint is disabled because the web part's code hasn't been loaded yet. SharePoint Framework loads web parts on demand only after they have been added to the page.

Visual Studio Code en mode de débogage affiché en regard de Google Chrome affichant la version locale de SharePoint Workbench

Ajout d’un composant WebPart au canevas

Pour vérifier que le débogage fonctionne, ajoutez votre composant WebPart au canevas dans Workbench.

Boîte à outils de composant WebPart dans SharePoint Workbench

Quand le code est chargé sur la page, l’indicateur de point d’arrêt devient actif.

Point d’arrêt actif une fois le composant WebPart ajouté au canevas

Si vous rechargez la page maintenant, votre point d’arrêt dans Visual Studio Code est atteint, et vous pouvez inspecter toutes les propriétés et parcourir le code.

Point d’arrêt atteint dans Visual Studio Code

Débogage d’une solution à l’aide de Workbench hébergé

Quand vous générez des solutions SharePoint Framework qui communiquent avec SharePoint, vous pouvez avoir besoin de vérifier l’interaction entre vos solutions dans SharePoint. Pour cela, vous pouvez utiliser la version hébergée de SharePoint Workbench, qui est disponible dans chaque client Microsoft 365 à une adresse de type : https://yourtenant.sharepoint.com/_layouts/workbench.aspx.

Quand vous générez des solutions SharePoint Framework, effectuez régulièrement des tests similaires. Vous pouvez également créer une configuration de débogage distincte pour la version hébergée de SharePoint Workbench.

Débogage d’une solution WebPart à l’aide de Workbench hébergé

  1. Ouvrez le fichier .vscode/launch.json et mettez à jour la propriété url sous la configuration Workbench hébergé avec votre URL de site SharePoint.

    "url": "https://enter-your-SharePoint-site/_layouts/workbench.aspx",
    
  2. Dans Visual Studio Code, activez le volet Déboguer et sélectionnez la nouvelle configuration ajoutée Workbench hébergé dans la liste Configurations.

    Configuration de Workbench hébergé sélectionnée dans la liste déroulante des configurations de débogage dans Visual Studio Code

  3. Démarrez le débogage en sélectionnant F5 ou l’option Démarrer le débogage dans le menu Déboguer. Visual Studio Code passe en mode de débogage (barre d’état orange) et l’extension Débogueur pour Chrome ouvre la page de connexion à Microsoft 365 dans une nouvelle instance de Google Chrome.

    Page de connexion à Microsoft 365 affichée dans Google Chrome après le démarrage du débogage dans Workbench hébergé

  4. Une fois connecté, ajoutez le composant WebPart au canevas et actualisez le workbench, comme vous l’avez fait avec le workbench local. Vous verrez le point d’arrêt dans Visual Studio Code être atteint, et vous pouvez inspecter les variables et parcourir le code.

    Point d’arrêt atteint dans Visual Studio Code lors du débogage d’un composant WebPart côté client SharePoint Framework dans Workbench hébergé

Débogage d’une solution d’extension à l’aide de Workbench hébergé

La procédure pour déboguer une extension dans Workbench hébergé est semblable aux étapes à suivre pour un composant WebPart, avec quelques différences importantes.

  1. Ouvrez le fichier .vscode/launch.json et mettez à jour la propriété url sous la configuration Workbench hébergé avec votre URL de site SharePoint.

    "url": "https://enter-your-SharePoint-site/_layouts/workbench.aspx",
    
  2. Dans Visual Studio Code, activez le volet Déboguer et sélectionnez la nouvelle configuration ajoutée Workbench hébergé dans la liste Configurations.

    Configuration de Workbench hébergé sélectionnée dans la liste déroulante des configurations de débogage dans Visual Studio Code

  3. Après avoir lancé le traitement du Gulp dans le terminal, démarrez le débogage en sélectionnant F5 ou l’option Démarrer le débogage dans le menu Déboguer. Visual Studio Code passe en mode de débogage (barre d’état orange) et l’extension Débogueur pour Chrome ouvre la page de connexion à Microsoft 365 dans une nouvelle instance de Google Chrome.

    Page de connexion à Microsoft 365 affichée dans Google Chrome après le démarrage du débogage dans Workbench hébergé

  4. Dans l’onglet Workbench ouvert dans votre navigateur, accédez à une page SharePoint Online où vous souhaitez tester votre extension.

  5. Ajoutez les paramètres de chaîne de requête suivants à l’URL. Notez que vous devez mettre à jour l’ID pour le faire correspondre à votre propre identificateur d’extension. Cette option est disponible dans le fichier HelloWorldApplicationCustomizer.manifest.json.

    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={"e5625e23-5c5a-4007-a335-e6c2c3afa485":{
        "location":"ClientSideExtension.ApplicationCustomizer",
        "properties":{
          "testMessage":"Hello as property!"
        }
    }}
    

    Plus de détails sur les paramètres d’URL :

    • loadSPFX=true : garantit 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 : spécifie que vous souhaitez charger les composants SPFx 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 : simule 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.
      • Clé : utilisez le GUID de l’extension comme clé à associer à l’action personnalisée. Cela doit correspondre à la valeur d’ID de votre extension qui est disponible dans le fichier manifest.json de l’extension.
      • Emplacement : type d’action personnalisée. Utilisez ClientSideExtension.ApplicationCustomizer pour l’extension du personnalisateur d’application.
      • Propriétés : objet JSON facultatif contenant les propriétés disponibles via le membre this.properties. Dans cet exemple HelloWorld, une propriété testMessage a été définie.

    L’URL complète doit ressembler à ce qui suit :

    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/Lists/Contoso/AllItems.aspx
        ?loadSPFX=true
        &debugManifestsFile=https://localhost:4321/temp/manifests.js
        &customActions={"e5625e23-5c5a-4007-a335-e6c2c3afa485":{
            "location":"ClientSideExtension.ApplicationCustomizer",
            "properties":{
              "testMessage":"Hello as property!"
            }
        }}
    
  6. Sélectionnez Charger les scripts de débogage pour continuer à charger les scripts depuis votre hôte local.

    Autoriser la question de manifeste de débogage de la page

    Lorsque la page se charge, vous devriez pouvoir voir l’extension sur votre page (dans ce cas, une extension de commande d’affichage de liste) :

    Accès aux points d’arrêt dans Visual Studio Code

    De plus, vous pouvez désormais activer/désactiver les points d’arrêt et naviguer dans le code :

    Accès aux points d’arrêt dans Visual Studio Code

Débogage avec Microsoft Edge ou des projets plus anciens

Si vous utilisez une version plus ancienne du générateur Yeoman pour SharePoint Framework ou que vous souhaitez effectuer un débogage avec Microsoft Edge, suivez ces étapes pour créer le fichier launch.json manuellement.

Notes

Pour déboguer avec Microsoft Edge, vous devrez installer la Mise à jour Windows du 10 avril 2018 qui inclut le protocole Microsoft Edge DevTools.

Création de la configuration de débogage pour Workbench local

  1. Dans Visual Studio Code, activez le volet Déboguer.

    Panneau Déboguer activé dans Visual Studio Code

  2. Dans la partie supérieure du volet, développez la liste Configurations et sélectionnez l’option Ajouter une configuration.

    Option Ajouter une configuration mise en surbrillance dans la liste déroulante des configurations de débogage

  3. Dans la liste des environnements de débogage, sélectionnez Edge ou Chrome.

    Chrome mis en surbrillance en tant qu’environnement de débogage pour la nouvelle configuration

  4. Pour Microsoft Edge, remplacez le contenu du fichier .vscode/launch.json généré par ce qui suit :

    {
      "version": "0.2.0",
      "configurations": [
        {
          "name": "Local workbench",
          "type": "msedge",
          "request": "launch",
          "url": "https://localhost:4321/temp/workbench.html",
          "webRoot": "${workspaceRoot}",
          "sourceMaps": true,
          "sourceMapPathOverrides": {
            "webpack:///.././src/*": "${webRoot}/src/*",
            "webpack:///../../../src/*": "${webRoot}/src/*",
            "webpack:///../../../../src/*": "${webRoot}/src/*",
            "webpack:///../../../../../src/*": "${webRoot}/src/*"
          }
        }
      ]
    }
    

    Cette configuration utilise le débogueur Edge fourni avec l’extension Débogueur pour Edge. Elle pointe vers l’URL de Workbench local en tant que point de départ. Pendant le débogage d’un code TypeScript, il est essentiel de configurer des mappages des sources utilisées par le débogueur pour mapper le code JavaScript exécuté dans le navigateur dans le code TypeScript d’origine.

  5. Pour Chrome, remplacez le contenu du fichier .vscode/launch.json généré par ce qui suit :

    {
      "version": "0.2.0",
      "configurations": [
        {
          "name": "Local workbench",
          "type": "chrome",
          "request": "launch",
          "url": "https://localhost:4321/temp/workbench.html",
          "webRoot": "${workspaceRoot}",
          "sourceMaps": true,
          "sourceMapPathOverrides": {
            "webpack:///.././src/*": "${webRoot}/src/*",
            "webpack:///../../../src/*": "${webRoot}/src/*",
            "webpack:///../../../../src/*": "${webRoot}/src/*",
            "webpack:///../../../../../src/*": "${webRoot}/src/*"
          },
          "runtimeArgs": [
            "--remote-debugging-port=9222"
          ]
        }
      ]
    }
    

    Cette configuration utilise le débogueur Chrome fourni avec l’extension de débogueur pour Chrome . Il pointe vers l’URL du workbench local comme point de départ. Ce qui est essentiel dans le débogage du code TypeScript, c’est la configuration des cartes sources que le débogueur utilise pour mapper le Code JavaScript en cours d’exécution dans le navigateur au code TypeScript d’origine.

Création de la configuration de débogage pour Workbench hébergé

  1. Dans Visual Studio Code, ouvrez le fichier .vscode/launch.json.

  2. Pour Edge, copiez la configuration de débogage existante et utilisez l’URL de Workbench hébergé :

    {
      "version": "0.2.0",
      "configurations": [
        {
          "name": "Local workbench",
          "type": "msedge",
          "request": "launch",
          "url": "https://localhost:4321/temp/workbench.html",
          "webRoot": "${workspaceRoot}",
          "sourceMaps": true,
          "sourceMapPathOverrides": {
            "webpack:///.././src/*": "${webRoot}/src/*",
            "webpack:///../../../src/*": "${webRoot}/src/*",
            "webpack:///../../../../src/*": "${webRoot}/src/*",
            "webpack:///../../../../../src/*": "${webRoot}/src/*"
          }
        },
        {
          "name": "Hosted workbench",
          "type": "msedge",
          "request": "launch",
          "url": "https://contoso.sharepoint.com/_layouts/workbench.aspx",
          "webRoot": "${workspaceRoot}",
          "sourceMaps": true,
          "sourceMapPathOverrides": {
            "webpack:///.././src/*": "${webRoot}/src/*",
            "webpack:///../../../src/*": "${webRoot}/src/*",
            "webpack:///../../../../src/*": "${webRoot}/src/*",
            "webpack:///../../../../../src/*": "${webRoot}/src/*"
          }
        }
      ]
    }
    
  3. Pour Chrome, copiez la configuration de débogage existante et utilisez l’URL de Workbench hébergé :

    {
      "version": "0.2.0",
      "configurations": [
        {
          "name": "Local workbench",
          "type": "chrome",
          "request": "launch",
          "url": "https://localhost:4321/temp/workbench.html",
          "webRoot": "${workspaceRoot}",
          "sourceMaps": true,
          "sourceMapPathOverrides": {
            "webpack:///.././src/*": "${webRoot}/src/*",
            "webpack:///../../../src/*": "${webRoot}/src/*",
            "webpack:///../../../../src/*": "${webRoot}/src/*",
            "webpack:///../../../../../src/*": "${webRoot}/src/*"
          },
          "runtimeArgs": [
            "--remote-debugging-port=9222"
          ]
        },
        {
          "name": "Hosted workbench",
          "type": "chrome",
          "request": "launch",
          "url": "https://contoso.sharepoint.com/_layouts/workbench.aspx",
          "webRoot": "${workspaceRoot}",
          "sourceMaps": true,
          "sourceMapPathOverrides": {
            "webpack:///.././src/*": "${webRoot}/src/*",
            "webpack:///../../../src/*": "${webRoot}/src/*",
            "webpack:///../../../../src/*": "${webRoot}/src/*",
            "webpack:///../../../../../src/*": "${webRoot}/src/*"
          },
          "runtimeArgs": [
            "--remote-debugging-port=9222"
          ]
        }
      ]
    }
    

Voir aussi