A extensão do VS Code em detalhe

Uma visita a todos os ecrãs da extensão do Archestack para o VS Code: o que cada um mostra, o que faz e como lá chegar. Archestack no VS Code é o guia para trabalhar com ela; esta página é o detalhe. As capturas de ecrã mostram o Service Planner, uma pequena aplicação para distribuir trabalhos de assistência pelos técnicos, a correr como projeto na máquina.

O projeto, o seu código e a aplicação lado a lado

O VS Code com a vista Archestack à esquerda, o código de uma página ao centro e a página a correr, um quadro de planeamento com trabalhos e técnicos, à direita.

A vista Archestack na barra de atividades lista os packages do repositório e o que contêm. O editor tem o código de uma página, e Open Preview to the Side renderiza essa página ao lado com os dados do próprio projeto, acompanhando cada edição, guardada ou não. A página é desenhada dentro do app layout que a aplicação publicada coloca à sua volta. A barra de estado mostra a que é que a janela está ligada: aqui local, o projeto.

A página Customers em pré-visualização num iPhone 15 a 55%, dentro do cabeçalho do layout Service desk, com as escolhas de layout, dispositivo e zoom por cima.

A barra de ferramentas da pré-visualização escolhe em quê e sobre quê a página é desenhada. Layout é o app layout à sua volta: Automatic indica o que a aplicação publicada usaria e diz porquê ao passar o rato, ou escolha outro layout, ou nenhum. A lista de dispositivos tem telemóveis, tablets e computadores ao tamanho real, mais um tamanho à sua escolha; um telemóvel ou tablet roda para a horizontal, e o zoom ajusta o dispositivo ao painel ou mostra-o numa percentagem. A aplicação mede a largura do dispositivo, por isso a página assume a forma que tem nesse dispositivo. A pré-visualização seguinte abre no último dispositivo que escolheu.

A vista Workspace

O primeiro nó é o próprio espaço de trabalho, com o seu endereço. Por baixo dele, cada package do repositório lista os seus artefactos por tipo, cada um com uma contagem: Script Modules, Business Events, Business Entities, páginas, test suites, casos de teste e tabelas. In sync depois da versão de um package diz que o projeto tem o que a pasta tem; caso contrário, cada artefacto leva uma marca, tal como o git marca os ficheiros.

Clicar num artefacto abre o seu ficheiro, ou o seu formulário; uma página ou um template abre como pré-visualização.
Go to Code, o botão na linha de um artefacto, abre logo o seu código, sem passar pela pré-visualização de uma página; um artefacto sem código tem aí Edit Settings, que abre o seu formulário.
+ num tipo ou num package escreve os ficheiros de um novo artefacto.
O botão de execução num package, numa suite ou num caso corre esses testes.
Clicar com o botão direito oferece Delete, Open in Builder e o resto.

A lista da barra de estado

A lista que a barra de estado abre: o projeto a correr, outros espaços de trabalho e as ações do projeto, como abrir o builder, parar, mostrar os logs da API e fazer reset da base de dados.

Clicar no item da barra de estado abre uma única lista para tudo o que diz respeito à ligação: o projeto e se está a correr, os outros espaços de trabalho no mesmo endereço e as ações do projeto. A partir daqui abre o builder do projeto no browser, para o projeto, lê os logs da API ou faz reset da sua base de dados, o que deita fora os dados e carrega o repositório de novo.

Definições em formulários

Um Business Event aberto no seu formulário: nome, Business Entity, ativo, e os momentos em que dispara, como BeforeCreate e BeforeUpdate.

As definições de um artefacto são o ficheiro JSON ao lado do seu código, e abrir esse ficheiro abre um formulário. O formulário de um Business Event tem o nome, a Business Entity, se está ativo, os momentos em que dispara, a condição e as ações. Cada alteração num formulário é escrita no ficheiro, por isso o git vê-a como qualquer outra edição; Edit as JSON abre o texto em vez disso. Os Script Modules, as páginas, os PDF Templates e Frontend Templates, os agendamentos e os casos de teste têm formulários próprios.

Business Entities

O editor de entidades para Service Job: master table, coluna de etiqueta, joins às tabelas de clientes e de técnicos, e as colunas.

Uma Business Entity abre no editor de entidades: a sua master table e a coluna de etiqueta, os seus joins (a partir de que tabela, de que tipo, para que tabela e coluna, e quantas linhas um join dá) e as suas colunas por ordem, cada uma com uma agregação e a entidade de onde uma chave tira as suas etiquetas. As tabelas e as colunas são escolhidas a partir da base de dados do projeto, por isso não é possível escolher um nome que não existe.

C# com o próprio compilador do projeto

Autocompletar num script depois de Db.Serv, a oferecer os conjuntos tipados ServiceCustomer, ServiceJob e ServiceTechnician.

Os scripts são compilados pelo próprio projeto, contra os mesmos globais e o mesmo modelo de dados com que correm. Cada Business Entity é um conjunto tipado em Db, por isso o autocompletar oferece ServiceJob e os outros conjuntos e, depois do ponto, as suas colunas.

Informação ao passar o rato sobre Db.ServiceJob, a mostrar o seu tipo e a nota de que é a Business Entity Service Job, as linhas de service_job.

Passar o rato sobre um nome mostra o seu tipo e a sua documentação, aqui que Db.ServiceJob é a Business Entity Service Job, as linhas de service_job. A informação sobre os parâmetros aparece enquanto escreve uma chamada, e os erros são sublinhados enquanto escreve.

Go to Definition em ServiceJob a abrir a classe WorkspaceDb gerada, só de leitura, com um conjunto tipado por cada Business Entity.

Go to Definition (F12) num conjunto tipado abre o modelo de dados que o projeto gerou a partir das suas tabelas e Business Entities, só de leitura. No método de um Script Module abre o script desse módulo, e num parâmetro as definições que o declaram.

Os tipos de que mais do que um script precisa ficam em ficheiros C# partilhados na pasta code/ de um package, e Shared code na vista Workspace lista os de um espaço de trabalho. Têm as mesmas funcionalidades, e F12 num tipo partilhado, dentro de um script, abre o ficheiro que o declara.

Testar um Script Module

O código de GetPlannerWeek à esquerda e o seu painel de teste à direita: o parâmetro week_start, Run test, Passed e a semana que devolveu.

Test, a ligação por cima do código de um Script Module, abre ao lado um painel que corre o módulo em modo de simulação, com o código tal como o editor o tem. Pede os parâmetros e memoriza-os, mostra se passou, quanto tempo demorou, o que devolveu e o que escreveu no log, e lista as escritas, emails e notificações que registou em vez de fazer. Uma falha mostra o seu erro com um botão que leva à linha. Show the SQL it ran envia as suas instruções para o painel SQL Trace.

O código de páginas e a sua referência

O código de uma página à esquerda e a referência What page code can use à direita, a começar por backend.

O código de páginas e de templates é verificado contra aquilo que tem quando corre: backend, pageContext, o React, todos os componentes MUI e um tipo de linha para cada Business Entity. What page code can use, a ligação por cima do código, abre a lista completa ao lado, todos os globais com o que fazem e um exemplo.

O código de páginas pode importar: os ficheiros próprios de uma página, ao lado das suas vistas, como ./OrderRow, e os módulos partilhados da pasta code/ de um package como @/components/StatusChip. Os imports são tipados, F12 segue-os, e renomear altera todos os ficheiros que usam o nome.

Tabelas

Um ficheiro de tabela abre no editor de tabelas: a sua coluna de etiqueta, se tem colunas de auditoria, e uma linha por coluna com o nome, o tipo, o comprimento, a chave, se pode ficar vazia, se é única, o valor por omissão e a tabela que referencia. Os índices vêm a seguir, por baixo. Cada alteração é escrita no ficheiro, packages/<package>/tables/<table>.json.

O diagrama da base de dados a mostrar service_job com chaves estrangeiras para service_customer e service_technician, filtrado pelo package Service Planner.

Open Database Diagram desenha as tabelas e as suas chaves estrangeiras. Escolha um package para ver só as suas tabelas; Overview encaixa-as todas na janela, + Table começa uma nova e Review and publish abre a revisão do esquema. Faça duplo clique numa tabela para a editar; arraste um cabeçalho para a mover, o que fica guardado no layout.json do package.

Migrações

A revisão do esquema: a tabela alterada service_job, um plano com uma operação safe que acrescenta uma coluna, o seu SQL, a verificação dos scripts tipados e os scripts de antes e depois do deployment.

Add Migration compara os ficheiros de tabela com a base de dados do projeto e mostra a revisão: que tabelas mudam, cada operação com o seu risco (aqui safe), o SQL exato, se todos os scripts tipados continuam a compilar contra as tabelas alteradas, e espaço para SQL a correr antes e depois da alteração.

A vista Deployments com uma migração pendente por cima do deployment que criou as tabelas do repositório.

Depois de acrescentada, a migração espera na vista Deployments como um deployment pendente, com um nome tirado do que altera, até que Deploy a corra. A vista é todo o histórico da base de dados, do mais recente para o mais antigo; Roll Back to Here num deployment anterior planeia levar as tabelas de volta a esse ponto.

Consola SQL

Uma query SQL que junta trabalhos e técnicos à esquerda, e as suas 13 linhas no painel SQL Results à direita.

New SQL Query abre um editor sobre a base de dados do projeto, com autocompletar de tabelas e colunas. Run Query (Ctrl+Enter) corre a seleção ou o ficheiro inteiro, instrução a instrução, e os resultados abrem ao lado, cada um copiável como CSV. Um erro diz que instrução falhou e onde, e as instruções anteriores ficam feitas.

Explain Query e Explain Analyze Query (Ctrl+Alt+Enter) abrem o plano da instrução em Query Plan: cada passo com a sua parte do tempo, linhas encontradas face às esperadas, e uma nota onde um passo lê muito mais do que mantém. O Analyze corre a instrução e reverte-a.

Rastreio de SQL

Trace SQL, num Script Module ou numa Business Entity na vista Workspace ou no seu ficheiro, corre o módulo (em modo de simulação, salvo se escolher outra coisa) ou lê a entidade como uma grelha a lê, e lista em SQL Trace o que enviou para a base de dados: cada instrução com os seus valores, o seu tempo e o código que a enviou, por ordem ou com as instruções iguais juntas, onde uma query enviada uma vez por linha salta à vista. Cada instrução pode mostrar o seu plano, abrir como SQL ou ser copiada com os valores no lugar. Na vista Testing, Run with SQL Trace faz o mesmo com os casos de teste.

Testes

A vista Workspace com os casos de teste do Service Planner, cada um com um visto verde depois de uma execução.

Run Tests corre os testes de todos os packages, ou os de um package, de uma suite ou de um caso a partir do seu próprio botão de execução. Cada caso corre numa base de dados sandbox própria e mostra o seu resultado na árvore quando termina; clicar num caso que já correu abre o que verificou, o esperado face ao obtido, e o que imprimiu. A vista Testing lista os mesmos casos.

Event Log

A vista Event Log mostra o que correu no projeto, agrupado por tipo, com as falhas e o total do último dia em cada grupo. Aqui estão os Business Events que os testes dispararam: a maioria foi bem-sucedida, e os que um teste esperava que recusassem uma gravação falharam. Uma falha é contada no contador da vista e anunciada quando acontece. Clicar numa entrada abre tudo o que ela registou, e Open Artifact vai para o script em que falhou, na linha que falhou.

Data API

A vista Data API lista os endpoints do projeto, cada um com as suas versões e o seu estado, e os seus API clients. Os botões no título acrescentam um endpoint ou um API client e abrem o documento OpenAPI de tudo o que pode chamar. Um clique num endpoint abre-o, a partir da pasta quando um package dela o contém; um clique numa versão servida experimenta-a.

O formulário do endpoint Customers: a sua Business Entity, nome e rota, quem o pode chamar, e a versão 2 com o estado, o sunset, o tamanho de página, as operações e uma tabela de campos.

O formulário de um endpoint edita api/customers.json: a entidade que serve, o nome e a rota, e cada versão com o estado, o dia de sunset, o tamanho de página, as operações e os campos. A tabela de campos vai buscar a coluna de cada campo à entidade e diz quando uma coluna não pode ser escrita. Uma versão publicada indica-o, porque só pode crescer; + New version copia a que está à vista, para a alteração que a partiria. Quem pode chamar o endpoint não está no ficheiro: Edit access in the workspace abre os acessos concedidos no projeto.

O formulário do endpoint Planner week, que chama um Script Module: a versão 1, ativa, chama GetPlannerWeek com GET e passa um parâmetro, weekStart, ao week_start do módulo, obrigatório e com descrição.

Um endpoint pode chamar um Script Module em vez de servir uma entidade. Cada versão indica o módulo e o seu método, POST com os parâmetros num corpo JSON ou GET com eles na query string, e lista os parâmetros que quem chama envia: um nome público sobre um parâmetro do módulo, o seu tipo, se é obrigatório e uma descrição. Add remaining parameters acrescenta os restantes parâmetros do módulo, e o formulário assinala um parâmetro de que o módulo precisa mas que a versão não passa. Depois de publicada, uma versão mantém o seu módulo e o seu método, e só ganha parâmetros opcionais. Um módulo marcado como admin only só é chamado por admins e owners, e o formulário di-lo.

Try Customers: a versão 2 e o pedido GET /, uma query, o envio como o utilizador com sessão iniciada, o comando curl e a resposta, 200 com os clientes em JSON.

Try It envia pedidos reais a uma versão: uma lista com uma query, um get, ou um create, update ou delete com um corpo de exemplo feito a partir dos campos graváveis da versão; num endpoint que chama um Script Module, a chamada com parâmetros de exemplo. Envie-os em seu nome, com o SQL executado se quiser, ou com a chave de um API client, para ver o que esse cliente pode fazer. A resposta aparece tal como chegou, com o estado, os cabeçalhos de versão e o corpo, e Copy as curl dá o mesmo pedido com um marcador onde vai o segredo.

Um API client abre num formulário próprio: o nome, as roles, a validade e se está ativo. Criar um, ou Rotate Key num existente, mostra a chave uma única vez, com um comando para confirmar que funciona.

Definições do espaço de trabalho

O formulário de branding: uma barra de pré-visualização na cor da aplicação com o seu nome, o nome da aplicação, se o nome aparece ao lado do logótipo, o tamanho do logótipo e o logótipo.

As definições do próprio espaço de trabalho são ficheiros em workspace/ e também abrem em formulários. O formulário de branding mostra uma barra de pré-visualização nas cores da aplicação, o nome da aplicação, o logótipo e o seu tamanho, e as cores; o formulário dos app layouts tem o cabeçalho e a barra lateral da aplicação publicada. O projeto recebe-os quando guarda.

Para onde seguir a partir daqui

Archestack no VS Code explica como instalar a extensão, arrancar um projeto e trabalhar em equipa, e Estratégia de deployment como o repositório chega a teste, aceitação e produção.