L'extension VS Code en détail

Une visite de chaque écran de l'extension Archestack pour VS Code : ce qu'il montre, ce qu'il fait et comment y accéder. Archestack dans VS Code est le guide pour travailler avec elle ; cette page en donne le détail. Les captures d'écran montrent Service Planner, une petite application qui planifie des interventions et les attribue à des techniciens, et qui tourne comme projet sur la machine.

Le projet, son code et l'application côte à côte

VS Code avec la vue Archestack à gauche, le code d'une page au milieu et, à droite, la page en cours d'exécution, un tableau de planification avec des interventions et des techniciens.

La vue Archestack dans la barre d'activité liste les packages du dépôt et ce qu'ils contiennent. L'éditeur affiche le code d'une page, et Open Preview to the Side rend cette page à côté avec les propres données du projet, en suivant chaque modification, enregistrée ou non. Elle est dessinée dans le layout d'application que l'application publiée met autour d'elle. La barre d'état indique à quoi la fenêtre est connectée : ici local, le projet.

La page Customers en aperçu sur un iPhone 15 à 55 %, dans l'en-tête du layout Service desk, avec les choix de layout, d'appareil et de zoom au-dessus.

La barre d'outils de l'aperçu choisit dans quoi et sur quoi la page est dessinée. Layout est le layout d'application autour d'elle : Automatic nomme celui que l'application publiée utiliserait et dit pourquoi au survol, ou choisissez un autre layout, ou aucun. La liste des appareils contient des téléphones, des tablettes et des ordinateurs à leur taille réelle, plus une taille de votre choix ; un téléphone ou une tablette passe en paysage, et le zoom ajuste l'appareil au panneau ou l'affiche à un pourcentage. L'application mesure la largeur de l'appareil, si bien que la page prend la forme qu'elle a sur cet appareil. L'aperçu suivant s'ouvre sur le dernier appareil choisi.

La vue Workspace

Le premier nœud est l'espace de travail lui-même, avec son adresse. En dessous, chaque package du dépôt liste ses artefacts par type, chacun avec son nombre : Script Modules, Business Events, Business Entities, pages, suites de test, cas de test et tables. In sync après la version d'un package indique que le projet a ce que le dossier contient ; sinon, chaque artefact porte une marque, comme git marque les fichiers.

Un clic sur un artefact ouvre son fichier, ou son formulaire ; une page ou un template s'ouvre en aperçu.
Go to Code, le bouton sur la ligne d'un artefact, ouvre directement son code, sans passer par l'aperçu d'une page ; un artefact sans code y a Edit Settings, qui ouvre son formulaire.
+ sur un type ou sur un package écrit les fichiers d'un nouvel artefact.
Le bouton d'exécution d'un package, d'une suite ou d'un cas exécute ces tests.
Le clic droit propose Delete, Open in Builder et le reste.

La liste de la barre d'état

La liste qu'ouvre la barre d'état : le projet en cours d'exécution, d'autres espaces de travail, et les actions du projet, comme ouvrir le builder, l'arrêter, afficher les logs de l'API et réinitialiser la base de données.

Un clic sur l'élément de la barre d'état ouvre une seule liste pour tout ce qui concerne la connexion : le projet et s'il tourne, les autres espaces de travail à la même adresse, et les actions du projet. De là, vous ouvrez le builder du projet dans le navigateur, arrêtez le projet, lisez les logs de l'API ou réinitialisez sa base de données, ce qui jette les données et recharge le dépôt.

Les réglages dans des formulaires

Un Business Event ouvert dans son formulaire : nom, Business Entity, activé, et les moments où il se déclenche, comme BeforeCreate et BeforeUpdate.

Les réglages d'un artefact sont le fichier JSON à côté de son code, et ouvrir ce fichier ouvre un formulaire. Le formulaire d'un Business Event contient son nom, son Business Entity, s'il est activé, les moments où il se déclenche, sa condition et ses actions. Chaque modification dans un formulaire est écrite dans le fichier, donc git la voit comme n'importe quelle autre modification ; Edit as JSON ouvre le texte à la place. Les Script Modules, les pages, les PDF Templates et les Frontend Templates, les planifications et les cas de test ont leurs propres formulaires.

Business Entities

L'éditeur d'entité pour Service Job : table maître, colonne de libellé, jointures vers les tables des clients et des techniciens, et les colonnes.

Un Business Entity s'ouvre dans l'éditeur d'entité : sa table maître et sa colonne de libellé, ses jointures (depuis quelle table, de quel type, vers quelle table et quelle colonne, et combien de lignes donne une jointure), et ses colonnes dans l'ordre, chacune avec un agrégat et l'entité dont une clé tire ses libellés. Les tables et les colonnes sont choisies dans la base de données du projet, donc un nom qui n'existe pas ne peut pas être choisi.

Le C# avec le propre compilateur du projet

La complétion dans un script après Db.Serv, qui propose les ensembles typés ServiceCustomer, ServiceJob et ServiceTechnician.

Les scripts sont compilés par le projet lui-même, avec les mêmes variables globales et le même modèle de données que ceux avec lesquels ils s'exécutent. Chaque Business Entity est un ensemble typé sur Db, donc la complétion propose ServiceJob et les autres ensembles, puis, après le point, leurs colonnes.

Un survol de Db.ServiceJob qui montre son type et la note indiquant qu'il s'agit du Business Entity Service Job, les lignes de service_job.

Survoler un nom affiche son type et sa documentation, ici que Db.ServiceJob est le Business Entity Service Job, les lignes de service_job. Les informations sur les paramètres apparaissent pendant que vous tapez un appel, et les erreurs sont soulignées au fil de la frappe.

Go to Definition sur ServiceJob, qui ouvre la classe WorkspaceDb générée, en lecture seule, avec un ensemble typé par Business Entity.

Go to Definition (F12) sur un ensemble typé ouvre le modèle de données que le projet a généré à partir de ses tables et de ses Business Entities, en lecture seule. Sur la méthode d'un Script Module, il ouvre le script de ce module, et sur un paramètre les réglages qui le déclarent.

Les types dont plusieurs scripts ont besoin se trouvent dans des fichiers C# partagés sous le dossier code/ d'un package, et Shared code dans la vue Workspace liste ceux d'un espace de travail. Ils bénéficient des mêmes fonctionnalités, et F12 sur un type partagé dans un script ouvre le fichier qui le déclare.

Tester un Script Module

Le code de GetPlannerWeek à gauche et son panneau de test à droite : le paramètre week_start, Run test, Passed et la semaine renvoyée.

Test, le lien au-dessus du code d'un Script Module, ouvre à côté un panneau qui exécute le module à blanc, avec le code tel que l'éditeur l'a. Il demande les paramètres et les retient, indique s'il a réussi, combien de temps il a pris, ce qu'il a renvoyé et ce qu'il a écrit dans le log, et liste les écritures, mails et notifications qu'il a enregistrés au lieu de les faire. Un échec montre son erreur avec un bouton vers la ligne. Show the SQL it ran envoie ses instructions au panneau SQL Trace.

Le code des pages et sa référence

Le code d'une page à gauche et la référence What page code can use à droite, qui commence par backend.

Le code des pages et des templates est vérifié par rapport à ce dont il dispose à l'exécution : backend, pageContext, React, chaque composant MUI et un type de ligne par Business Entity. What page code can use, le lien au-dessus du code, ouvre la liste complète à côté, chaque variable globale avec ce qu'elle fait et un exemple.

Le code des pages peut importer : les propres fichiers d'une page, à côté de ses vues, sous la forme ./OrderRow, et les modules partagés du dossier code/ d'un package sous la forme @/components/StatusChip. Les imports sont typés, F12 les suit, et un renommage modifie chaque fichier qui utilise le nom.

Tables

Un fichier de table s'ouvre dans l'éditeur de tables : sa colonne de libellé, si elle a des colonnes d'audit, et une ligne par colonne avec son nom, son type, sa longueur, sa clé, si elle peut être vide, si elle est unique, sa valeur par défaut et la table qu'elle référence. Les index suivent en dessous. Chaque modification est écrite dans le fichier, packages/<package>/tables/<table>.json.

Le diagramme de base de données montrant service_job avec ses clés étrangères vers service_customer et service_technician, filtré sur le package Service Planner.

Open Database Diagram dessine les tables et leurs clés étrangères. Choisissez un package pour ne voir que ses tables, Overview les fait toutes tenir dans la fenêtre, + Table en commence une nouvelle, et Review and publish ouvre la revue du schéma. Double-cliquez sur une table pour la modifier ; faites glisser son en-tête pour la déplacer, ce qui est enregistré dans le layout.json du package.

Migrations

La revue du schéma : la table modifiée service_job, un plan avec une opération sûre qui ajoute une colonne, son SQL, la vérification des scripts typés et les scripts de pré- et post-déploiement.

Add Migration compare les fichiers de table avec la base de données du projet et affiche la revue : quelles tables changent, chaque opération avec son risque (ici safe), le SQL exact, si chaque script typé compile encore avec les tables modifiées, et de la place pour du SQL à exécuter avant et après la modification.

La vue Deployments avec une migration en attente au-dessus du déploiement qui a créé les tables du dépôt.

Une fois ajoutée, la migration attend dans la vue Deployments comme un déploiement en attente, nommé d'après ce qu'il modifie, jusqu'à ce que Deploy l'exécute. La vue est tout l'historique de la base de données, du plus récent au plus ancien ; Roll Back to Here sur un déploiement antérieur planifie le retour des tables à cet état.

Console SQL

Une requête SQL qui joint les interventions et les techniciens à gauche, et ses 13 lignes dans le panneau SQL Results à droite.

New SQL Query ouvre un éditeur sur la base de données du projet, avec la complétion des tables et des colonnes. Run Query (Ctrl+Enter) exécute la sélection ou le fichier entier, instruction par instruction, et les résultats s'ouvrent à côté, chacun copiable en CSV. Une erreur indique quelle instruction a échoué et où, et les instructions qui la précèdent restent exécutées.

Explain Query et Explain Analyze Query (Ctrl+Alt+Enter) ouvrent le plan de l'instruction dans Query Plan : chaque étape avec sa part du temps, les lignes trouvées face aux lignes attendues, et une note là où une étape lit bien plus qu'elle ne garde. Analyze exécute l'instruction puis l'annule.

Trace SQL

Trace SQL, sur un Script Module ou un Business Entity dans la vue Workspace ou sur son fichier, exécute le module (à blanc, sauf si vous en décidez autrement) ou lit l'entité comme le fait une grille, et liste dans SQL Trace ce qui a été envoyé à la base de données : chaque instruction avec ses valeurs, sa durée et le code qui l'a envoyée, dans l'ordre ou avec les instructions identiques regroupées, où une requête envoyée une fois par ligne saute aux yeux. Chaque instruction peut montrer son plan, s'ouvrir en SQL ou se copier avec ses valeurs en place. Dans la vue Testing, Run with SQL Trace fait de même pour les cas de test.

Tests

La vue Workspace avec les cas de test de Service Planner, chacun avec une coche verte après une exécution.

Run Tests exécute les tests de tous les packages, ou ceux d'un package, d'une suite ou d'un cas depuis leur propre bouton d'exécution. Chaque cas s'exécute dans une base de données sandbox qui lui est propre et affiche son résultat dans l'arborescence quand il se termine ; un clic sur un cas exécuté ouvre ce qu'il a vérifié, l'attendu face au réel, et ce qu'il a affiché. La vue Testing liste les mêmes cas.

Event Log

La vue Event Log montre ce qui s'est exécuté dans le projet, regroupé par type, avec sur chaque groupe les échecs et le total du dernier jour. Ici, ce sont les Business Events que les tests ont déclenchés : la plupart ont réussi, et ceux dont un test attendait qu'ils refusent un enregistrement ont échoué. Un échec est compté sur le badge de la vue et annoncé au moment où il se produit. Un clic sur une entrée ouvre tout ce qu'elle a enregistré, et Open Artifact mène au script dans lequel l'échec s'est produit, sur la ligne en échec.

Data API

La vue Data API liste les endpoints du projet, chacun avec ses versions et leur statut, ainsi que ses API clients. Les boutons de son titre ajoutent un endpoint ou un API client et ouvrent le document OpenAPI de tout ce que vous pouvez appeler. Un clic sur un endpoint l'ouvre, depuis le dossier quand un package l'y contient ; un clic sur une version servie l'essaie.

Le formulaire de l'endpoint Customers : sa Business Entity, son nom et sa route, qui peut l'appeler, et la version 2 avec son statut, son sunset, sa taille de page, ses opérations et un tableau de champs.

Le formulaire d'un endpoint modifie api/customers.json : l'entité qu'il expose, son nom et sa route, et chaque version avec son statut, son jour de sunset, sa taille de page, ses opérations et ses champs. Le tableau des champs prend la colonne de chaque champ dans l'entité et signale quand une colonne ne peut pas être écrite. Une version publiée l'indique, puisqu'elle ne peut que grandir ; + New version copie celle affichée, pour le changement qui la casserait. Qui peut appeler l'endpoint ne figure pas dans le fichier : Edit access in the workspace ouvre ses autorisations dans le projet.

Le formulaire de l'endpoint Planner week, qui appelle un Script Module : la version 1, active, appelle GetPlannerWeek en GET et transmet un paramètre, weekStart, au week_start du module, obligatoire et décrit.

Un endpoint peut appeler un Script Module au lieu d'exposer une entité. Chaque version nomme le module et sa méthode, POST avec les paramètres dans un corps JSON ou GET avec eux dans la chaîne de requête, et liste les paramètres que les appelants envoient : un nom public sur un paramètre du module, son type, s'il est obligatoire, et une description. Add remaining parameters ajoute les autres paramètres du module, et le formulaire signale un paramètre dont le module a besoin mais que la version ne transmet pas. Une fois publiée, une version garde son module et sa méthode, et ne gagne que des paramètres optionnels. Un module marqué admin only n'est appelé que par les admins et les owners, et le formulaire le dit.

Try Customers : la version 2 et la requête GET /, une query, l'envoi en tant qu'utilisateur connecté, la commande curl, et la réponse, 200 avec les clients en JSON.

Try It envoie de vraies requêtes à une version : une liste avec une query, un get, ou un create, un update ou un delete avec un corps d'exemple tiré des champs modifiables de la version ; sur un endpoint qui appelle un Script Module, l'appel avec des paramètres d'exemple. Envoyez-les en votre nom, avec le SQL exécuté si vous le souhaitez, ou avec la clé d'un API client, pour voir ce que ce client a le droit de faire. La réponse s'affiche telle qu'elle est arrivée, avec son statut, ses en-têtes de version et son corps, et Copy as curl donne la même requête avec un espace réservé à la place du secret.

Un API client s'ouvre dans un formulaire à lui : son nom, ses rôles, son expiration et s'il est activé. En créer un, ou Rotate Key sur un client existant, affiche sa clé une seule fois, avec une commande pour vérifier qu'elle fonctionne.

Les réglages de l'espace de travail

Les réglages propres à l'espace de travail sont des fichiers dans workspace/ et s'ouvrent aussi dans des formulaires. Le formulaire de branding montre une barre d'aperçu aux couleurs de l'application, le nom de l'application, le logo et sa taille, et les couleurs ; le formulaire des layouts d'application contient l'en-tête et la barre latérale de l'application publiée. Le projet les prend en compte quand vous enregistrez.

Pour aller plus loin

Archestack dans VS Code couvre l'installation de l'extension, le démarrage d'un projet et le travail en équipe, et Stratégie de déploiement la façon dont le dépôt atteint le test, la recette et la production.