Die VS Code-Erweiterung im Detail

Ein Rundgang durch jeden Bildschirm der Archestack-Erweiterung für VS Code: was er zeigt, was er tut und wie du dorthin kommst. Archestack in VS Code ist die Anleitung für die Arbeit damit; diese Seite liefert die Details. Die Screenshots zeigen Service Planner, eine kleine App, die Serviceaufträge auf Techniker verplant und als Projekt auf dem Rechner läuft.

Das Projekt, sein Code und die App nebeneinander

VS Code mit der Archestack-Ansicht links, dem Code einer Page in der Mitte und rechts der laufenden Page, einer Planungstafel mit Aufträgen und Technikern.

Die Ansicht Archestack in der Aktivitätsleiste listet die Packages des Repositorys und ihren Inhalt. Im Editor steht der Code einer Page, und Open Preview to the Side rendert diese Page daneben mit den eigenen Daten des Projekts und folgt jeder Änderung, gespeichert oder nicht. Die Page wird im App Layout gezeichnet, das die veröffentlichte App um sie legt. Die Statusleiste zeigt, womit das Fenster verbunden ist: hier local, das Projekt.

Die Page Customers in der Vorschau auf einem iPhone 15 mit 55 Prozent, im Header des Layouts Service desk, darüber die Auswahl für Layout, Gerät und Zoom.

Die Werkzeugleiste der Vorschau wählt, worin und worauf die Page gezeichnet wird. Layout ist das App Layout um sie: Automatic nennt das Layout, das die veröffentlichte App verwenden würde, und sagt beim Darüberfahren, warum, oder du wählst ein anderes Layout oder keines. Die Geräteliste enthält Handys, Tablets und Desktops in echter Größe, dazu eine eigene Größe; ein Handy oder Tablet dreht sich ins Querformat, und der Zoom passt das Gerät ins Panel ein oder zeigt es mit einem Prozentwert. Die App darin misst die Breite des Geräts, also zeigt sich die Page so, wie sie auf diesem Gerät aussieht. Die nächste Vorschau öffnet auf dem Gerät, das du zuletzt gewählt hast.

Die Workspace-Ansicht

Der erste Knoten ist der Workspace selbst, mit seiner Adresse. Darunter listet jedes Package des Repositorys seine Artefakte nach Art, jeweils mit einer Anzahl: Script Modules, Business Events, Business Entities, Pages, Test Suites, Testfälle und Tabellen. In sync hinter der Version eines Packages heißt, dass das Projekt hat, was der Ordner hat; andernfalls trägt jedes Artefakt eine Markierung, so wie git Dateien markiert.

Ein Klick auf ein Artefakt öffnet seine Datei oder sein Formular; eine Page oder ein Template öffnet sich als Vorschau.
Go to Code, der Button in der Zeile eines Artefakts, öffnet direkt seinen Code, an der Vorschau einer Page vorbei; ein Artefakt ohne Code hat dort stattdessen Edit Settings, das sein Formular öffnet.
+ an einer Art oder einem Package schreibt die Dateien eines neuen Artefakts.
Der Ausführen-Button an einem Package, einer Suite oder einem Testfall führt diese Tests aus.
Ein Rechtsklick bietet Delete, Open in Builder und die übrigen Befehle an.

Die Liste der Statusleiste

Die Liste, die die Statusleiste öffnet: das laufende Projekt, andere Workspaces und die Aktionen des Projekts, etwa den Builder öffnen, stoppen, die API-Logs anzeigen und die Datenbank zurücksetzen.

Ein Klick auf den Eintrag in der Statusleiste öffnet eine einzige Liste für alles rund um die Verbindung: das Projekt und ob es läuft, die anderen Workspaces unter derselben Adresse und die Aktionen des Projekts. Von hier aus öffnest du den Builder des Projekts im Browser, stoppst das Projekt, liest die Logs der API oder setzt seine Datenbank zurück, was die Daten wegwirft und das Repository neu hineinlädt.

Einstellungen in Formularen

Ein Business Event in seinem Formular: Name, Business Entity, aktiviert und die Zeitpunkte, zu denen es feuert, etwa BeforeCreate und BeforeUpdate.

Die Einstellungen eines Artefakts sind die JSON-Datei neben seinem Code, und wenn du diese Datei öffnest, öffnet sich ein Formular. Das Formular eines Business Events enthält seinen Namen, seine Business Entity, ob es aktiviert ist, die Zeitpunkte, zu denen es feuert, seine Condition und seine Actions. Jede Änderung in einem Formular wird in die Datei geschrieben, git sieht sie also wie jede andere Änderung; Edit as JSON öffnet stattdessen den Text. Script Modules, Pages, PDF und Frontend Templates, Zeitpläne und Testfälle haben eigene Formulare.

Business Entities

Der Entity-Editor für Service Job: Master-Tabelle, Label-Spalte, Joins auf die Kunden- und die Techniker-Tabelle und die Spalten.

Eine Business Entity öffnet sich im Entity-Editor: ihre Master-Tabelle und Label-Spalte, ihre Joins (von welcher Tabelle, welche Art, auf welche Tabelle und Spalte und wie viele Zeilen ein Join ergibt) und ihre Spalten in ihrer Reihenfolge, jede mit einem Aggregat und der Entity, von der ein Schlüssel seine Labels nimmt. Tabellen und Spalten werden aus der Datenbank des Projekts ausgewählt, ein Name, der nicht existiert, lässt sich also gar nicht wählen.

C# mit dem eigenen Compiler des Projekts

Vervollständigung in einem Skript nach Db.Serv, die die typisierten Sets ServiceCustomer, ServiceJob und ServiceTechnician anbietet.

Skripte werden vom Projekt selbst kompiliert, gegen dieselben Globals und dasselbe Datenmodell, mit denen sie laufen. Jede Business Entity ist ein typisiertes Set auf Db, die Vervollständigung bietet also ServiceJob und die anderen Sets an und nach dem Punkt ihre Spalten.

Ein Hover über Db.ServiceJob, der seinen Typ zeigt und den Hinweis, dass es die Business Entity Service Job ist, die Zeilen von service_job.

Fährst du mit der Maus über einen Namen, siehst du seinen Typ und seine Dokumentation, hier, dass Db.ServiceJob die Business Entity Service Job ist, die Zeilen von service_job. Parameterinfo erscheint, während du einen Aufruf tippst, und Fehler werden beim Tippen unterstrichen.

Go to Definition auf ServiceJob öffnet die erzeugte, schreibgeschützte Klasse WorkspaceDb mit einem typisierten Set pro Business Entity.

Go to Definition (F12) auf einem typisierten Set öffnet das Datenmodell, das das Projekt aus seinen Tabellen und Business Entities erzeugt hat, schreibgeschützt. Auf der Methode eines Script Modules öffnet es das Skript dieses Moduls und auf einem Parameter die Einstellungen, die ihn deklarieren.

Typen, die mehr als ein Skript braucht, liegen als Shared Code in C#-Dateien im Ordner code/ eines Packages, und Shared code in der Workspace-Ansicht listet die Shared-Code-Dateien eines Workspaces. Sie bekommen dieselben Funktionen, und F12 auf einem Typ aus dem Shared Code öffnet in einem Skript die Datei, die ihn deklariert.

Ein Script Module testen

Links der Code von GetPlannerWeek, rechts sein Test-Panel: der Parameter week_start, Run test, Passed und die zurückgegebene Woche.

Test, der Link über dem Code eines Script Modules, öffnet daneben ein Panel, das das Modul als Probelauf ausführt, mit dem Code, wie er im Editor steht. Es fragt nach den Parametern und merkt sie sich, zeigt, ob der Test bestanden ist, wie lange er gedauert hat, was das Modul zurückgegeben und was es ins Log geschrieben hat, und listet die Schreibvorgänge, Mails und Benachrichtigungen, die es aufgezeichnet statt ausgeführt hat. Ein Fehler zeigt seine Meldung mit einem Button zur Zeile. Show the SQL it ran schickt seine Statements ins Panel SQL Trace.

Page-Code und seine Referenz

Der Code einer Page links und die Referenz What page code can use rechts, beginnend mit backend.

Page- und Template-Code wird gegen das geprüft, was er zur Laufzeit hat: backend, pageContext, React, jede MUI-Komponente und einen Zeilentyp pro Business Entity. What page code can use, der Link über dem Code, öffnet daneben die vollständige Liste, jedes Global mit dem, was es tut, und einem Beispiel.

Page-Code kann importieren: die eigenen Dateien einer Page neben ihren Ansichten als ./OrderRow und Module aus dem Shared Code im Ordner code/ eines Packages als @/components/StatusChip. Imports sind typisiert, F12 folgt ihnen, und eine Umbenennung ändert jede Datei, die den Namen verwendet.

Tabellen

Eine Tabellendatei öffnet sich im Tabelleneditor: ihre Label-Spalte, ob sie Audit-Spalten hat, und eine Zeile pro Spalte mit ihrem Namen, ihrem Typ, ihrer Länge, ihrem Schlüssel, ob sie leer sein darf, ob sie eindeutig ist, ihrem Default und der Tabelle, auf die sie verweist. Darunter folgen die Indizes. Jede Änderung wird in die Datei geschrieben, packages/<package>/tables/<table>.json.

Das Datenbankdiagramm mit service_job und seinen Fremdschlüsseln auf service_customer und service_technician, gefiltert auf das Package Service Planner.

Open Database Diagram zeichnet die Tabellen und ihre Fremdschlüssel. Wähle ein Package, um nur seine Tabellen zu sehen; Overview passt alle ins Fenster ein, + Table beginnt eine neue, und Review and publish öffnet die Schema-Überprüfung. Doppelklicke auf eine Tabelle, um sie zu bearbeiten; zieh an ihrem Kopf, um sie zu verschieben, was in der layout.json des Packages gespeichert wird.

Migrationen

Die Schema-Überprüfung: die geänderte Tabelle service_job, ein Plan mit einer sicheren Operation, die eine Spalte hinzufügt, ihr SQL, die Prüfung der typisierten Skripte und die Skripte vor und nach dem Deployment.

Add Migration vergleicht die Tabellendateien mit der Datenbank des Projekts und zeigt die Überprüfung: welche Tabellen sich ändern, jede Operation mit ihrem Risiko (hier safe), das genaue SQL, ob jedes typisierte Skript gegen die geänderten Tabellen noch kompiliert, und Platz für SQL, das vor und nach der Änderung läuft.

Die Ansicht Deployments mit einer ausstehenden Migration über dem Deployment, das die Tabellen des Repositorys angelegt hat.

Einmal hinzugefügt, wartet die Migration in der Ansicht Deployments als ausstehendes Deployment, benannt nach dem, was sie ändert, bis Deploy sie ausführt. Die Ansicht ist die ganze Historie der Datenbank, das neueste zuerst; Roll Back to Here auf einem früheren Deployment plant, die Tabellen auf dessen Stand zurückzubringen.

SQL-Konsole

Links eine SQL-Abfrage, die Aufträge und Techniker joint, rechts ihre 13 Zeilen im Panel SQL Results.

New SQL Query öffnet einen Editor auf der Datenbank des Projekts, mit Vervollständigung für Tabellen und Spalten. Run Query (Ctrl+Enter) führt die Auswahl oder die ganze Datei aus, Statement für Statement, und die Ergebnisse öffnen sich daneben, jedes als CSV kopierbar. Ein Fehler sagt, welches Statement fehlgeschlagen ist und wo, und die Statements davor bleiben ausgeführt.

Explain Query und Explain Analyze Query (Ctrl+Alt+Enter) öffnen den Plan des Statements in Query Plan: jeden Schritt mit seinem Anteil an der Zeit, gefundene gegen erwartete Zeilen und einen Hinweis, wo ein Schritt weit mehr liest, als er behält. Analyze führt das Statement aus und rollt es zurück.

SQL-Trace

Trace SQL, an einem Script Module oder einer Business Entity in der Workspace-Ansicht oder an ihrer Datei, führt das Modul aus (als Probelauf, wenn du nichts anderes wählst) oder liest die Entity so, wie ein Grid es tut, und listet in SQL Trace, was an die Datenbank ging: jedes Statement mit seinen Werten, seiner Zeit und dem Code, der es gesendet hat, der Reihe nach oder mit gleichen Statements zusammengefasst, wo eine Abfrage, die einmal pro Zeile gesendet wird, sofort auffällt. Für jedes Statement lässt sich der Plan anzeigen, und es lässt sich mit eingesetzten Werten als SQL öffnen oder kopieren. In der Ansicht Testing macht Run with SQL Trace dasselbe für Testfälle.

Tests

Die Workspace-Ansicht mit den Testfällen von Service Planner, jeder nach einem Lauf mit einem grünen Haken.

Run Tests führt die Tests aller Packages aus, oder über den eigenen Ausführen-Button die eines Packages, einer Suite oder eines Testfalls. Jeder Testfall läuft in einer eigenen Sandbox-Datenbank und zeigt sein Ergebnis im Baum, sobald er fertig ist; ein Klick auf einen gelaufenen Testfall öffnet, was er geprüft hat, Erwartung gegen Ist-Wert, und was er ausgegeben hat. Die Ansicht Testing listet dieselben Testfälle.

Event Log

Die Ansicht Event Log zeigt, was im Projekt gelaufen ist, gruppiert nach Art, mit den Fehlschlägen und der Gesamtzahl des letzten Tages an jeder Gruppe. Hier sind es die Business Events, die die Tests ausgelöst haben: Die meisten waren erfolgreich, und die, von denen ein Test erwartet hat, dass sie ein Speichern ablehnen, sind fehlgeschlagen. Ein Fehlschlag wird im Badge der Ansicht gezählt und gemeldet, sobald er passiert. Ein Klick auf einen Eintrag öffnet alles, was er aufgezeichnet hat, und Open Artifact springt zu dem Skript, in dem er fehlgeschlagen ist, auf die fehlerhafte Zeile.

Data API

Die Ansicht Data API listet die Endpunkte des Projekts, jeden mit seinen Versionen und deren Status, und seine API-Clients. Die Schaltflächen in ihrem Titel fügen einen Endpunkt oder einen API-Client hinzu und öffnen das OpenAPI-Dokument mit allem, was du aufrufen darfst. Ein Klick auf einen Endpunkt öffnet ihn, aus dem Ordner, wenn ein Package dort ihn enthält; ein Klick auf eine bediente Version probiert sie aus.

Das Formular des Endpunkts Customers: Business Entity, Name und Route, wer ihn aufrufen darf, und Version 2 mit Status, Sunset, Seitengröße, Operationen und einer Tabelle der Felder.

Das Formular eines Endpunkts bearbeitet api/customers.json: die Entity, die er bereitstellt, seinen Namen und seine Route und jede Version mit Status, Sunset-Tag, Seitengröße, Operationen und Feldern. Die Feldtabelle nimmt die Spalte jedes Felds aus der Entity und sagt, wenn eine Spalte nicht geschrieben werden kann. Eine veröffentlichte Version sagt das, denn sie kann nur wachsen; + New version kopiert die angezeigte, für die Änderung, die sie brechen würde. Wer den Endpunkt aufrufen darf, steht nicht in der Datei: Edit access in the workspace öffnet seine Freigaben im Projekt.

Das Formular des Endpunkts Planner week, der ein Script Module aufruft: Version 1, aktiv, ruft GetPlannerWeek mit GET auf und übergibt einen Parameter, weekStart, an week_start des Moduls, Pflicht und mit Beschreibung.

Ein Endpunkt kann statt einer Entity auch ein Script Module aufrufen. Jede Version nennt das Modul und seine Methode, POST mit den Parametern in einem JSON-Body oder GET mit ihnen im Query-String, und listet die Parameter auf, die Aufrufer senden: ein öffentlicher Name über einem Parameter des Moduls, sein Typ, ob er Pflicht ist, und eine Beschreibung. Add remaining parameters fügt die übrigen Parameter des Moduls hinzu, und das Formular markiert einen Parameter, den das Modul braucht, die Version aber nicht übergibt. Einmal veröffentlicht, behält eine Version ihr Modul und ihre Methode und bekommt nur optionale Parameter hinzu. Ein als admin only markiertes Modul rufen nur Admins und Owner auf, und das Formular sagt es.

Try Customers: Version 2 und der Request GET /, eine Query, gesendet als der angemeldete Benutzer, der curl-Befehl und die Antwort, 200 mit den Kunden als JSON.

Try It sendet echte Requests an eine Version: eine Liste mit einer Query, ein Get oder ein Create, Update oder Delete mit einem Beispiel-Body aus den schreibbaren Feldern der Version, bei einem Endpunkt, der ein Script Module aufruft, den Aufruf mit Beispielparametern. Sende sie als du selbst, auf Wunsch mit dem ausgeführten SQL, oder mit dem Schlüssel eines API-Clients, um zu sehen, was dieser Client darf. Die Antwort erscheint so, wie sie ankam, mit Status, Versions-Headern und Body, und Copy as curl liefert denselben Request mit einem Platzhalter, wo das Geheimnis hingehört.

Ein API-Client öffnet sich in einem eigenen Formular: Name, Rollen, Ablaufdatum und ob er aktiv ist. Einen anzulegen, oder Rotate Key auf einem bestehenden, zeigt seinen Schlüssel einmal, mit einem Befehl, der prüft, dass er funktioniert.

Workspace-Einstellungen

Die eigenen Einstellungen des Workspaces sind Dateien in workspace/ und öffnen sich ebenfalls in Formularen. Das Branding-Formular zeigt eine Vorschauleiste in den Farben der App, den App-Namen, das Logo und seine Größe sowie die Farben; das Formular der App Layouts enthält Header und Sidebar der veröffentlichten App. Das Projekt übernimmt sie, wenn du speicherst.

Wie es weitergeht

Archestack in VS Code behandelt, wie du die Erweiterung installierst, ein Projekt startest und im Team arbeitest, und Deployment-Strategie, wie das Repository Test, Abnahme und Produktion erreicht.