L'estensione VS Code nel dettaglio
Un giro di ogni schermata dell'estensione Archestack per VS Code: cosa mostra, cosa fa e come ci si arriva. Archestack in VS Code è la guida per lavorarci; questa pagina è il dettaglio. Gli screenshot mostrano Service Planner, una piccola app per assegnare gli interventi di assistenza ai tecnici, che gira come progetto sulla macchina.
Il progetto, il suo codice e l'app fianco a fianco
La vista Archestack nella barra delle attività elenca i package del repository
e ciò che contengono. L'editor contiene il codice di una pagina, e Open Preview to the
Side renderizza quella pagina accanto con i dati del progetto stesso, seguendo ogni
modifica, salvata o no. La pagina viene disegnata dentro l'app layout che l'app pubblicata le
mette intorno. La barra di stato mostra a cosa è connessa la finestra: qui local,
il progetto.
La barra degli strumenti dell'anteprima sceglie in cosa e su cosa viene disegnata la pagina. Layout è l'app layout intorno: Automatic nomina quello che userebbe l'app pubblicata e dice perché passandoci sopra, oppure scegli un altro layout, o nessuno. L'elenco dei dispositivi contiene telefoni, tablet e desktop alla dimensione reale, più una dimensione tua; un telefono o un tablet ruota in orizzontale, e lo zoom adatta il dispositivo al pannello o lo mostra a una percentuale. L'app misura la larghezza del dispositivo, così la pagina prende la forma che ha su quel dispositivo. L'anteprima successiva si apre sull'ultimo dispositivo che hai scelto.
La vista Workspace
Il primo nodo è il workspace stesso, con il suo indirizzo. Sotto, ogni package del repository elenca i suoi artefatti per tipo, ognuno con un conteggio: script module, business event, business entity, pagine, test suite, test case e tabelle. In sync dopo la versione di un package dice che il progetto ha ciò che ha la cartella; altrimenti ogni artefatto porta un segno, come git segna i file.
- Un clic su un artefatto apre il suo file, o il suo form; una pagina o un template si apre come anteprima.
- Go to Code, il pulsante sulla riga di un artefatto, apre subito il suo codice, saltando l'anteprima di una pagina; un artefatto senza codice ha lì Edit Settings, che apre il suo form.
- + su un tipo o su un package scrive i file di un nuovo artefatto.
- Il pulsante di esecuzione su un package, una suite o un test case esegue quei test.
- Il clic destro offre Delete, Open in Builder e il resto.
L'elenco della barra di stato
Un clic sulla voce della barra di stato apre un solo elenco per tutto ciò che riguarda la connessione: il progetto e se è in esecuzione, gli altri workspace sullo stesso indirizzo e le azioni del progetto. Da qui apri il builder del progetto nel browser, fermi il progetto, leggi i log dell'API o resetti il suo database, cosa che butta via i dati e carica di nuovo il repository.
Impostazioni nei form
Le impostazioni di un artefatto sono il file JSON accanto al suo codice, e aprire quel file apre un form. Il form di un business event contiene il nome, la business entity, se è abilitato, i momenti in cui scatta, la condizione e le azioni. Ogni modifica in un form viene scritta nel file, quindi git la vede come qualsiasi altra modifica; Edit as JSON apre invece il testo. Script module, pagine, PDF template e frontend template, pianificazioni e test case hanno form propri.
Business entity
Una business entity si apre nell'editor delle entity: la sua master table e la colonna etichetta, i suoi join (da quale tabella, di che tipo, su quale tabella e colonna, e quante righe dà un join) e le sue colonne in ordine, ognuna con un aggregato e l'entity da cui una chiave prende le etichette. Tabelle e colonne si scelgono dal database del progetto, quindi non si può scegliere un nome che non esiste.
C# con il compilatore del progetto stesso
Gli script vengono compilati dal progetto stesso, rispetto agli stessi globali e allo stesso
modello dati con cui girano. Ogni business entity è un set tipizzato su Db, quindi
il completamento offre ServiceJob e gli altri set e, dopo il punto, le loro colonne.
Passando il mouse su un nome se ne vedono il tipo e la documentazione, qui che
Db.ServiceJob è la business entity Service Job, le righe di
service_job. Le informazioni sui parametri compaiono mentre scrivi una chiamata, e
gli errori vengono sottolineati mentre scrivi.
Go to Definition (F12) su un set tipizzato apre il modello dati che il progetto ha generato dalle sue tabelle e business entity, in sola lettura. Sul metodo di uno script module apre lo script di quel modulo, e su un parametro le impostazioni che lo dichiarano.
I tipi che servono a più di uno script stanno in file C# condivisi sotto la cartella
code/ di un package, e Shared code nella vista Workspace elenca
quelli di un workspace. Hanno le stesse funzionalità, e F12 su un tipo condiviso in uno script
apre il file che lo dichiara.
Provare uno script module
Test, il link sopra il codice di uno script module, apre accanto un pannello che esegue il modulo in simulazione, con il codice così come lo ha l'editor. Chiede i parametri e li ricorda, mostra se è passato, quanto è durato, cosa ha restituito e cosa ha scritto nel log, ed elenca le scritture, le mail e le notifiche registrate invece che eseguite. Un errore mostra il messaggio con un pulsante che porta alla riga. Show the SQL it ran manda le sue istruzioni al pannello SQL Trace.
Il codice delle pagine e il suo riferimento
Il codice delle pagine e dei template viene controllato rispetto a ciò che ha a disposizione
quando gira: backend, pageContext, React, ogni componente MUI e un tipo
di riga per ogni business entity. What page code can use, il link sopra il
codice, apre accanto l'elenco completo, ogni globale con cosa fa e un esempio.
Il codice delle pagine può importare: i file propri di una pagina accanto alle sue viste come
./OrderRow, e i moduli condivisi dalla cartella code/ di un package come
@/components/StatusChip. Gli import sono tipizzati, F12 li segue, e un rename
modifica ogni file che usa quel nome.
Tabelle
Un file di tabella si apre nell'editor delle tabelle: la sua colonna etichetta, se ha le colonne
di audit, e una riga per ogni colonna con il nome, il tipo, la lunghezza, la chiave, se può
essere vuota, se è unica, il default e la tabella a cui fa riferimento. Sotto seguono gli
indici. Ogni modifica viene scritta nel file,
packages/<package>/tables/<table>.json.
Open Database Diagram disegna le tabelle e le loro foreign key. Scegli un
package per vedere solo le sue tabelle; Overview le fa stare tutte nella
finestra, + Table ne inizia una nuova e Review and publish apre
la revisione dello schema. Fai doppio clic su una tabella per modificarla; trascina
un'intestazione per spostarla, e la posizione viene salvata nel layout.json del
package.
Migration
Add Migration confronta i file delle tabelle con il database del progetto e mostra la revisione: quali tabelle cambiano, ogni operazione con il suo rischio (qui safe), l'SQL esatto, se ogni script tipizzato compila ancora con le tabelle modificate, e lo spazio per l'SQL da eseguire prima e dopo la modifica.
Una volta aggiunta, la migration aspetta nella vista Deployments come deployment in sospeso, con un nome che dice cosa cambia, finché Deploy non la esegue. La vista è l'intera cronologia del database, dal più recente; Roll Back to Here su un deployment precedente pianifica il ritorno delle tabelle a quel punto.
Console SQL
New SQL Query apre un editor sul database del progetto, con il completamento di tabelle e colonne. Run Query (Ctrl+Enter) esegue la selezione o l'intero file, un'istruzione alla volta, e i risultati si aprono accanto, ognuno copiabile come CSV. Un errore dice quale istruzione è fallita e dove, e le istruzioni precedenti restano eseguite.
Explain Query ed Explain Analyze Query (Ctrl+Alt+Enter) aprono il piano dell'istruzione in Query Plan: ogni passo con la sua quota di tempo, le righe trovate contro quelle attese, e una nota dove un passo legge molto più di quanto tiene. Analyze esegue l'istruzione e poi fa il rollback.
Tracciamento SQL
Trace SQL, su uno script module o una business entity nella vista Workspace o sul suo file, esegue il modulo (in simulazione, a meno che tu non scelga diversamente) o legge l'entity come fa una griglia, ed elenca in SQL Trace ciò che ha inviato al database: ogni istruzione con i suoi valori, il suo tempo e il codice che l'ha inviata, in ordine o con le istruzioni uguali raggruppate, dove una query inviata una volta per riga salta all'occhio. Di ogni istruzione si può vedere il piano, e la si può aprire come SQL o copiare con i valori al loro posto. Nella vista Testing, Run with SQL Trace fa lo stesso per i test case.
Test
Run Tests esegue i test di tutti i package, oppure quelli di un package, di una suite o di un test case dal loro pulsante di esecuzione. Ogni test case gira in un database sandbox tutto suo e mostra il suo risultato nell'albero quando finisce; un clic su un test case eseguito apre cosa ha controllato, atteso contro effettivo, e cosa ha stampato. La vista Testing elenca gli stessi test case.
Event Log
La vista Event Log mostra cosa è stato eseguito nel progetto, raggruppato per tipo, con i fallimenti e il totale dell'ultimo giorno su ogni gruppo. Qui ci sono i business event fatti scattare dai test: la maggior parte è riuscita, e quelli che secondo un test dovevano rifiutare un salvataggio sono falliti. Un fallimento viene contato sul badge della vista e segnalato nel momento in cui avviene. Un clic su una voce apre tutto ciò che ha registrato, e Open Artifact va allo script in cui è fallita, sulla riga che ha fallito.
Data API
La vista Data API elenca gli endpoint del progetto, ognuno con le sue versioni e il loro stato, e i suoi API client. I pulsanti nel suo titolo aggiungono un endpoint o un API client e aprono il documento OpenAPI di tutto ciò che puoi chiamare. Un clic su un endpoint lo apre, dalla cartella quando un package lì lo contiene; un clic su una versione servita la prova.
Il form di un endpoint modifica api/customers.json: l'entity che espone, il nome e la
route, e ogni versione con stato, giorno di sunset, dimensione della pagina, operazioni e campi. La
tabella dei campi prende la colonna di ogni campo dall'entity e dice quando una colonna non può
essere scritta. Una versione pubblicata lo dice, perché può solo crescere; + New
version copia quella mostrata, per la modifica che la romperebbe. Chi può chiamare
l'endpoint non è nel file: Edit access in the workspace apre le sue autorizzazioni
nel progetto.
Un endpoint può chiamare uno script module invece di esporre una entity. Ogni versione nomina il modulo e il suo metodo, POST con i parametri in un body JSON o GET con i parametri nella query string, ed elenca i parametri che i chiamanti inviano: un nome pubblico su un parametro del modulo, il suo tipo, se è obbligatorio e una descrizione. Add remaining parameters aggiunge gli altri parametri del modulo, e il form segnala un parametro di cui il modulo ha bisogno ma che la versione non passa. Una volta pubblicata, una versione mantiene il suo modulo e il suo metodo, e acquisisce solo parametri facoltativi. Un modulo segnato come admin only lo chiamano solo admin e owner, e il form lo dice.
Try It invia richieste reali a una versione: un elenco con una query, un get, o un create, update o delete con un body di esempio fatto dai campi scrivibili della versione; su un endpoint che chiama uno script module, la chiamata con parametri di esempio. Inviale come te, con l'SQL eseguito se vuoi, o con la chiave di un API client, per vedere cosa è permesso a quel client. La risposta appare così com'è arrivata, con lo stato, gli header di versione e il body, e Copy as curl dà la stessa richiesta con un segnaposto al posto del segreto.
Un API client si apre in un form tutto suo: nome, ruoli, scadenza e se è attivo. Crearne uno, o Rotate Key su uno esistente, mostra la sua chiave una sola volta, con un comando per verificare che funzioni.
Impostazioni del workspace
Le impostazioni del workspace stesso sono file in workspace/ e si aprono anche loro
in form. Il form del branding mostra una barra di anteprima nei colori dell'app, il nome
dell'app, il logo e la sua dimensione, e i colori; il form degli app layout contiene l'header e
la sidebar dell'app pubblicata. Il progetto li riceve quando salvi.
Dove andare dopo
Archestack in VS Code spiega come installare l'estensione, avviare un progetto e lavorare in team, e Strategia di deployment come il repository arriva in test, collaudo e produzione.