Ihre Erweiterung mit Visual Studio Code debuggen

  • 18 Minuten

Das Auffinden und Korrigieren von Fehlern wird als Debuggen bezeichnet. Mit Visual Studio Code und der AL Language-Erweiterung erhalten Sie einen integrierten Debugger, mit dem Sie Ihren Code überprüfen können, um sicherzustellen, dass Ihre Anwendung wie erwartet ausgeführt werden kann. Um eine Debugging-Sitzung zu starten, drücken Sie die Taste F5.

Beachten Sie die folgenden Beschränkungen:

  • Externer Code kann nur debuggt werden, wenn der Code die Markierung Meinen Code anzeigen gesetzt hat. Sie können die Markierung Meinen Code anzeigen in der Konfigurationsdatei App.json einstellen.

  • Der Debugger startet jedes Mal eine neue Client-Instanz, wenn Sie die Taste F5 drücken. Wenn Sie die Debugging-Sitzung schließen und dann eine neue Sitzung starten, ist die neue Sitzung auf eine neue Client-Instanz angewiesen. Wir empfehlen, dass Sie die Webclient-Instanzen schließen, wenn Sie eine Debugging-Sitzung schließen.

  • Das Anhalten der Debugging-Sitzung wird nicht unterstützt.

Haltepunkte

Das Grundkonzept beim Debuggen ist der Haltepunkt. Dies ist eine Markierung, die Sie für eine Anweisung setzen. Wenn der Programmablauf den Haltepunkt erreicht, wird der Debugger nicht mehr ausgeführt, bis Sie ihn anweisen, fortzufahren. Ohne Haltepunkte wird der Code ohne Unterbrechung ausgeführt, wenn der Debugger aktiv ist. Sie können einen Haltepunkt festlegen, indem Sie das Menü Debuggen in Visual Studio Code verwenden, oder Sie können F9 in der Zeile drücken, die Sie debuggen möchten.

Sie können den Basisanwendungscode mithilfe der Funktion Zur Definition wechseln aufrufen und Haltepunkte für den referenzierten Code festlegen, bei dem es sich im Allgemeinen um eine (.dal)-Datei handelt. Führen Sie die folgenden Schritte aus, um einen Haltepunkt für den externen Code oder den Basisanwendungscode festzulegen.

  1. Erstellen Sie eine Variable eines Basisobjekts, oder wählen Sie „Quelltabelle“ auf einer Seite aus.

  2. Klicken Sie mit der rechten Maustaste auf die Variable, und wählen Sie Zur Definition wechseln aus, oder Sie können F12 drücken. Eine externe Datei (.dal-Datei) wird geöffnet.

  3. Wählen Sie die Zeile aus, in der Sie einen Haltepunkt setzen möchten, und drücken Sie dann F9.

Debuggen von Verknüpfungen

Während des Debuggens können Sie einige Verknüpfungen verwenden, um das Debuggen zu starten oder zu stoppen oder in den Code zu springen bzw. den Code zu überspringen.

  • F5 – Debuggen starten

  • STRG+F5 – Ohne Debuggen starten

  • UMSCHALT+F5 – Debuggen stoppen

  • STRG+UMSCHALT+F5 - Debuggen ohne Veröffentlichung starten Der Debugger debuggt die zuletzt veröffentlichte Version, nicht die Version, die in Ihrer Visual Studio Code-Umgebung aktiv ist.

  • ALT+F5 – Schnelle Anwendungsentwicklung mit Debuggen starten

  • F10 – Schritt bis zur ersten Anweisung außerhalb der Funktion

  • F11 – Schritt bis zur ersten Anweisung innerhalb der Funktion

  • UMSCHALT+F11 – Schritt bis zur nächsten Anweisung in der aufrufenden Funktion

  • F12 – Zur Definition wechseln

Unterbrechen bei Fehlern

In der Konfigurationsdatei launch.json können Sie angeben, ob der Debugger beim nächsten Fehler unterbrochen werden soll, indem Sie die Eigenschaft breakOnError verwenden. Wenn der Debugger auf breakOnError eingestellt ist, wird die Ausführung von Fehlern, die im Code behandelt bzw. im Code nicht behandelt werden, gestoppt.

Der Standardwert der Eigenschaft breakOnError ist true. Dies bedeutet, dass der Debugger eine Implementierung stoppt, die standardmäßig einen Fehler auslöst. Um den Fehlerbehandlungsprozess zu überspringen, stellen Sie die Eigenschaft breakOnError in der Datei launch.json auf false ein.

Die Einstellung breakOnError in der launch.json-Datei nimmt einen der folgenden Werte an:

  • true – Unterbricht bei allen Fehlern.

  • false – Unterbricht nicht bei Fehlern.

  • Keine – Unterbricht nicht bei Fehlern.

  • Alle – Unterbricht bei allen Fehlern.

  • ExcludeTry – Unterbricht bei Fehlern nur dann, wenn sie außerhalb des Kontexts einer Try-Funktion auftreten.

Die Werte true und false werden zur Zeit aus Gründen der Abwärtskompatibilität beibehalten. Sie werden Alle und Keine zugeordnet. Wir empfehlen, zukünftig letzteres zu verwenden. true und false können in einer zukünftigen Version obsolet sein.

Bei Datensatzänderungen unterbrechen

In der Konfigurationsdatei launch.json können Sie angeben, ob der Debugger beim nächsten Fehler im Datensatz unterbrochen werden soll, indem Sie die Eigenschaft breakOnRecordWrite verwenden. Wenn der Debugger so eingestellt ist, dass er bei Datensatzänderungen unterbrochen wird, wird er vor dem Erstellen, Ändern oder Löschen eines Datensatzes unterbrochen.

Der Standardwert der Eigenschaft breakOnRecordWrite ist false. Dies bedeutet, dass der Debugger standardmäßig nicht so eingestellt ist, dass er bei Datensatzänderungen unterbrochen wird. Um Datensatzänderungen zu unterbrechen, stellen Sie die Eigenschaft breakOnRecordWrite in der Datei launch.json auf true ein.

Die Einstellung breakOnRecordWrite in der launch.json-Datei nimmt einen der folgenden Werte an:

  • true – Unterbricht bei allen Datensatz-Schreibvorgängen.

  • false – Unterbricht nicht bei Datensatz-Schreibvorgängen.

  • Keine – Unterbricht nicht bei Datensatz-Schreibvorgängen.

  • Alle – Unterbricht bei allen Datensatz-Schreibvorgängen.

  • ExcludeTemporary – Unterbricht Datensatz-Schreibvorgänge nur, wenn sie nicht in einer temporären Tabelle vorgenommen werden.

Die Werte true und false werden zur Zeit aus Gründen der Abwärtskompatibilität beibehalten. Sie werden Alle und Keine zugeordnet. Wir empfehlen, zukünftig letzteres zu verwenden. true und false können in einer zukünftigen Version obsolet sein.

Einstellungen zur Richtlinie zur Ressourcenoffenlegung

Wenn Sie eine Erweiterung entwickeln, ist Ihr Code standardmäßig vor dem Herunterladen oder Debuggen geschützt. Erfahren Sie hier mehr über das Hinzufügen von Schutz durch geistiges Eigentum (IP) gegen das Herunterladen oder Debuggen in einer Erweiterung, um den Quellcode in den Erweiterungen anzuzeigen.

Das Erweiterungsentwicklungspaket bietet eine vorkonfigurierte Einstellung zum Schutz vor Anzeigen oder Herunterladen des Codes der Erweiterungen. Diese Einstellung kann jedoch auch im Manifest gesteuert werden; in der app.json-Datei.

Wenn Sie ein neues Projekt starten, wird automatisch eine app.json-Datei generiert, die die Informationen zu der Erweiterung enthält, auf der Sie aufbauen. In der Datei app.json können Sie eine Einstellung namens resourceExposurePolicy angeben, die die Zugänglichkeit der Ressourcen und des Quellcodes während verschiedener Operationen definiert.

Die Einstellung resourceExposurePolicy gibt die folgende Liste von Optionen an:

  • allowDebugging

  • allowDownloadingSource

  • includeSourceInSymbolFile

Jede dieser Eigenschaften legt die spezifischen Bereiche fest, in denen auf den Quellcode einer Erweiterung zugegriffen werden kann. Alle Optionen sind standardmäßig auf „false“ gesetzt. Dies bedeutet, dass standardmäßig keine abhängige Erweiterung den Quellcode Ihrer Erweiterung debuggen oder herunterladen kann.

Hier ist ein Beispiel für eine JSON-Datei mit Standardwerten, generiert unter Verwendung von AL: Go! Befehl:

... "resourceExposurePolicy": { "allowDebugging": true, "allowDownloadingSource": false, "includeSourceInSymbolFile": false }, "runtime": "8.0", "keyVaultUrls": [ "https://mykeyvault.vault.azure.net" ], "applicationInsightsConnectionString": "MyConnectionString1234" ...

Die Einstellung resourceExposurePolicy ist in der Datei app.json nicht sichtbar, wenn sie generiert wird. Fügen Sie die Einstellung wie im obigen Syntaxbeispiel gezeigt hinzu, um den Standardwert von false zu ändern.

allowDebugging

Richten Sie das Kennzeichen allowDebugging ein, um das Debuggen in Ihrer Erweiterung zuzulassen, wenn die Erweiterung als Abhängigkeit verwendet wird. Andernfalls ist das Debuggen nicht erlaubt. Wenn Sie Debuggern in Ihrer Erweiterung erlauben möchten, den Quellcode anzuzeigen, muss die Eigenschaft allowDebugging in der Datei app.json auf true festgelegt werden.

Wenn zum Beispiel ein Entwickler Erweiterung A entwickelt und er oder jemand anderes im Team Erweiterung B entwickelt und B von A abhängt, wird das Debuggen von B nur dann in den Code für A eintreten, wenn eine Methode von A aufgerufen wird und wenn das Kennzeichen allowDebugging in der App.json-Datei für die Erweiterung A auf true eingestellt ist.

Das Einrichten der Eigenschaft allowDebugging auf true erlaubt es, in diesen Code einzusteigen, es sei denn, Sie haben das Attribut [NonDebuggable] für Methoden und Variablen angegeben. Wenn Sie jedoch die mit [NonDebuggable] gekennzeichneten Methoden und Variablen markiert haben, bleiben diese nicht debug-fähig.

Der Standardwert des Kennzeichens allowDebugging ist false. Es wird empfohlen, dieses Kennzeichen nur auf „true“ zu setzen, wenn Sie demjenigen vertrauen, der Ihre Erweiterung erweitert. Wenn allowDebugging auf true gesetzt ist, kann jeder, der Ihren Code erweitert, darauf zugreifen, um ihn zu debuggen. Sie können die Ressourcenrichtlinie überschreiben, wenn Sie nur einigen Personen Zugriff auf Ihren Code gewähren möchten.

Es gibt einige Fälle, in denen Code debuggt werden kann, obwohl das Kennzeichen allowDebugging auf false gesetzt ist. Diese sind:

  • Jemand kann Ihren Code weiterhin anzeigen, wenn eine Erweiterung über Visual Studio Code als DEV-Erweiterung bereitgestellt wird, im Gegensatz zur Bereitstellung mithilfe eines Cmdlets, mithilfe der Seite Erweiterungsverwaltung in Business Central oder mithilfe von AppSource.

  • Benutzerdefinierte externe Tools für AL erhalten möglicherweise Zugriff auf die DAL-Informationen, die vom Debugger verfügbar gemacht werden, indem sie Debugger-Ereignisse abhören, die von Visual Studio Code ausgelöst werden.

allowDownloadingSource

Wenn diese Einstellung in der Datei „app.json“ der Erweiterung A auf „true“ eingestellt ist, können der Quellcode und alle Mediendateien der Erweiterung A heruntergeladen werden. Zum Beispiel von der Option Download-Quelle in der Seite Erweiterungsverwaltung in Business Central. Erweiterung A kann eine PTE‑ oder eine DEV-Erweiterung sein. Der Standardwert von allowDownloadingSource ist false.

includeSourceInSymbolFile

Wenn dies in der Datei app.json der Erweiterung A auf „true“ gesetzt ist, enthält die heruntergeladene Symboldatei in Visual Studio Code, auf den über die Funktion Symbole herunterladen zugegriffen wird, Symbole, Quellcode und alle anderen Ressourcen der Erweiterung A. Wechseln Sie zur Definition, um den Code anzuzeigen, hängt auch von dieser Eigenschaft ab. Der Standardwert des Kennzeichens includesourceInSymbolFile ist false.

AL-Compiler-Diagnosemeldungen

Wenn Sie Codeanalysatoren kompilieren oder ausführen, können Diagnosemeldungen in Form von Fehler‑, Warnungs‑ oder Informationsmeldungen angezeigt werden. Diese enthalten jetzt eine URL für zusätzliche Dokumentation zur Ursache des Problems und Optionen zur Lösung des Problems, um solche Diagnoseprobleme zu lösen.

Verknüpfungen in Diagnosemeldungen von Kompilierungs‑ oder Codeanalysatoren unterstützen die Verknüpfung mit zusätzlicher, relevanter Dokumentation zur Ursache des Problems sowie Optionen zur Problemlösung.

Es gibt Dokumentationsseiten für alle Diagnoseprobleme und URL-Links von der Compilerausgabediagnose. Dennoch ist die Dokumentation anfänglich oberflächlich und enthält hauptsächlich die Botschaft. Wir bitten Partner, mit Feedback zu helfen, zu welchen Themen mehr Dokumentation priorisiert werden sollte, und auch Feedback dazu zu geben, welche Inhalte zur Lösung von Problemen nützlich wären. Auf dieser Grundlage wird die Dokumentation hoffentlich im Laufe der Zeit wachsen, und das Wissen zwischen den Partnern wird durch diese Tipps und Tricks zu Ursachen und Behebungen geteilt, wodurch sich der Zeitaufwand für jede Diagnose verringert.

Sie können den aktuellen Artikel AL-Compiler-Diagnose für Beispiele und Referenzen anzeigen.

Einführung in ein bestimmtes Unternehmen über Visual Studio Code

Sie können in einem Business Central-Mandanten über mehrere Unternehmen verfügen. Wenn Sie Ihre App debuggen oder testen, möchten Sie dies oft im Kontext eines bestimmten Unternehmens vornehmen. In früheren Versionen von Business Central konnten Sie nicht festlegen, welches Unternehmen verwendet werden soll, wenn Sie den Client über Visual Studio Code starten. In der Regel müssten Sie zuerst das Standardunternehmen im Client einrichten.

Ein neues Parameter startupCompany wurde der Konfigurationsdatei launch.json von Visual Studio Code hinzugefügt. Verwenden Sie dieses, um das Unternehmen anzugeben, das genutzt werden soll, wenn der Client aus Visual Studio Code gestartet wird, z. B. beim Ausführen oder Debuggen.

SQL Server-Informationen während des AL-Debuggens anzeigen

Es kann schwierig sein, Datenbanksperren beim Entwickeln und Beheben von Fehlern in Cloud-Sandboxen ohne direkten SQL-Zugriff zu verstehen. Es kann schwierig sein, beim Aufrufen von beispielsweise den Methoden rec.Modify() oder rec.FindSet() zu identifizieren, welche Sperren von AL verwendet sind. Während SQL-Sperren jetzt im Webclient angezeigt werden, ist die Verwendung zum Debuggen umständlich, da Sie einen anderen Browser mit einer anderen Sitzung benötigen.

Der Abschnitt Datenbankstatistik wurde im Variablenfenster für die Visual Studio Code-AL-Debugerfahrung erweitert, um SQL-Sperren für die debuggte Sitzung anzuzeigen und dies so zu unterstützen.

Sie können neben den zuletzt ausgeführten SQL-Anweisungen und Datenbankstatistiken auch Informationen über aktive SQL-Sperren abrufen, die während der zu debuggenden Sitzung auftreten. Die Liste wird beim schrittweisen Durchgehen des AL-Codes aktualisiert. Commits entfernen die gehaltenen Sperren.

Die Systemanwendung debuggen

Mit der kürzlichen Einführung des Datentyps SecureText ermöglichen wir das Debuggen der Systemanwendung, was sowohl der Entwicklung und Fehlerbehebung von Anwendungen als auch Open-Source-Beiträgen zur Systemanwendung selbst hilft.

Damit können Sie beim Debuggen in die Codebasis der Systemanwendung gehen, um den Codefluss zu verstehen und Variablen zu überprüfen, sofern diese nicht durch den neuen SecureText-Typ geschützt sind.

Der Zugriff zum Debuggen der Systemanwendung hilft sowohl bei der Entwicklung und Fehlerbehebung von AppSource‑ und kundenspezifischen Anwendungen als auch bei der Mitwirkung an der Systemanwendung selbst mit https://github.com/microsoft/BCApps.