De VS Code-extensie in detail

Een rondleiding langs elk scherm van de Archestack-extensie voor VS Code: wat het toont, wat het doet en hoe je er komt. Archestack in VS Code is de handleiding om ermee te werken; deze pagina is het detail. De screenshots tonen Service Planner, een kleine app om serviceopdrachten in te plannen bij technici, die als project op de machine draait.

Het project, zijn code en de app naast elkaar

VS Code met links de view Archestack, in het midden de code van een pagina en rechts de draaiende pagina, een planbord met opdrachten en technici.

De view Archestack in de activiteitenbalk toont de packages van de repository en wat erin zit. De editor bevat de code van een pagina, en Open Preview to the Side rendert die pagina ernaast met de eigen data van het project, en volgt elke bewerking, opgeslagen of niet. De pagina wordt getekend in de app-layout die de gepubliceerde app eromheen zet. De statusbalk toont waarmee het venster verbonden is: hier local, het project.

De pagina Customers als preview op een iPhone 15 op 55 procent, in de header van de layout Service desk, met de keuzes voor layout, toestel en zoom erboven.

De werkbalk van de preview kiest waarin en waarop de pagina getekend wordt. Layout is de app-layout eromheen: Automatic noemt de layout die de gepubliceerde app zou gebruiken en zegt waarom als je erover hovert, of kies een andere layout, of geen. De lijst met toestellen bevat telefoons, tablets en desktops op ware grootte, plus een eigen formaat; een telefoon of tablet draait naar liggend, en zoom past het toestel in het paneel of toont het op een percentage. De app erin meet de breedte van het toestel, dus de pagina krijgt de vorm die ze op dat toestel heeft. De volgende preview opent op het toestel dat je het laatst koos.

De Workspace-view

Het eerste knooppunt is de werkruimte zelf, met het adres ervan. Daaronder toont elke package van de repository zijn artefacten per soort, elk met een aantal: script modules, business events, business entities, pagina's, test suites, testcases en tabellen. In sync na de versie van een package betekent dat het project heeft wat de map heeft; anders draagt elk artefact een markering, zoals git bestanden markeert.

Een klik op een artefact opent zijn bestand of zijn formulier; een pagina of template opent als preview.
Go to Code, de knop op de rij van een artefact, opent meteen zijn code, langs de preview van een pagina heen; een artefact zonder code heeft daar Edit Settings, dat zijn formulier opent.
+ op een soort of een package schrijft de bestanden van een nieuw artefact.
De runknop op een package, een suite of een case draait die tests.
Rechtsklikken biedt Delete, Open in Builder en de rest.

De lijst van de statusbalk

De lijst die de statusbalk opent: het draaiende project, andere werkruimtes, en de acties van het project, zoals de builder openen, stoppen, de logs van de API tonen en de database resetten.

Een klik op het item in de statusbalk opent één lijst voor alles over de verbinding: het project en of het draait, de andere werkruimtes op hetzelfde adres, en de acties van het project. Van hieruit open je de builder van het project in de browser, stop je het project, lees je de logs van de API, of reset je de database, wat de data weggooit en de repository opnieuw inlaadt.

Instellingen in formulieren

Een business event open in zijn formulier: naam, business entity, ingeschakeld, en de momenten waarop het vuurt, zoals BeforeCreate en BeforeUpdate.

De instellingen van een artefact zijn het JSON-bestand naast zijn code, en dat bestand openen opent een formulier. Het formulier van een business event bevat de naam, de business entity, of het ingeschakeld is, de momenten waarop het vuurt, de conditie en de acties. Elke wijziging in een formulier wordt in het bestand geschreven, dus git ziet ze zoals elke andere bewerking; Edit as JSON opent in plaats daarvan de tekst. Script modules, pagina's, PDF- en frontend templates, schedules en testcases hebben hun eigen formulieren.

Business entities

De entity-editor voor Service Job: master-tabel, labelkolom, joins naar de tabellen van de klanten en de technici, en de kolommen.

Een business entity opent in de entity-editor: zijn master-tabel en labelkolom, zijn joins (vanuit welke tabel, welk type, naar welke tabel en kolom, en hoeveel rijen een join geeft), en zijn kolommen in volgorde, elk met een aggregaat en de entity waar een sleutel zijn labels van haalt. Tabellen en kolommen kies je uit de database van het project, dus een naam die niet bestaat, kan niet gekozen worden.

C# met de eigen compiler van het project

Aanvulling in een script na Db.Serv, met de getypte sets ServiceCustomer, ServiceJob en ServiceTechnician.

Scripts worden door het project zelf gecompileerd, tegen dezelfde globals en hetzelfde datamodel waarmee ze draaien. Elke business entity is een getypte set op Db, dus de aanvulling biedt ServiceJob en de andere sets aan, en na de punt hun kolommen.

Een hover over Db.ServiceJob met het type en de notitie dat het de business entity Service Job is, de rijen van service_job.

Een hover over een naam toont het type en de documentatie, hier dat Db.ServiceJob de business entity Service Job is, de rijen van service_job. Parameterinfo verschijnt terwijl je een aanroep typt, en fouten worden onderstreept terwijl je typt.

Go to Definition op ServiceJob, dat de gegenereerde, alleen-lezen klasse WorkspaceDb opent met één getypte set per business entity.

Go to Definition (F12) op een getypte set opent het datamodel dat het project uit zijn tabellen en business entities genereerde, alleen-lezen. Op de methode van een script module opent het het script van die module, en op een parameter de instellingen die hem declareren.

Types die in meer dan één script nodig zijn, staan in gedeelde C#-bestanden in de map code/ van een package, en Shared code in de Workspace-view toont die van een werkruimte. Ze krijgen dezelfde functies, en F12 op een gedeeld type in een script opent het bestand dat het declareert.

Een script module testen

Links de code van GetPlannerWeek, rechts zijn testpaneel: de parameter week_start, Run test, Passed en de week die hij teruggaf.

Test, de link boven de code van een script module, opent ernaast een paneel dat de module als proefrun uitvoert, met de code zoals de editor die heeft. Het vraagt de parameters en onthoudt ze, toont of de test geslaagd is, hoe lang hij duurde, wat de module teruggaf en wat hij naar de log schreef, en somt de schrijfacties, mail en meldingen op die hij vastlegde in plaats van uitvoerde. Een fout toont zijn melding met een knop naar de regel. Show the SQL it ran stuurt zijn statements naar het paneel SQL Trace.

Paginacode en de referentie ervan

Links de code van een pagina en rechts de referentie What page code can use, die begint met backend.

Pagina- en templatecode wordt gecontroleerd tegen wat die code heeft wanneer ze draait: backend, pageContext, React, elke MUI-component en een rijtype per business entity. What page code can use, de link boven de code, opent de volledige lijst ernaast, elke global met wat hij doet en een voorbeeld.

Paginacode kan importeren: de eigen bestanden van een pagina naast de views als ./OrderRow, en gedeelde modules uit de map code/ van een package als @/components/StatusChip. Imports zijn getypt, F12 volgt ze, en hernoemen past elk bestand aan dat de naam gebruikt.

Tabellen

De tabeleditor voor service_job: labelkolom, audit-kolommen, en een rij per kolom met naam, type, lengte, sleutel, leeg, uniek, default en verwijzing.

Een tabelbestand opent in de tabeleditor: de labelkolom, of de tabel audit-kolommen heeft, en een rij per kolom met de naam, het type, de lengte, de sleutel, of hij leeg mag zijn, of hij uniek is, de default en de tabel waarnaar hij verwijst. De indexes volgen eronder. Elke wijziging wordt in het bestand geschreven, packages/<package>/tables/<table>.json.

Het databasediagram met service_job en zijn foreign keys naar service_customer en service_technician, gefilterd op de package Service Planner.

Open Database Diagram tekent de tabellen en hun foreign keys. Kies een package om alleen zijn tabellen te zien, Overview past ze allemaal in het venster, + Table begint een nieuwe, en Review and publish opent de schemareview. Dubbelklik op een tabel om hem te bewerken; versleep een kop om de tabel te verplaatsen, wat bewaard wordt in de layout.json van de package.

Migraties

De schemareview: de gewijzigde tabel service_job, een plan met één veilige operatie die een kolom toevoegt, de SQL ervan, de controle van de getypte scripts en de scripts voor en na de deployment.

Add Migration vergelijkt de tabelbestanden met de database van het project en toont de review: welke tabellen veranderen, elke operatie met haar risico (hier safe), de exacte SQL, of elk getypt script nog compileert tegen de gewijzigde tabellen, en ruimte voor SQL die voor en na de wijziging draait.

De view Deployments met een openstaande migratie boven de deployment die de tabellen van de repository maakte.

Eenmaal toegevoegd wacht de migratie in de view Deployments als een openstaande deployment, genoemd naar wat ze verandert, tot Deploy ze uitvoert. De view is de hele geschiedenis van de database, nieuwste eerst; Roll Back to Here op een eerdere deployment plant het terugzetten van de tabellen naar die deployment.

SQL-console

Links een SQL-query die opdrachten en technici joint, en rechts de 13 rijen ervan in het paneel SQL Results.

New SQL Query opent een editor op de database van het project, met aanvulling van tabellen en kolommen. Run Query (Ctrl+Enter) voert de selectie of het hele bestand uit, statement per statement, en de resultaten openen ernaast, elk resultaat als CSV te kopiëren. Een fout zegt welk statement faalde en waar, en de statements ervoor blijven uitgevoerd.

Explain Query en Explain Analyze Query (Ctrl+Alt+Enter) openen het plan van het statement in Query Plan: elke stap met zijn aandeel in de tijd, gevonden rijen tegenover verwachte rijen, en een opmerking waar een stap veel meer leest dan hij houdt. Analyze voert het statement uit en draait het terug.

SQL-trace

Trace SQL, op een script module of business entity in de Workspace-view of op zijn bestand, draait de module (als proefrun, tenzij je anders kiest) of leest de entity zoals een grid dat doet, en toont in SQL Trace wat er naar de database ging: elk statement met zijn waarden, zijn tijd en de code die het verstuurde, op volgorde of met gelijke statements samen, waar een query die één keer per rij wordt verstuurd meteen opvalt. Van elk statement kun je het plan zien, en je kunt het met ingevulde waarden als SQL openen of kopiëren. In de view Testing doet Run with SQL Trace hetzelfde voor testcases.

Tests

De Workspace-view met de testcases van Service Planner, elk met een groen vinkje na een run.

Run Tests draait de tests van elke package, of die van één package, suite of case via hun eigen runknop. Elke case draait in een eigen sandboxdatabase en toont zijn resultaat in de boomweergave wanneer hij klaar is; een klik op een case die gedraaid heeft, opent wat hij controleerde, verwacht tegenover werkelijk, en wat hij afdrukte. De view Testing toont dezelfde cases.

Event Log

De view Event Log toont wat er in het project gedraaid heeft, gegroepeerd per soort, met op elke groep de fouten en het totaal van de afgelopen dag. Hier zijn dat de business events die de tests in gang zetten: de meeste slaagden, en de events waarvan een test verwachtte dat ze een opslag zouden weigeren, faalden. Een fout wordt geteld op de badge van de view en gemeld zodra ze gebeurt. Een klik op een entry opent alles wat die heeft vastgelegd, en Open Artifact gaat naar het script waarin het misging, op de regel van de fout.

Data API

De view Data API toont de endpoints van het project, elk met zijn versies en hun status, en zijn API clients. De knoppen in de titel voegen een endpoint of een API client toe en openen het OpenAPI-document van alles wat jij mag aanroepen. Een klik op een endpoint opent het, uit de map als een package daar het heeft; een klik op een versie die bediend wordt, probeert ze.

Het formulier van het endpoint Customers: de business entity, naam en route, wie het mag aanroepen, en versie 2 met status, sunset, paginagrootte, operaties en een tabel met velden.

Het formulier van een endpoint bewerkt api/customers.json: de entity die het openstelt, de naam en de route, en elke versie met haar status, sunset-dag, paginagrootte, operaties en velden. De veldentabel haalt de kolom van elk veld uit de entity en zegt wanneer een kolom niet geschreven kan worden. Een gepubliceerde versie zegt dat, want ze kan alleen groeien; + New version kopieert de getoonde, voor de wijziging die haar zou breken. Wie het endpoint mag aanroepen, staat niet in het bestand: Edit access in the workspace opent de rechten in het project.

Het formulier van het endpoint Planner week, dat een script module aanroept: versie 1, actief, roept GetPlannerWeek aan met GET en geeft één parameter, weekStart, door aan week_start van de module, verplicht en met een beschrijving.

Een endpoint kan ook een script module aanroepen in plaats van een entity open te stellen. Elke versie noemt de module en haar methode, POST met de parameters in een JSON-body of GET met ze in de querystring, en somt de parameters op die aanroepers sturen: een publieke naam over een parameter van de module, het type, of hij verplicht is, en een beschrijving. Add remaining parameters voegt de andere parameters van de module toe, en het formulier markeert een parameter die de module nodig heeft maar die de versie niet doorgeeft. Eenmaal gepubliceerd houdt een versie haar module en methode, en krijgt ze er alleen optionele parameters bij. Een module die als admin only gemarkeerd is, wordt alleen door admins en owners aangeroepen, en het formulier zegt dat.

Try Customers: versie 2 en de request GET /, een query, verzonden als de aangemelde gebruiker, het curl-commando, en het antwoord, 200 met de klanten als JSON.

Try It stuurt echte requests naar een versie: een lijst met een query, een get, of een create, update of delete met een voorbeeldbody uit de schrijfbare velden van de versie; op een endpoint dat een script module aanroept, de aanroep met voorbeeldparameters. Stuur ze als jezelf, desgewenst met de SQL die ze draaiden, of met de sleutel van een API client, om te zien wat die client mag. Het antwoord verschijnt zoals het binnenkwam, met de status, de versieheaders en de body, en Copy as curl geeft dezelfde request met een plaatshouder waar het geheim hoort.

Een API client opent in een eigen formulier: de naam, de rollen, de vervaldatum en of hij aan staat. Een nieuwe aanmaken, of Rotate Key op een bestaande, toont de sleutel één keer, met een commando om te controleren dat hij werkt.

Instellingen van de werkruimte

De eigen instellingen van de werkruimte zijn bestanden in workspace/ en openen ook in formulieren. Het brandingformulier toont een previewbalk in de kleuren van de app, de naam van de app, het logo en de grootte ervan, en de kleuren; het formulier van de app-layouts bevat de header en de sidebar van de gepubliceerde app. Het project neemt ze op wanneer je opslaat.

Waar dit naartoe gaat

Archestack in VS Code behandelt het installeren van de extensie, een project starten en werken als team, en Deploymentstrategie hoe de repository test, acceptatie en productie bereikt.