Visual Studio Code

Visual Studio Code ist ein Open Source Code-Editor von Microsoft. Über ein von ClassiX bereitgestelltes Plugin wird auch InstantView unterstützt.

Der erste angebotene Download ist nur ein User-Setup (es wird nur für den einen User ins User-Verzeichnis installiert). Möchte man für alle Benutzer installieren oder unter Programme installieren, muss man sich den System-Installer herunterladen. Dieser befindet sich etwas weiter unten auf der Seite oder wenn man auf der Seite oben rechts auf Download klickt.

Installation

Zur Ausführung des Plugins wird Java mindestens in der Version 1.8 benötigt. Installieren Sie daher Java bitte zuerst. Die aktuellste Version kann unter https://openjdk.java.net/ gefunden werden.

Das Plugin kann einfach über den Visual Studio Code Marketplace installiert werden. Dafür gehen Sie in InstantView auf die Extensions und suchen nach InstantView. Dann sollten Sie das Plugin direkt installieren und finden können.

Einrichtung eines InstantView-Projekts

Ein InstantView-Projekt ist ein Basisordner, in dem dann die vom CyberEnterprise zur Laufzeit benötigten Dateien liegen. Normalerweise liegen in diesem Basisordner die Ordner appswh mit den Modulen des AppsWarehouse,  projects mit der Startdatei und system mit allen Dateien zur Konfiguration des Systems. In Visual Studio Code wird mit dem Projekt als Ganzes gearbeitet.

Projekt öffnen

Um ein Projekt bearbeiten zu können, sind folgende Schritte notwendig:

1. Der Ordner wird in Visual Studio Code geöffnet. Gehen Sie dazu auf File → Open Folder... und wählen anschließend den entsprechenden Basisordner aus.
2. Den Aufbau eines Projekts erfährt das Plugin über IPC-Dateien. IPC-Dateien sind einfache Textdateien, die genau angeben, wo das Plugin nach Dateien suchen muss. Der Pfad zur IPC-Datei wird in den Einstellungen gespeichert. Diese kann man per Strg + , öffnen. Unter Extensions > Instantview > Project: Ipc File befindet sich die entsprechende Einstellung. Hier wird die IPC-Datei relativ zum Basisordner oder als absoluter Pfad angegeben.
3. Damit Änderungen an der .ipc-Datei übernommen werden, muss VSCode einmal neu gestartet werden.

IPC-Datei setzen/wechseln

Ab Version 2.21.0 des Plugins gibt es eine komfortablere Variante, die .ipc-Datei zu setzen/wechseln. Hierzu öffnet man das Befehlsfenster per STRG+SHIFT+P und gibt "ipc" sein, um nach dem Befehl "InstantView: Select IPC file" zu suchen. (Nach dem ersten Aufruf, sollte der Befehl immer ganz oben in der Liste stehen und eine Suche nicht mehr notwendig sein)

Führt man diesen Befehl nun mit ENTER aus, dann wird eine Liste mit allen im aktuellen Workspace gefundenen .ipc-Dateien ausgegeben und die aktuell konfigurierte .ipc-Datei wird hevorgehoben.

Sobald die Auswahl bestätigt wird, wird der entsprechende Eintrag in der Konfguration aktualisiert und der VSCode-Editor startet sich automatisch neu, damit der Parser mit der neuen .ipc-Datei arbeitet.

Dieser Befehl funktioniert auch für Workspaces mit mehreren Projekten korrekt.

Wichtig: Der Befehl funktioniert nur dann, wenn die aktuell geöffnete Datei eine Datei aus dem Workspace ist. Wird der Befehl beispielsweise aus den Einstellungen heraus ausgeführt, dann ist bei mehreren Projekten unklar, welches gemeint ist.

Dieser Befehl lässt sich auch mit einem frei wählbaren Tastenkürzel verbinden.

Mehrere Projekte öffnen

Es ist in Visual Studio Code auch möglich, mehrere Projekte auf einmal zu öffnen. Die IPC-Datei kann dann für jedes Projekt einzeln konfiguriert werden. Das Vorgehen dafür ist folgendes:

1. Wählen Sie im Menü File → Open Folder... und öffnen den Basisordner des ersten Projekts.
2. Alle weiteren Projekte öffnen Sie , indem Sie im Menü auf File → Add Folder to Workspace... klicken und jeweils den Basisordner auswählen.
3. Die IPC-Datei wird je Projekt festgelegt. Klicken Sie dafür jeweils auf den Basisordner im Explorer mit der rechten Maustaste und wählen Open Folder Settings. Hier geben Sie im Suchfeld ipc ein und suchen dann nach dem Eintrag Instantview > Project: Ipc File. Geben Sie die IPC-Datei relativ zum jeweiligen Basisordner oder mit absolutem Pfad ein.

Die Einstellungen eines Workspace, also der Zusammenstellung mehrerer Projekte lässt sich in einer Datei speichern und immer wieder öffnen. Dafür klicken Sie im Menü auf File → Save Workspace As... und wählen einen Dateinamen aus. Später kann der Workspace dann wieder im Menü über File → Open Workspace... geöffnet werden.

Extension für Perforce

Extention -> "Perforce for VS Code" suchen. Es werden mehrere Treffer gefunden. Unter anderem auch zwei Mal „Perforce for VS Code“. In diesem Beispiel der dritte Treffer „Symbol ‚P4k‘ auf blauem Hintergrund“ ist die Extension für Perforce, die wir haben wollen. (Es ist der Nachfolger vom ersten Treffer.)

Nach der Installation der Extension mit Strg +, die Settings aufrufen, auf Workspace klicken, „Extension“ aufklappen, nach unten scrollen und auf „VS Code Perforce …“ klicken. Alternativ kann, nach dem man Workspace ausgewählt hat, auch nach „VS Code Perforce Configuration“ gesucht werden.

Folgende Checkboxen sind zu aktivieren:

• Add On File Create
• Edit On File Modified
• Edit On File Save
• Hide Submit Icon

Tipps und Features

Im Folgenden werden einige Tipps gegeben und Features gezeigt, die das InstantView-Plugin unterstützt.

Vorher sollte aber noch der Begriff Symbol definiert werden: Als Symbole werden alle Definitionen wie Module, Variablen, Prozeduren, Fenster oder Widgets bezeichnet. Sie beinhalten also im Gegensatz zu reinen Textstellen schon die Semantik von InstantView. Die Symbole einer Datei werden durch Parsen im Hintergrund bestimmt. Die aktuelle Datei wird während Änderungen ständig im Hintergrund neu geparsed, so dass auch alle Symbole in der Datei ständig aktualisiert werden. Die meisten der folgenden Features basieren auf den Symbolen einer Datei. Bitte beachten Sie auch die Hinweise zu Symbolen.

Dateien öffnen

Um Dateien in einem Projekt zu öffnen, können Sie Strg + P drücken. Es öffnet sich dann ein Menü, in das Sie einen Teil des Dateinamen eingeben können. Während des Tippens werden die möglichen Dateinamen gefiltert. Wie im Bild zu sehen ist, müssen die Teile des Dateinamens auch nicht zusammenhängend sein. Nach Auswählen eines Eintrages und Druck auf Enter wird die entsprechende Datei geöffnet.

Anzeige von Problemen

Während des Parsens wird der Quelltext analysiert und Warnungen oder Fehler können angezeigt werden. Zum Öffnen der Übersicht über alle Warnungen und Fehler drücken Sie Strg + Shift + M.

Darüber hinaus werden die Warnungen und Fehler auch durch Unterkringeln um Quelltext angezeigt und weitere Informationen können Sie durch Draufzeigen mit der Maus erhalten:

Navigation zu Symbol

Mit der Tastenkombination Strg + Shift + O kann statt zu einer anderen Datei zu einem anderen Symbol in der aktuellen Datei gesprungen werden. Auch hier können die Ergebnisse durch Eingeben eines Teils des Namens gefiltert werden.

Wenn die Taste Strg gedrückt wird und mit der Maus auf ein Symbol im Editor gezeigt wird, erscheint ein Link wenn zu dem Symbol navigiert werden kann. Durch Klick auf den Link kann dann zur Definition des Symbols gesprungen werden.

Falls der Cursor auf einem Symbol steht, dann kann per F12 zu der Definition gesprungen werden.

Anzeigen von Definition

Statt komplett zu einer Definition zu springen und dabei vielleicht noch die aktuelle Stelle in der Datei zu verlieren, kann die Definition des Symbols unter dem Cursor über die Tastenkombination Alt + F12 in den aktuellen Editor eingeblendet werden.

Hilfe

Wenn auf einen Befehl, ein Widget oder eine Message mit der Maus gezeigt wird, so erscheint ein Popup mit einer Hilfe zum entsprechenden Symbol. Wo möglich befindet sich in der kurzen Hilfe auch ein Link zur ausführlichen Dokumentation, die dann im Browser geöffnet wird.

Faltung von Quelltext

Auf der linken Seite des Editors erscheinen an bestimmten Stellen Pfeile mit denen Teile des Quelltextes eingeklappt werden können, um so mehr Übersicht zu erhalten.

Die Hilfe funktioniert auch für Prozeduren, auch aus Providern, und zeigt dann den entsprechenden Kommentar an. Ebenso funktioniert sie bei entsprechenden Kommentaren an Modulen oder Messages.

Autovervollständigung

Beim Tippen werden automatisch Vorschläge zur Vervollständigung des aktuellen Begriffs gemacht. Diese können durch Klicken auf Enter übernommen werden. Sollte die Liste sich mal geschlossen haben, lässt sie sich durch Strg + Leertaste wieder öffnen. Die Vorschläge sind kontextsensitiv, wird also zum Beispiel eine Klasse erwartet, so werden auch nur Klassen angezeigt. Durch weiteres Tippen kann die Liste weiter gefiltert werden.

Für die Vorschläge wird das Modul im Hintergrund während des Tippens ständig neu geparsed und die Struktur ausgewertet. Da die Struktur sich an manchen Stellen verändert sobald ein Text vorhanden ist oder nicht, kann es sein, dass die Vorschläge erst richtig sind sobald mindestens ein Buchstabe eingegeben wurde. Da sich die Vorschläge erst nach Eingeben eines Buchstaben von selbst öffnen betrifft dieser Hinweis vor allem den Fall, wenn an einer leeren Stelle Strg + Leertaste gedrückt wird. Daher sollte stattdessen lieber der erste Buchstabe eingegeben werden.

Dateistruktur

Unter dem Explorer kann der Punkt Outline aufgeklappt werden. Hier wird eine Übersicht über die Symbole in der aktuellen Datei angezeigt. Die Liste kann über das Menü mit den drei Punkten nach Position oder Name sortiert werden. Wird auf ein Symbol geklickt, so springt der Editor an die entsprechende Stelle.

Brotkrümelnavigation

Am oberen Rand des Editors wird angezeigt wo sich der Cursor gerade befindet. Per Klick auf eines der Symbole innerhalb der Navigation werden ähnliche Symbole angezeigt und es kann direkt zu den anderen Symbolen navigiert werden.

Code Lenses

Wenn ein Symbol (Widget/Prozedur) abgeleitet ist oder in einem abgeleiteten Modul überschrieben wird, so wird das im Editor durch Hinweise über der entsprechenden Stelle, sogenannte Code Lenses, angezeigt. Durch Klick auf die Code Lenses kann zu der entsprechenden Stelle gesprungen werden.

Jedes Modul hat über der Moduldefinition eine Code Lens, die einen schnellen Überblick und Navigation durch die Modulstruktur und Hierarchie ermöglicht. Hier kann zur Definition des Basis-Moduls oder der Child-Module gesprungen werden, sowie alle Prozeduren/Variablen/Fenster und vom Modul abgefangenen Messages durchsucht (schließt geerbte Definitionen ein) und an deren Definition gesprungen werden.

Jedes Fenster enthält eine Codelens, die alle enthaltenen Widgets und abgefangen Messages auflistet.

Finden von Referenzen

Wenn der Cursor auf einem Symbol steht, so können mit der Tastenkombination Shift + Alt + F12 alle Verweise auf dieses Symbol gesucht werden. Das Suchergebnis wird dabei in der Seitenleiste angezeigt. Darüber hinaus können die Verweise über das Kontextmenü auch ohne Wechsel der Ansicht gesucht werden und direkt im Editor angezeigt werden. Dafür wählen Sie im Kontextmenü Peek → Peek References.

Umbennen eines Symbols

Wenn der Cursor auf einem Symbol steht, kann mittels F2 das Symbol umbenannt werden. Es werden dabei auch automatisch alle Verweise auf das Symbol geändert. Bitte beachten Sie hierzu auch die Hinweise zu Symbolen.

Import und ImportContext

Beim Hovern über einen ImportContext wird in einem Tooltip angezeigt, an welchen Provider dieser Kontext gebunden ist.
Platziert man den Cursor auf eine der Variablen innerhalb von bind(), dann kann man per F12 an die Definition der Variablen im Consumer-oder Provider-Modul springen. 

Das per Import importierte Widget zeigt in einem Tooltip die Widget-Hierarchie des importierten Widgets und per F12 kann hier auch an die Definition des importierten Widgets gesprungen werden.

Keybindings

Die Keybindings können unter über die "Keyboard Shortcuts" geändert werden. Dies geschieht entweder in dem man erst Strg + K und dann Strg + S drückt oder in dem über "File -> Preferences -> Keyboard Shortcuts" die Keyboard Shortcuts aufgerufen werden.

Empfohlene Anpassungen

Um in VS Code wie in Eclipse suchen zu können, sollten "Find Next" und "Find Next Selection" auf F3 gelegt werden.

In der Suchliste nach "Find Next" suchen und das Keybinding für "Find Next " und für "Find Next Selection" auf F3 ändern

In der Suchliste nach "Go to Bracket" suchen und das Keybinding auf "STRG+M" ändern. Mit diesem Tastenkürzel kann man mit dem Cursor zur passenden öffnenden/schließenden Klammer im Source-Code springen.

Liste mit nützlichen Tastenkürzeln

Optionen zur Verhinderung von White-Spaces setzen

Diese Optionen bewirken, dass in allen bearbeiteten Dateien beim Speichern automatisch die Leerzeichen am Zeilenende entfernt werden.
Außerdem wird eine sinnvolle Newline am Ende der Datei eingefügt, falls noch keine vorhanden ist.

Achtung: Beim Editieren von .bat-Dateien sollte diese Option nicht aktiv sein, da die häufig verwendete Variable CX_START_WAIT ein Leerzeichen am Ende erwartet und der Editor es einfach wegschneidet.

Hinweis zu Symbolen

Als Symbole werden alle Definitionen wie Module, Variablen, Prozeduren, Fenster oder Widgets bezeichnet. Um mögliche Symbole in einer Datei zu finden, muss die entsprechende Datei erst geparsed werden. Der Parser wird immer zu einem Modul auch alle Elternmodule parsen. In der Standardeinstellung werden auch alle Module geparsed, die vom höchsten Elternmodul des aktuellen Moduls direkt oder indirekt abgeleitet sind, so dass alle irgendwie in der Hierarchie vorkommenen Symbole bekannt sein wenn ein Modul geöffnet wird. Dieses Verhalten lässt sich in den Einstellungen mit dem Parameter Parser: Parse Full Hierarchy einstellen.

Soll ein systemweites Refactoring vorgenommen werden, so lässt sich in den Einstellungen über den Parameter Parser: Parse All Files auch einstellen, dass beim Start alle Module geparsed werden. Damit sind dann auch alle Symbole und deren Verwendungen bekannt. Da das aber beim Start etwas dauert, ist das nicht die Standardeinstellung. Wird ohne Parsen aller Module ein Symbol umbenannt, so ist nicht garantiert, dass auch wirklich alle Verwendungen mit angepasst werden.

Ab Version 3.0.0 erkennt der Parser selbst, welche Symbole global referenziert sein könnten und bei der Referenzsuche und beim Umbenennen dieser Symbole wird automatisch das Parsen aller Module angestoßen. Dieser globale Parsevorgang lässt sich wie folgt abbrechen. Die Refrenzsuche/Umbenennung bezieht sich dann aber nur auf die bis dahin geparsten Module.

Nach einer Änderung der Parse-Einstellung muss VSCode neu gestartet werden, damit die Änderung übernommen wird.

Debugging

Das Plugin bietet die Möglichkeit ein laufendes CyberEnterprise zu debuggen.

Debugger verbinden

Um eine Instanz des CyberEnterprise zu debuggen, rechtsklicken Sie bitte bei gehaltener Alt-Taste auf ein geöffnetes Fenster und wählen Sie im neu geöffneten Monitor Window die Schaltfläche Enable Debugging. Das Icon sollte sich nun grün färben, was anzeigt, das diese Instanz des CyberEnterprise zum Debuggen bereit ist.

Visual Studio Code benötigt für das Debugging eine Konfigurationsdatei launch.json. Sollten Sie noch keine besitzen, lässt diese sich leicht anlegen. Klicken Sie dafür auf das Debug-Symbol in der Leiste links. Klicken Sie dann auf Show all automatic debug configurations, anschließend wählen Sie Add Configuration... und zum Schluss InstantView Debugger.

Sobald eine Konfigurationsdatei exisitert, können Sie das Debuggen über den grünen Pfeil starten. Zuerst wird nach zu debuggenden Instanzen des CyberEnterprise gesucht und sobald Sie keine ausgewählt haben, wird der Debugger mit dieser Instanz verbunden. Sie erkennen die erfolgreiche Verbindung daran, dass die Statusleiste von Visual Studio Code orange wird.

Hinweis:
Bei Verbindungsproblemen sollte die verwendete Java-Version überprüft werden.

Übersicht

Das folgende Bild zeigt eine Übersicht der Informationen und Steuerungsmöglichkeiten während des Debuggings:

Am oberen Rand befinden sich die Kontrollelemente für das Debugging. Ganz links kann die Ausführung unterbrochen oder fortgesetzt werden. Mit den folgenden Schaltflächen kann der nächste Befehl ohne oder mit Hineinspringen ausgeführt werden mit der nächsten aus dem aktuellen Befehl herausgesgesprungen werden und mit der letzten Schaltfläche kann die Verbindung zwischen Debugger und ClassiX getrennt werden.

Auf der rechten Seite wird der Quelltext und die Debug-Konsole angezeigt und auf der linken Seite von oben nach unten der aktuelle Stack, lokale Variablen, Modulvariablen und globale Variablen, dann der aktuelle Call Stack und alle gesetzten Breakpoints.

Einige Variablen (Vektoren) können durch anklicken aufgeklappt werden, um deren Inhalt zu inspizieren.

Durch Anklicken eines Eintrags vom Callstack kann zu dem aufrufenden/aufgerufenen Befehl gesprungen werden und dabei wird auch die Anzeige des InstantView-Stacks aktualisiert, sodass man sieht, was vor dem Aufruf einer Prozedur auf dem Stack lag.

Breakpoints können entweder durch Klicken auf die Fläche links neben einer Zeilennummer gesetzt werden. Dann wird beim ersten Befehl einer Zeile angehalten. Alternativ kann der Cursor an eine Stelle gesetzt und Shift + F9 gedrückt werden. Dann erscheitn der Breakpoint direkt vor dem entsprechenden Befehl und die Ausführung würde dort anhalten.

Debug-Konsole

Falls die Ausführung des Prozesses innerhalb einer Prozedur/Message steht, dann kann in der Debug-Konsole beliebiger InstantView-Code ausgeführt werden. Hierdurch ist folgendes möglich:

• Der Stack kann nach Belieben zwischen zwei Requests verändert werden
• Lokale Variablen auf den Stack legen um deren Inhalt anzuzeigen
• Inhalt von lokalen Variablen verändern
• Neue lokale Variablen lassen sich definieren
• Informationen per Attention oder SystemObject Call(Log) ausgeben
• Programmablauf durch break, continue, return manipulieren
• Es können ganz normal Prozeduren aufgerufen werden und SendMsg() & PostMsg() verwendet werden.
• Es können per Define(proc) … ; neue Prozeduren definiert werden, die dann aufgerufen werden können.
• Per Define(proc) …; können auch bestehende Prozeduren überschrieben werden (auch in Providern). Das geänderte Verhalten sieht man, sobald die Prozedur das nächste Mal aufgerufen wird. 
  Hierbei ist zu beachten, dass Breakpoints in der alten Prozedur nicht mehr ausgelöst werden und man beim Debuggen durch die neue Prozedur keinen Code sehen kann.
   

Direktsprung in Quelltext

Es ist möglich aus der ClassiX-Shell heraus direkt an die entsprechende Stelle im Quelltext zu springen. Dafür ist die Konfiguration der Umgebungsvariablen CX_EDITOR nötig. Diese muss auf den Wert

code.cmd -r -g %s:%d:%d

gesetzt werden. Das kann entweder über die Systemeinstellungen oder in der bat-Datei zum Starten von ClassiX eingestellt werden. Es ist wichtig zu wissen, dass in einer bat-Datei die Prozentzeichen doppelt gesetzt werden müssen.

Mit dieser Einstellung wird die Datei in einer bereits geöffneten Instanz von Visual Studio Code geöffnet oder eine neue Instanz gestartet wenn keine offen ist. Sollte eine neue Instanz gestartet und die Datei darin geöffnet werden, wird der Basisordner nicht geöffnet, das bedeutet das Projekt wird auch nicht geladen. Es empfiehlt sich daher Visual Studio Code zuvor selbst im richtigen Ordner zu starten. Ansonsten sind bis auf die Syntaxhervorhebung alle Funktionalitäten nicht verfügbar. Alternativ kann auch noch eine Workspace-Datei angegeben werden, dann funktioniert auch das Öffnen des richtigen Projektes. Liegt die Workspace-Datei zum Beispiel unter C:\ClassiX\classix.code-workspace, ändert sich der Befehl zu:

code.cmd -r -g %s:%d:%d "C:\ClassiX\classix.code-workspace"