Rozszerzenie VS Code w szczegółach

Przegląd wszystkich ekranów rozszerzenia Archestack dla VS Code: co każdy z nich pokazuje, co robi i jak do niego dotrzeć. Archestack w VS Code to przewodnik po pracy z rozszerzeniem; ta strona opisuje szczegóły. Zrzuty ekranu pokazują Service Planner, małą aplikację do przydzielania zleceń serwisowych technikom, działającą jako projekt na maszynie.

Projekt, jego kod i aplikacja obok siebie

VS Code z widokiem Archestack po lewej, kodem strony pośrodku i działającą stroną, tablicą planowania ze zleceniami i technikami, po prawej.

Widok Archestack na pasku aktywności wymienia packages repozytorium i ich zawartość. W edytorze jest kod strony, a Open Preview to the Side renderuje tę stronę obok niego z danymi samego projektu i nadąża za każdą zmianą, zapisaną lub nie. Strona jest rysowana w układzie aplikacji, który opublikowana aplikacja wokół niej umieszcza. Pasek stanu pokazuje, z czym połączone jest okno: tutaj jest to local, czyli projekt.

Strona Customers w podglądzie na iPhonie 15 w skali 55%, w nagłówku układu Service desk, z wyborem układu, urządzenia i powiększenia nad nią.

Pasek narzędzi podglądu wybiera, w czym i na czym strona jest rysowana. Layout to układ aplikacji wokół niej: Automatic podaje układ, jakiego użyłaby opublikowana aplikacja, i po najechaniu mówi dlaczego, albo wybierz inny układ lub żaden. Lista urządzeń zawiera telefony, tablety i komputery w prawdziwym rozmiarze oraz własny rozmiar; telefon albo tablet obraca się poziomo, a zoom dopasowuje urządzenie do panelu albo pokazuje je w wybranym procencie. Aplikacja w środku mierzy szerokość urządzenia, więc strona przybiera postać, jaką ma na tym urządzeniu. Następny podgląd otwiera się na urządzeniu wybranym ostatnio.

Widok Workspace

Pierwszym węzłem jest sama przestrzeń robocza, z jej adresem. Pod nią każdy package repozytorium wymienia swoje artefakty według rodzaju, każdy rodzaj z liczbą elementów: Script Modules, Business Events, Business Entities, strony, zestawy testów, przypadki testowe i tabele. In sync po wersji package'a oznacza, że projekt ma to, co folder; w przeciwnym razie każdy artefakt ma oznaczenie, tak jak git oznacza pliki.

Kliknięcie artefaktu otwiera jego plik albo formularz; strona lub szablon otwiera się jako podgląd.
Go to Code, przycisk w wierszu artefaktu, od razu otwiera jego kod, z pominięciem podglądu strony; artefakt bez kodu ma w tym miejscu Edit Settings, które otwiera jego formularz.
+ przy rodzaju albo package'u zapisuje pliki nowego artefaktu.
Przycisk uruchamiania przy package'u, zestawie albo przypadku uruchamia te testy.
Kliknięcie prawym przyciskiem oferuje Delete, Open in Builder i resztę.

Lista z paska stanu

Lista, którą otwiera pasek stanu: działający projekt, inne przestrzenie robocze i akcje projektu, takie jak otwarcie buildera, zatrzymanie, pokazanie logów API i reset bazy danych.

Kliknięcie elementu na pasku stanu otwiera jedną listę na wszystko, co dotyczy połączenia: projekt i to, czy działa, inne przestrzenie robocze pod tym samym adresem oraz akcje projektu. Stąd otwierasz builder projektu w przeglądarce, zatrzymujesz projekt, czytasz logi API albo resetujesz jego bazę danych, co wyrzuca dane i wczytuje repozytorium od nowa.

Ustawienia w formularzach

Business Event otwarty w swoim formularzu: nazwa, Business Entity, włączony oraz momenty, w których się odpala, takie jak BeforeCreate i BeforeUpdate.

Ustawienia artefaktu to plik JSON obok jego kodu, a otwarcie tego pliku otwiera formularz. Formularz Business Event zawiera jego nazwę, jego Business Entity, informację, czy jest włączony, momenty, w których się odpala, warunek i akcje. Każda zmiana w formularzu jest zapisywana w pliku, więc git widzi ją jak każdą inną edycję; Edit as JSON otwiera zamiast tego tekst. Script Modules, strony, PDF Templates i Frontend Templates, harmonogramy i przypadki testowe mają własne formularze.

Business Entities

Edytor encji dla Service Job: master table, kolumna etykiety, joiny do tabel klientów i techników oraz kolumny.

Business Entity otwiera się w edytorze encji: jego master table i kolumna etykiety, joiny (z której tabeli, jakiego rodzaju, do której tabeli i kolumny oraz ile wierszy daje join) i kolumny w kolejności, każda z agregacją i encją, z której klucz bierze etykiety. Tabele i kolumny wybiera się z bazy danych projektu, więc nie da się wybrać nazwy, która nie istnieje.

C# z kompilatorem samego projektu

Podpowiedzi w skrypcie po Db.Serv, proponujące typowane zbiory ServiceCustomer, ServiceJob i ServiceTechnician.

Skrypty kompiluje sam projekt, z tymi samymi globalami i tym samym modelem danych, z którymi działają. Każde Business Entity jest typowanym zbiorem na Db, więc podpowiedzi proponują ServiceJob i pozostałe zbiory, a po kropce ich kolumny.

Opis po najechaniu kursorem na Db.ServiceJob, pokazujący jego typ i informację, że to Business Entity Service Job, czyli wiersze tabeli service_job.

Najechanie kursorem na nazwę pokazuje jej typ i dokumentację, tutaj to, że Db.ServiceJob to Business Entity Service Job, czyli wiersze tabeli service_job. Informacje o parametrach pojawiają się podczas pisania wywołania, a błędy są podkreślane na bieżąco, w trakcie pisania.

Go to Definition na ServiceJob otwierające wygenerowaną klasę WorkspaceDb, tylko do odczytu, z jednym typowanym zbiorem dla każdego Business Entity.

Go to Definition (F12) na typowanym zbiorze otwiera model danych, który projekt wygenerował ze swoich tabel i Business Entities, tylko do odczytu. Na metodzie Script Module otwiera skrypt tego modułu, a na parametrze ustawienia, które go deklarują.

Typy, których potrzebuje więcej niż jeden skrypt, znajdują się we współdzielonych plikach C# w folderze code/ package'a, a węzeł Shared code w widoku Workspace wymienia te, które ma przestrzeń robocza. Działają w nich te same funkcje, a F12 na typie współdzielonym w skrypcie otwiera plik, który go deklaruje.

Testowanie Script Module

Kod GetPlannerWeek po lewej i jego panel testu po prawej: parametr week_start, Run test, Passed i zwrócony tydzień.

Test, link nad kodem Script Module, otwiera obok panel, który uruchamia moduł w trybie próbnym, z kodem w takiej postaci, w jakiej ma go edytor. Pyta o parametry i je zapamiętuje, pokazuje, czy test przeszedł, ile trwał, co moduł zwrócił i co zapisał do logu, oraz wymienia zapisy, maile i powiadomienia, które zarejestrował zamiast je wykonać. Błąd pokazuje swój komunikat z przyciskiem prowadzącym do wiersza. Show the SQL it ran wysyła jego instrukcje do panelu SQL Trace.

Kod stron i jego dokumentacja

Kod strony po lewej i dokumentacja What page code can use po prawej, zaczynająca się od backend.

Kod stron i szablonów jest sprawdzany względem tego, co ma do dyspozycji, gdy działa: backend, pageContext, React, każdy komponent MUI i typ wiersza dla każdego Business Entity. What page code can use, link nad kodem, otwiera obok pełną listę: każdy global z opisem tego, co robi, i przykładem.

Kod strony może importować: własne pliki strony obok jej widoków jako ./OrderRow oraz moduły współdzielone z folderu code/ package'a jako @/components/StatusChip. Importy są typowane, F12 podąża za nimi, a zmiana nazwy zmienia każdy plik, który tej nazwy używa.

Tabele

Edytor tabel dla service_job: kolumna etykiety, kolumny audytowe i po jednym wierszu na kolumnę z nazwą, typem, długością, kluczem, pustą wartością, unikalnością, wartością domyślną i odwołaniem.

Plik tabeli otwiera się w edytorze tabel: jej kolumna etykiety, informacja, czy ma kolumny audytowe, i po jednym wierszu na kolumnę z nazwą, typem, długością, kluczem, informacją, czy może być pusta i czy jest unikalna, wartością domyślną i tabelą, do której się odwołuje. Poniżej są indeksy. Każda zmiana jest zapisywana w pliku packages/<package>/tables/<table>.json.

Diagram bazy danych pokazujący service_job z kluczami obcymi do service_customer i service_technician, przefiltrowany do package'a Service Planner.

Open Database Diagram rysuje tabele i ich klucze obce. Wybierz package, żeby widzieć tylko jego tabele; Overview mieści je wszystkie w oknie, + Table zakłada nową, a Review and publish otwiera przegląd schematu. Kliknij tabelę dwukrotnie, żeby ją edytować; przeciągnij nagłówek, żeby ją przesunąć, co zapisuje się w layout.json package'a.

Migracje

Przegląd schematu: zmieniona tabela service_job, plan z jedną operacją safe dodającą kolumnę, jej SQL, sprawdzenie typowanych skryptów oraz skrypty przed wdrożeniem i po nim.

Add Migration porównuje pliki tabel z bazą danych projektu i pokazuje przegląd: które tabele się zmieniają, każdą operację z jej ryzykiem (tutaj safe), dokładny SQL, informację, czy każdy typowany skrypt nadal kompiluje się ze zmienionymi tabelami, oraz miejsce na SQL do wykonania przed zmianą i po niej.

Widok Deployments z oczekującą migracją nad wdrożeniem, które utworzyło tabele repozytorium.

Dodana migracja czeka w widoku Deployments jako oczekujące wdrożenie, nazwane od tego, co zmienia, dopóki Deploy jej nie wykona. Widok to cała historia bazy danych, od najnowszych; Roll Back to Here na wcześniejszym wdrożeniu planuje przywrócenie tabel do tamtego stanu.

Konsola SQL

Zapytanie SQL łączące zlecenia z technikami po lewej i jego 13 wierszy w panelu SQL Results po prawej.

New SQL Query otwiera edytor na bazie danych projektu, z podpowiadaniem tabel i kolumn. Run Query (Ctrl+Enter) wykonuje zaznaczenie albo cały plik, instrukcja po instrukcji, a wyniki otwierają się obok, każdy do skopiowania jako CSV. Błąd mówi, która instrukcja się nie powiodła i w którym miejscu, a instrukcje przed nią pozostają wykonane.

Explain Query i Explain Analyze Query (Ctrl+Alt+Enter) otwierają plan instrukcji w Query Plan: każdy krok z jego udziałem w czasie, wiersze znalezione wobec oczekiwanych i uwagę tam, gdzie krok czyta dużo więcej, niż zostawia. Analyze wykonuje instrukcję i ją wycofuje.

Śledzenie SQL

Trace SQL, na Script Module lub Business Entity w widoku Workspace albo na jego pliku, uruchamia moduł (w trybie próbnym, chyba że wybierzesz inaczej) albo odczytuje encję tak, jak robi to siatka, i wymienia w SQL Trace to, co trafiło do bazy danych: każdą instrukcję z jej wartościami, czasem i kodem, który ją wysłał, po kolei albo z tymi samymi instrukcjami razem, gdzie zapytanie wysyłane raz na wiersz od razu rzuca się w oczy. Dla każdej instrukcji można zobaczyć plan, otworzyć ją jako SQL albo skopiować ze wstawionymi wartościami. W widoku Testing to samo dla przypadków testowych robi Run with SQL Trace.

Testy

Widok Workspace z przypadkami testowymi Service Planner, każdy z zielonym znacznikiem po uruchomieniu.

Run Tests uruchamia testy wszystkich packages albo, ich własnym przyciskiem uruchamiania, testy jednego package'a, zestawu lub przypadku. Każdy przypadek działa we własnym sandboxie, osobnej bazie danych, i po zakończeniu pokazuje swój wynik w drzewie; kliknięcie przypadku, który został uruchomiony, otwiera to, co sprawdził, wartość oczekiwaną wobec rzeczywistej, i to, co wypisał. Widok Testing wymienia te same przypadki.

Event Log

Widok Event Log pokazuje, co zostało uruchomione w projekcie, pogrupowane według rodzaju, z niepowodzeniami i łączną liczbą z ostatniej doby przy każdej grupie. Tutaj są to Business Events wywołane przez testy: większość zakończyła się powodzeniem, a te, po których test oczekiwał odrzucenia zapisu, zakończyły się niepowodzeniem. Niepowodzenie jest liczone na plakietce widoku i ogłaszane na bieżąco. Kliknięcie wpisu otwiera wszystko, co zarejestrował, a Open Artifact przechodzi do skryptu, w którym wystąpił błąd, na linii z błędem.

Data API

Widok Data API pokazuje endpointy projektu, każdy z jego wersjami i ich statusem, oraz jego klientów API. Przyciski w tytule dodają endpoint lub klienta API i otwierają dokument OpenAPI wszystkiego, co możesz wywołać. Kliknięcie endpointu otwiera go, z folderu, gdy zawiera go tam pakiet; kliknięcie obsługiwanej wersji ją wypróbowuje.

Formularz endpointu Customers: jego Business Entity, nazwa i trasa, kto może go wywoływać, oraz wersja 2 ze statusem, sunset, rozmiarem strony, operacjami i tabelą pól.

Formularz endpointu edytuje api/customers.json: encję, którą udostępnia, jego nazwę i trasę oraz każdą wersję ze statusem, dniem sunset, rozmiarem strony, operacjami i polami. Tabela pól bierze kolumnę każdego pola z encji i mówi, kiedy kolumny nie da się zapisać. Opublikowana wersja to zaznacza, bo może tylko rosnąć; + New version kopiuje wyświetlaną, na zmianę, która by ją zepsuła. Tego, kto może wywoływać endpoint, nie ma w pliku: Edit access in the workspace otwiera jego uprawnienia w projekcie.

Formularz endpointu Planner week, który wywołuje Script Module: wersja 1, aktywna, wywołuje GetPlannerWeek metodą GET i przekazuje jeden parametr, weekStart, do week_start modułu, wymagany i z opisem.

Endpoint może wywoływać Script Module zamiast udostępniać encję. Każda wersja wskazuje moduł i jego metodę, POST z parametrami w ciele JSON albo GET z parametrami w adresie URL, i wymienia parametry, które wysyłają wywołujący: publiczną nazwę nad parametrem modułu, jego typ, czy jest wymagany, i opis. Add remaining parameters dodaje pozostałe parametry modułu, a formularz oznacza parametr, którego moduł potrzebuje, a wersja go nie przekazuje. Po opublikowaniu wersja zachowuje swój moduł i metodę i zyskuje tylko parametry opcjonalne. Moduł oznaczony jako admin only wywołują tylko role admin i owner, i formularz o tym mówi.

Try Customers: wersja 2 i żądanie GET /, zapytanie, wysyłka jako zalogowany użytkownik, polecenie curl i odpowiedź 200 z klientami w JSON.

Try It wysyła prawdziwe żądania do wersji: listę z zapytaniem, get albo create, update lub delete z przykładowym body zbudowanym z zapisywalnych pól wersji, a na endpoincie, który wywołuje Script Module, wywołanie z przykładowymi parametrami. Wyślij je jako ty, jeśli chcesz z wykonanym SQL, albo z kluczem klienta API, żeby zobaczyć, na co ten klient ma pozwolenie. Odpowiedź pojawia się tak, jak przyszła, ze statusem, nagłówkami wersji i body, a Copy as curl daje to samo żądanie z symbolem zastępczym w miejscu sekretu.

Klient API otwiera się we własnym formularzu: nazwa, role, data wygaśnięcia i czy jest włączony. Utworzenie klienta, albo Rotate Key na istniejącym, pokazuje jego klucz jeden raz, z poleceniem, które sprawdza, że działa.

Ustawienia przestrzeni roboczej

Własne ustawienia przestrzeni roboczej są plikami w workspace/ i też otwierają się w formularzach. Formularz brandingu pokazuje pasek podglądu w kolorach aplikacji, nazwę aplikacji, logo i jego rozmiar oraz kolory; formularz układów aplikacji zawiera nagłówek i pasek boczny opublikowanej aplikacji. Projekt przejmuje je, gdy zapisujesz.

Co dalej

Strona Archestack w VS Code opisuje instalację rozszerzenia, uruchomienie projektu i pracę w zespole, a strona Strategia wdrożeń to, jak repozytorium trafia do środowisk testowego, akceptacyjnego i produkcyjnego.