Debuggen von SharePoint-Framework-Lösungen in Visual Studio Code

Visual Studio Code ist eine beliebter Code-Editor, der häufig zur Erstellung von SharePoint Framework-Lösungen verwendet wird. Wenn Sie Ihre SharePoint Framework-Lösung in Visual Studio Code debuggen, können Sie Ihren Code effizienter durcharbeiten und Fehler beheben.

In einem Video in unserem YouTube-Kanal „Microsoft 365 Platform Communtiy Patterns & Practices (PnP)“ werden auch die erforderlichen Schritte zum Aktivieren von Debugging in Visual Studio Code erläutert:

Voraussetzungen

Die einfachste Möglichkeit zum Konfigurieren von Visual Studio Code (VS Code) zum Debuggen SharePoint-Framework Projektmappen ist die Verwendung des in VS Code enthaltenen JavaScript-Debuggers zum Debuggen von Chrome & Edge.

Sie benötigen auch Google Chrome oder Microsoft Edge.

Debugkonfigurationen

Die Debugkonfigurationen sind in der Datei ./vscode/launch.json im folgenden Visual Studio Code-Arbeitsbereichsordner enthalten.

Konfigurieren eines Haltepunkts

1. Öffnen Sie in Visual Studio Code die Quelldatei des Hauptwebparts, und fügen Sie in der ersten Zeile der Methode render() einen Haltepunkt hinzu. Klicken Sie dazu entweder links neben die Zeilennummer, oder markieren Sie die Codezeile im Editor, und drücken Sie die Taste F9.

   

2. Wählen Sie in Visual Studio Code im Menü Anzeigen die Option Integriertes Terminal aus, oder drücken Sie STRG+` auf der Tastatur.

3. Führen Sie im Terminal den folgenden Befehl aus:

   gulp serve --nobrowser
   

   Wenn Sie diesen Befehl ausführen, wird Ihre SharePoint-Framework Projektmappe erstellt und der lokale Webserver gestartet, um die Ausgabedateien bereitzustellen. Da der Debugger eine eigene Instanz des Browsers startet, verwenden Sie das Argument --nobrowser , um zu verhindern, dass die Serve-Aufgabe ein Browserfenster öffnet.

   

Starten des Debuggens in Visual Studio Code

Wechseln Sie nach Abschluss des gulp-Tasks in den Codebereich von Visual Studio Code, und drücken Sie F5. (Alternativ können Sie aus dem Menü Debuggen die Option Debugging starten auswählen.)

Der Debugmodus in Visual Studio Code wird gestartet, ändert die Farbe der Statusleiste in Orange und öffnet ein neues Fenster von Google Chrome, in dem die SharePoint-Workbench angezeigt wird.

Hinweis

An diesem Punkt ist der Haltepunkt deaktiviert, da der Code des Webparts noch nicht geladen wurde. SharePoint Framework kann Webparts erst bei Bedarf laden, wenn sie der Seite hinzugefügt wurden.

Hinzufügen eines Webparts zum Zeichenbereich

Um zu überprüfen, ob das Debuggen funktioniert, fügen Sie Ihr Webpart in der Workbench nun dem Zeichenbereich hinzu.

Sie sehen: Jetzt da der Code auf der Seite geladen wurde, ist der Haltepunktindikator aktiviert.

Wenn Sie die Seite nun neu laden, greift der Haltepunkt in Visual Studio Code, und Sie können alle Eigenschaften prüfen und den Code Schritt für Schritt durcharbeiten.

Debuggen der Lösung mithilfe der gehosteten Workbench

Wenn Sie SharePoint-Framework-Lösungen erstellen, die mit SharePoint kommunizieren, möchten Sie möglicherweise überprüfen, ob die Interaktion zwischen Ihrer Lösung und SharePoint funktioniert. Das geht ganz einfach mit der gehosteten Version der SharePoint-Workbench. Sie ist auf jedem Microsoft 365-Mandanten verfügbar, unter der Adresse https://yourtenant.sharepoint.com/_layouts/workbench.aspx.

Da solche Tests während der Erstellung von SharePoint-Framework-Lösungen regelmäßig durchgeführt werden, ist es empfehlenswert, eine separate Debugkonfiguration für die gehostete Version der SharePoint-Workbench zu erstellen.

Debuggen der Webpartlösung mithilfe der gehosteten Workbench

1. Öffnen Sie die Datei .vscode/launch.json, und ersetzen Sie die url-Eigenschaft in der Konfiguration für die gehostete Workbench durch die URL Ihrer SharePoint-Website.

   "url": "https://enter-your-SharePoint-site/_layouts/workbench.aspx",
   

2. Öffnen Sie in Visual Studio Code den Bereich Debuggen, und wählen Sie aus der Liste Konfigurationen die gerade erstellte Konfiguration für die gehostete Workbench aus.

   

3. Starten Sie das Debuggen. Drücken Sie dazu entweder die Taste F5, oder wählen Sie aus dem Menü Debuggen die Option Debugging starten aus. Visual Studio Code wechselt in den Debugmodus, und die Statusleiste wird orange. Außerdem öffnet die Erweiterung „Debugger for Chrome“ eine neue Instanz von Google Chrome mit der Microsoft 365-Anmeldeseite.

   

4. Nachdem Sie sich angemeldet haben, fügen Sie das Webpart zum Zeichenbereich hinzu, und aktualisieren Sie die Workbench. Sie werden sehen, wie der Haltepunkt in Visual Studio Code gegriffen wird. Außerdem können Sie Variablen überprüfen und den Code durchlaufen.

   

Debuggen der Erweiterungslösung mithilfe der gehosteten Workbench

Das Debuggen einer Erweiterung in einer gehosteten Workbench läuft ähnlich wie das Debuggen eines Webparts ab. Es gibt nur einige wichtige Unterschiede.

1. Öffnen Sie die Datei .vscode/launch.json, und ersetzen Sie die url-Eigenschaft in der Konfiguration für die gehostete Workbench durch die URL Ihrer SharePoint-Website.

   "url": "https://enter-your-SharePoint-site/_layouts/workbench.aspx",
   

2. Öffnen Sie in Visual Studio Code den Bereich Debuggen, und wählen Sie aus der Liste Konfigurationen die gerade erstellte Konfiguration für die gehostete Workbench aus.

   

3. Starten Sie nach dem Initiieren von "gulp serve" das Debuggen. Drücken Sie dazu entweder die Taste F5, oder wählen Sie aus dem Menü Debuggen die Option Debugging starten aus. Visual Studio Code wechselt in den Debugmodus, und die Statusleiste wird orange. Außerdem öffnet die Erweiterung „Debugger for Chrome“ eine neue Instanz von Google Chrome mit der Microsoft 365-Anmeldeseite.

   

4. Navigieren Sie auf der Workbench-Registerkarte, die in Ihrem Browser geöffnet wurde, zu einer SharePoint Online-Seite, für die Sie Ihre Erweiterung testen möchten.

5. Hängen Sie die folgenden Abfragezeichenfolgenparameter an die URL an. Beachten Sie, dass Sie die ID entsprechend Ihrem eigenen Erweiterungsbezeichner aktualisieren müssen. Dieser ist in der Datei HelloWorldApplicationCustomizer.manifest.json verfügbar.

   Vorsicht

   Der Einzug von Zeilenumbrüchen & wurde dem folgenden Codeausschnitt zur Lesbarkeit hinzugefügt. Der folgende Text sollte in einer einzigen Zeile ohne Leerzeichen angegeben werden.

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

   Weitere Details zu den URL-Parametern:

   • loadSPFX=true: Stellt sicher, dass das SharePoint-Framework auf der Seite geladen wird. Aus Leistungsgründen wird das Framework erst geladen, wenn mindestens eine Erweiterung registriert wurde. Da keine Komponenten registriert sind, müssen Sie das Framework explizit laden.
   • debugManifestsFile: Gibt an, dass lokal verarbeitete SPFx-Komponenten geladen werden sollen. Das Ladeprogramm sucht nur an zwei Stellen nach Komponenten: im App-Katalog (nach Komponenten der bereitgestellten Lösung) und auf dem SharePoint-Manifestserver (nach den Systembibliotheken).
   • customActions: Simuliert eine benutzerdefinierte Aktion. Wenn Sie diese Komponente auf einer Website bereitstellen und registrieren, erstellen Sie dieses CustomAction-Objekt und beschreiben die verschiedenen Eigenschaften, die Sie dafür festlegen können.
     • Key: Verwenden Sie die GUID der Erweiterung als Schlüssel, der der benutzerdefinierten Aktion zuzuordnen ist. Dieser muss dem ID-Wert der Erweiterung entsprechen, der in der JSON-Manifestdatei der Erweiterung zur Verfügung steht.
     • Location: Der Typ der benutzerdefinierten Aktion. Verwenden Sie ClientSideExtension.ApplicationCustomizer für die Application Customizer-Erweiterung.
     • Properties: Ein optionales JSON-Objekt mit Eigenschaften, die über den Member this.properties verfügbar sind. In diesem HelloWorld-Beispiel definiert es eine testMessage-Eigenschaft.

   Die vollständige URL sollte ähnlich wie im folgenden Beispiel aussehen:

   Vorsicht

   Der Einzug von Zeilenumbrüchen & wurde dem folgenden Codeausschnitt zur Lesbarkeit hinzugefügt. Der folgende Text sollte in einer einzigen Zeile ohne Leerzeichen angegeben werden.

   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. Wählen Sie Load debug scripts aus, um weiter Skripts von Ihrem lokalen Host zu laden.

   

   Wenn die Seite geladen wird, sollten Sie nun die Erweiterung auf Ihrer Seite sehen können (in diesem Fall eine Befehlserweiterung für die Listenansicht):

   

   Darüber hinaus können Sie jetzt Haltepunkte umschalten und den Code schrittweise durchlaufen:

   

Debuggen mit Microsoft Edge oder älteren Projekten

Wenn Sie eine ältere Version des SharePoint-Framework-Yeoman-Generators verwenden oder ein Debugging mit Microsoft Edge durchführen möchten, führen Sie die folgenden Schritte aus, um die Datei „launch.json“ manuell zu erstellen.

Hinweis

Damit Sie mit Microsoft Edge debuggen können, müssen Sie das Windows 10 April 2018 Update installieren, welches das Microsoft Edge DevTools-Protokoll enthält.

Erstellen einer Debugkonfiguration für die gehostete Workbench

1. Öffnen Sie in Visual Studio Code die Datei .vscode/launch.json.

2. Kopieren Sie bei Edge die vorhandene Debugkonfiguration, und verwenden Sie die URL der gehosteten Workbench:

   {
     "version": "0.2.0",
     "configurations": [
       {
         "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. Kopieren Sie in Chrome die vorhandene Debugkonfiguration, und verwenden Sie die URL der gehosteten Workbench:

   {
     "version": "0.2.0",
     "configurations": [
       {
         "name": "Hosted workbench",
         "type": "pwa-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",
           "-incognito"
         ]
       }
     ]
   }
   

Siehe auch

• How to debug your SharePoint Framework web part (Elio Struyf)
• Debug SPFx React webpart with Visual Studio Code (Velin Georgiev)
• Yeoman-Generator für SharePoint-Framework
• Übersicht über das SharePoint-Framework