La extensión de VS Code en detalle
Un recorrido por todas las pantallas de la extensión de Archestack para VS Code: qué muestra cada una, qué hace y cómo llegar a ella. Archestack en VS Code es la guía para trabajar con ella; esta página es el detalle. Las capturas muestran Service Planner, una pequeña aplicación para planificar trabajos de servicio y asignarlos a técnicos, que se ejecuta como proyecto en la máquina.
El proyecto, su código y la aplicación, uno junto a otro
La vista Archestack de la barra de actividad enumera los paquetes del
repositorio y lo que contienen. El editor tiene el código de una página, y Open Preview
to the Side renderiza esa página a su lado con los datos del propio proyecto, siguiendo
cada edición, guardada o no. La página se dibuja dentro del app layout que la aplicación
publicada pone a su alrededor. La barra de estado muestra a qué está conectada la ventana: aquí,
local, el proyecto.
La barra de herramientas de la vista previa elige en qué y sobre qué se dibuja la página. Layout es el app layout a su alrededor: Automatic nombra el que usaría la aplicación publicada y dice por qué al pasar el ratón, o elige otro layout, o ninguno. La lista de dispositivos tiene teléfonos, tabletas y escritorios a su tamaño real, además de un tamaño propio; un teléfono o una tableta gira a horizontal, y el zoom encaja el dispositivo en el panel o lo muestra a un porcentaje. La aplicación mide el ancho del dispositivo, así que la página toma la forma que tiene en ese dispositivo. La siguiente vista previa se abre en el último dispositivo que elegiste.
La vista Workspace
El primer nodo es el propio espacio de trabajo, con su dirección. Debajo, cada paquete del repositorio enumera sus artefactos por tipo, cada uno con un recuento: script modules, business events, business entities, páginas, test suites, casos de prueba y tablas. In sync después de la versión de un paquete indica que el proyecto tiene lo que tiene la carpeta; si no, cada artefacto lleva una marca, igual que git marca los archivos.
- Al hacer clic en un artefacto se abre su archivo, o su formulario; una página o una plantilla se abre como vista previa.
- Go to Code, el botón en la fila de un artefacto, abre directamente su código, sin pasar por la vista previa de una página; un artefacto sin código tiene ahí Edit Settings, que abre su formulario.
- + en un tipo o en un paquete escribe los archivos de un artefacto nuevo.
- El botón de ejecutar de un paquete, una suite o un caso ejecuta esas pruebas.
- El clic derecho ofrece Delete, Open in Builder y los demás comandos.
La lista de la barra de estado
Al hacer clic en el elemento de la barra de estado se abre una sola lista para todo lo relacionado con la conexión: el proyecto y si está en marcha, los demás espacios de trabajo de la misma dirección y las acciones del proyecto. Desde aquí abres el builder del proyecto en el navegador, detienes el proyecto, lees los logs de la API o restableces su base de datos, lo que descarta los datos y vuelve a cargar el repositorio.
Ajustes en formularios
Los ajustes de un artefacto son el archivo JSON que hay junto a su código, y al abrir ese archivo se abre un formulario. El formulario de un business event contiene su nombre, su business entity, si está activado, los momentos en que se dispara, su condición y sus acciones. Cada cambio en un formulario se escribe en el archivo, así que git lo ve como cualquier otra edición; Edit as JSON abre el texto en su lugar. Los script modules, las páginas, las plantillas PDF y las frontend templates, las programaciones y los casos de prueba tienen formularios propios.
Business entities
Una business entity se abre en el editor de entidades: su tabla maestra y su columna de etiqueta, sus joins (desde qué tabla, de qué tipo, hacia qué tabla y columna, y cuántas filas da un join), y sus columnas en orden, cada una con un agregado y la entidad de la que una clave toma sus etiquetas. Las tablas y las columnas se eligen de la base de datos del proyecto, así que no se puede elegir un nombre que no existe.
C# con el propio compilador del proyecto
Los scripts los compila el propio proyecto, con los mismos globales y el mismo modelo de datos con
los que se ejecutan. Cada business entity es un conjunto tipado sobre Db, así que el
autocompletado ofrece ServiceJob y los demás conjuntos y, después del punto, sus
columnas.
Al pasar el ratón sobre un nombre se ven su tipo y su documentación; aquí, que
Db.ServiceJob es la business entity Service Job, las filas de
service_job. La información de parámetros aparece mientras escribes una llamada, y
los errores se subrayan mientras escribes.
Go to Definition (F12) sobre un conjunto tipado abre, en solo lectura, el modelo de datos que el proyecto generó a partir de sus tablas y business entities. Sobre el método de un script module abre el script de ese módulo, y sobre un parámetro los ajustes que lo declaran.
Los tipos que necesitan varios scripts viven en archivos de C# compartidos, en la carpeta
code/ de un paquete, y Shared code, en la vista Workspace, enumera los
de un espacio de trabajo. Tienen las mismas funciones, y F12 sobre un tipo compartido en un script
abre el archivo que lo declara.
Probar un script module
Test, el enlace encima del código de un script module, abre a su lado un panel que ejecuta el módulo en modo de simulación, con el código tal como lo tiene el editor. Pide los parámetros y los recuerda, muestra si ha pasado, cuánto ha tardado, qué ha devuelto y qué ha escrito en el log, y lista las escrituras, correos y notificaciones que registró en lugar de hacerlos. Un fallo muestra su error con un botón que lleva a la línea. Show the SQL it ran envía sus sentencias al panel SQL Trace.
El código de páginas y su referencia
El código de páginas y plantillas se comprueba contra lo que tiene cuando se ejecuta:
backend, pageContext, React, todos los componentes de MUI y un tipo de
fila por cada business entity. What page code can use, el enlace que hay encima
del código, abre a su lado la lista completa, cada global con lo que hace y un ejemplo.
El código de páginas puede importar: los archivos propios de una página, junto a sus vistas, como
./OrderRow, y los módulos compartidos de la carpeta code/ de un paquete,
como @/components/StatusChip. Las importaciones están tipadas, F12 las sigue, y un
renombrado cambia todos los archivos que usan el nombre.
Tablas
Un archivo de tabla se abre en el editor de tablas: su columna de etiqueta, si tiene columnas de
auditoría, y una fila por columna con su nombre, su tipo, su longitud, su clave, si puede quedar
vacía, si es única, su valor por defecto y la tabla a la que hace referencia. Debajo vienen los
índices. Cada cambio se escribe en el archivo,
packages/<package>/tables/<table>.json.
Open Database Diagram dibuja las tablas y sus claves foráneas. Elige un paquete
para ver solo sus tablas; Overview las encaja todas en la ventana,
+ Table empieza una nueva y Review and publish abre la revisión
del esquema. Haz doble clic en una tabla para editarla; arrastra su cabecera para moverla, lo que
se guarda en el layout.json del paquete.
Migraciones
Add Migration compara los archivos de tabla con la base de datos del proyecto y muestra la revisión: qué tablas cambian, cada operación con su riesgo (aquí, safe), el SQL exacto, si cada script tipado sigue compilando con las tablas cambiadas, y espacio para SQL que se ejecuta antes y después del cambio.
Una vez añadida, la migración espera en la vista Deployments como un despliegue pendiente, con un nombre según lo que cambia, hasta que Deploy la ejecuta. La vista es todo el historial de la base de datos, del más reciente al más antiguo; Roll Back to Here sobre uno anterior planifica cómo devolver las tablas a ese punto.
Consola SQL
New SQL Query abre un editor sobre la base de datos del proyecto, con autocompletado de tablas y columnas. Run Query (Ctrl+Enter) ejecuta la selección o el archivo entero, sentencia a sentencia, y los resultados se abren al lado, cada uno copiable como CSV. Un error indica qué sentencia falló y dónde, y las sentencias anteriores quedan hechas.
Explain Query y Explain Analyze Query (Ctrl+Alt+Enter) abren el plan de la sentencia en Query Plan: cada paso con su parte del tiempo, las filas encontradas frente a las esperadas, y una nota donde un paso lee mucho más de lo que conserva. Analyze ejecuta la sentencia y la revierte.
Traza SQL
Trace SQL, sobre un script module o una business entity en la vista Workspace o sobre su archivo, ejecuta el módulo (en modo de simulación salvo que elijas otra cosa) o lee la entidad como lo hace una rejilla, y muestra en SQL Trace lo que envió a la base de datos: cada sentencia con sus valores, su tiempo y el código que la envió, en orden o con las sentencias iguales juntas, donde destaca una consulta enviada una vez por fila. De cada sentencia se puede ver el plan, y se puede abrir como SQL o copiar con sus valores en su sitio. En la vista Testing, Run with SQL Trace hace lo mismo con los casos de prueba.
Pruebas
Run Tests ejecuta las pruebas de todos los paquetes, o las de un paquete, una suite o un caso desde su propio botón de ejecutar. Cada caso se ejecuta en una base de datos sandbox propia y muestra su resultado en el árbol cuando termina; al hacer clic en un caso que se ha ejecutado se abre lo que comprobó, lo esperado frente a lo real, y lo que imprimió. La vista Testing muestra los mismos casos.
Event Log
La vista Event Log muestra lo que se ejecutó en el proyecto, agrupado por tipo, con los fallos y el total del último día en cada grupo. Aquí, los business events que dispararon las pruebas: la mayoría salieron bien, y fallaron los que una prueba esperaba que rechazaran un guardado. Un fallo se cuenta en la insignia de la vista y se anuncia en el momento. Al hacer clic en una entrada se abre todo lo que registró, y Open Artifact lleva al script en el que falló, en la línea del fallo.
Data API
La vista Data API lista los endpoints del proyecto, cada uno con sus versiones y su estado, y sus API clients. Los botones de su título añaden un endpoint o un API client y abren el documento OpenAPI de todo lo que puedes llamar. Un clic en un endpoint lo abre, desde la carpeta cuando un package de ella lo contiene; un clic en una versión que se sirve la prueba.
El formulario de un endpoint edita api/customers.json: la entidad que sirve, su nombre
y su ruta, y cada versión con su estado, su día de sunset, el tamaño de página, las operaciones y
los campos. La tabla de campos toma la columna de cada campo de la entidad y avisa cuando una
columna no se puede escribir. Una versión publicada lo indica, porque solo puede crecer;
+ New version copia la que se muestra, para el cambio que la rompería. Quién puede
llamar al endpoint no está en el archivo: Edit access in the workspace abre sus
permisos en el proyecto.
Un endpoint puede llamar a un script module en lugar de servir una entidad. Cada versión nombra el módulo y su método, POST con los parámetros en un cuerpo JSON o GET con ellos en la cadena de consulta, y enumera los parámetros que envían quienes llaman: un nombre público sobre un parámetro del módulo, su tipo, si es obligatorio y una descripción. Add remaining parameters añade los demás parámetros del módulo, y el formulario señala un parámetro que el módulo necesita y la versión no pasa. Una vez publicada, una versión conserva su módulo y su método, y solo gana parámetros opcionales. A un módulo marcado como admin only solo lo llaman los admins y los owners, y el formulario lo dice.
Try It envía peticiones reales a una versión: una lista con una query, un get, o un create, update o delete con un cuerpo de ejemplo hecho con los campos que se pueden escribir en la versión; en un endpoint que llama a un script module, la llamada con parámetros de ejemplo. Envíalas como tú, con el SQL que ejecutaron si quieres, o con la clave de un API client, para ver qué tiene permitido ese cliente. La respuesta aparece tal como llegó, con su estado, sus cabeceras de versión y su cuerpo, y Copy as curl da la misma petición con un marcador donde va el secreto.
Un API client se abre en un formulario propio: su nombre, sus roles, su caducidad y si está activo. Crear uno, o Rotate Key en uno existente, muestra su clave una sola vez, con un comando para comprobar que funciona.
Ajustes del espacio de trabajo
Los ajustes propios del espacio de trabajo son archivos en workspace/ y también se
abren en formularios. El formulario de branding muestra una barra de vista previa con los colores
de la aplicación, el nombre de la aplicación, el logotipo y su tamaño, y los colores; el
formulario de los app layouts contiene la cabecera y la barra lateral de la aplicación publicada.
El proyecto los recoge cuando guardas.
Hacia dónde va esto a continuación
Archestack en VS Code trata la instalación de la extensión, cómo arrancar un proyecto y el trabajo en equipo, y Estrategia de despliegue, cómo llega el repositorio a pruebas, aceptación y producción.