dostapczuk/soneta-erp-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5605ad2915eb78cd5851635539c069c085f21c3a
soneta-erp-skills/soneta-programming/references/scan-workers.md
T
Marcin Wojas 67fcc9e996 Rozbudowa scan-workers.csx
2026-05-20 22:48:32 +02:00

14 KiB
Raw Blame History

Skanowanie workerów i extenderów z DLL (Roslyn MetadataReference)

Narzędzie do wylistowania wszystkich klas *Worker / *Extender zarejestrowanych w bibliotekach dodatków enova365 / Soneta przez atrybut WorkerAttribute (assembly). Czyta metadane skompilowanych bibliotek dodatku — nie wymaga źródeł.

Cel

W modelu Soneta workery i extendery są rejestrowane atrybutem assembly:

[assembly: Worker<NazwaWorker, TypDanych>]   // worker przypięty do typu danych
[assembly: Worker<NazwaExtender>]            // extender (bez typu danych)

Skrypt wyciąga wszystkie takie rejestracje, grupuje workery wg typu danych oraz wypisuje dla każdej klasy: parametry inicjowane z Context, property dostępne do bindowania/odczytu oraz pozycje menu Czynności (metody z atrybutem [Action]).

Używaj tego narzędzia, gdy:

  • robisz inwentaryzację rozszerzeń (workery / extendery) w dodatku innej osoby albo w całej aplikacji;
  • chcesz znaleźć dostępne workery dla danego typu danych zanim napiszesz form.xml ({Workers.<Alias>.<Property>});
  • sprawdzasz, jakie pozycje menu Czynności są dostępne na danym obiekcie;
  • weryfikujesz, że Twój nowy worker / extender został poprawnie zarejestrowany i jest widoczny dla platformy;
  • przygotowujesz raport dla code review (dodatek powinien mieć spójną listę workerów / akcji).

Po komplementarne dane — patrz scan-modules.csx (lista tabel) i scan-props.csx (pola tabeli).

Mechanizm

Skrypt używa Roslyn (Microsoft.CodeAnalysis.CSharp) i MetadataReference.CreateFromFile, czyli metadane są czytane bez ładowania IL do CLR — bezpiecznie, bez ryzyka konfliktów wersji.

Algorytm:

  1. Zbierz wszystkie *.dll z podanego katalogu, dodaj jako MetadataReference. Dołącz biblioteki runtime'u .NET (TPA — AppContext.GetData("TRUSTED_PLATFORM_ASSEMBLIES")) — bez tego Roslyn nie rozwiązuje atrybutów ramowych i zwraca pustą ConstructorArguments.
  2. Zbuduj CSharpCompilation z tymi referencjami.
  3. Dla każdego IAssemblySymbol przejdź po atrybutach assembly (asm.GetAttributes()) i odfiltruj te, których klasa to WorkerAttribute z namespace zaczynającego się od Soneta (chroni przed kolizją z atrybutami o tej samej nazwie z innych bibliotek).
  4. Wyciągnij dane rejestracji w zależności od wariantu atrybutu:
    • wariant generyczny ([Worker<TWorker>], [Worker<TWorker, TData>]) — typy biorę z AttributeClass.TypeArguments[0] (worker) oraz TypeArguments[1] (data, opcjonalnie). W metadanych klasa atrybutu ma backtick (WorkerAttribute\1, WorkerAttribute`2), ale INamedTypeSymbol.Namezwraca"WorkerAttribute"` bez backticka — wystarczy porównanie po nazwie.
    • wariant z parametrami ([Worker(typeof(TWorker), typeof(TData))]) — typy biorę z ConstructorArguments (TypedConstantKind.Type). Dodatkowy string z konstruktora lub NamedArgument Name traktuję jako alias bindingu (nadpisuje nazwę domyślną).
  5. Pogrupuj rejestracje wg DataType (workery) i posortuj alfabetycznie. Rejestracje bez DataType trafiają pod osobny klucz __extenders__ w JSON-ie.
  6. Dla każdej klasy workera / extendera odczytaj:
    • Alias bindingu (pole name) — jawnie podany Name z atrybutu albo nazwa klasy bez sufiksu Worker / pełna nazwa dla extendera. Binding na UI:
      • worker (lista): {Workers.<name>.<Property>}
      • extender (formularz): {new <name>.<Property>}
    • Konstruktor inicjowany z Context — parametry pierwszego publicznego konstruktora z parametrami trafiają do params z kind: "ctor".
    • Property z [Context] — publiczne instancyjne property z atrybutem ContextAttribute, inicjowane z Context — trafiają do params bez pola kind.
    • Pod-parametry typu ContextBase — gdy typ parametru dziedziczy z Soneta.Business.ContextBase, wpis dostaje zagnieżdżone props z publicznymi property tej klasy (pomija property samego ContextBase).
    • Property do bindowania / odczytu (props workera) — pozostałe publiczne instancyjne property z getterem (bez [Context]).
    • Akcje menu Czynności (actions) — publiczne instancyjne metody z atrybutem ActionAttribute; każda akcja ma name (tytuł), method (nazwa metody), result (typ wyniku, void dla void).
  7. Wypisz JSON na stdout (sformatowany, z polskimi znakami w czystej formie). Sekcje params / actions / props są pomijane, gdy są puste.

Wymagania

  • .NET SDK (8.0+)
  • dotnet-script: 
    dotnet tool install -g dotnet-script

Uruchomienie

dotnet script ~/.claude/skills/soneta-programming/scripts/scan-workers.csx \
    -- <KatalogDll> [<NazwaTypuDanych>] [--related]

Drugi argument (opcjonalny) ogranicza wynik do workerów przypiętych do wskazanego typu danych — pełne skanowanie bibliotek Soneta zwraca tysiące rejestracji, więc filtr jest praktycznie niezbędny w codziennej pracy. Dopasowanie po:

  • prostej nazwie klasy (np. DokumentHandlowy), albo
  • pełnej nazwie z namespace (np. Soneta.Handel.DokumentHandlowy).

Gdy filtr jest podany, extendery (rejestracje bez DataType) są pomijane — ich nie da się przypisać do typu danych.

Flaga --related — typy powiązane

--related rozszerza filtr o typy powiązane z podanym typem. Pozwala jednym wywołaniem zebrać workery z całej „rodziny" obiektu (rekord, tabela, historia), bez konieczności trzech osobnych uruchomień. Reguły rozpoznawania powiązań (po metadanych typu):

Typ wejściowy Powiązany typ Sposób odczytu
Klasa dziedzicząca z Soneta.Business.Row (np. Pracownik, DokumentHandlowy) Klasa tabeli (Pracownicy, DokHandlowe) property Table w klasie Row (lub klas bazowych)
Klasa dziedzicząca z Soneta.Business.Table (np. Pracownicy, DokHandlowe) Klasa rekordu (Pracownik, DokumentHandlowy) indekser this[int] — typ zwracany
Typ implementujący IRowWithHistory (np. Pracownik) Typ rekordu historycznego (PracHistoria) indekser this[Soneta.Types.Date] — typ zwracany

Reguły działają przechodnio i łącznie — np. dla Pracownik (Row + IRowWithHistory) zestaw to: Pracownik, Pracownicy, PracHistoria, PracHistorie (tabela historii dochodzi, bo PracHistoria to też Row z własną Table).

Dodatkowo dla każdego znalezionego Row (oryginał + history-Row) skrypt rozszerza zestaw o całą hierarchię:

  • klasy bazowe (baseClasses) — chodzi w górę po BaseType aż do object wyłącznie (włącznie z generowanym *Row z *Module, frameworkowymi Row / GuidedRow / RowBase);
  • klasy pochodne (derivedClasses) — przeszukuje wszystkie referencje w poszukiwaniu klas mających dany Row w łańcuchu BaseType (np. OsobaWspolpracujaca, PracownikFirmy, Wlasciciel dla Pracownik).

Tabele tego rozszerzenia nie dostają — zbędne, intermediate *Table rzadko bywa celem rejestracji workera.

Informacje o znalezionych typach skrypt wypisuje dwojako:

  1. W JSON pod kluczem scope (na stdout, sformatowane do parsowania):

    {
  "description": "Workery przypięte do typu `Pracownik` (Soneta)",
  "scope": {
    "primary": "Soneta.Kadry.Pracownik",
    "related": [
      { "type": "Soneta.Kadry.Pracownicy",    "kind": "table" },
      { "type": "Soneta.Kadry.PracHistoria",  "kind": "history-row" },
      { "type": "Soneta.Kadry.PracHistorie",  "kind": "history-table" }
    ],
    "baseClasses": [
      "Soneta.Kadry.KadryModule.PracownikRow",
      "Soneta.Business.GuidedRow",
      "Soneta.Business.Row",
      "Soneta.Kadry.KadryModule.PracHistoriaRow"
    ],
    "derivedClasses": [
      "Soneta.Kadry.OsobaWspolpracujaca",
      "Soneta.Kadry.PracownikFirmy",
      "Soneta.Kadry.Wlasciciel"
    ]
  },
  "Soneta.Kadry.Pracownik": [ /* … */ ],
  "Soneta.Kadry.Pracownicy": [ /* … */ ]
}

    Pole scope pojawia się wyłącznie w trybie --related (przy zwykłym filtrze JSON nie ma tego klucza). Dozwolone wartości scope.related[].kind: table, row, history-row, history-table.

  2. W logu na stderr (# Typ podstawowy: …, # Typ powiązany (kind): …, # Klasa bazowa: …, # Klasa pochodna: …) — wygodne do szybkiego podglądu w konsoli.

Gdy --related jest podany, ale typu z <NazwaTypuDanych> nie da się znaleźć w referencjach (np. literówka), skrypt loguje ostrzeżenie na stderr i wraca do prostego dopasowania po nazwie (bez sekcji scope).

Przykłady

Pełna inwentaryzacja:

dotnet script ~/.claude/skills/soneta-programming/scripts/scan-workers.csx \
    -- ./bin/Debug/net8.0

Tylko workery przypięte do DokumentHandlowy:

dotnet script ~/.claude/skills/soneta-programming/scripts/scan-workers.csx \
    -- ./bin/Debug/net8.0 DokumentHandlowy

Format wyjścia: JSON

Skrypt zawsze wypisuje JSON na stdout — nadaje się do dalszego przetwarzania (jq, skrypty, narzędzia). Markdown został usunięty, żeby utrzymać jedno, stabilne źródło danych dla automatów i klientów.

Struktura JSON:

{
  "description": "Workery przypięte do typu `DokumentHandlowy` (Soneta)",
  "Soneta.Handel.DokumentHandlowy": [
    {
      "workerAssembly": "Soneta.Zadania",
      "workerType": "Soneta.Zadania.Smsing.WyslijSmsWorker",
      "name": "WyslijSms",
      "params": [
        { "name": "ConstructorParam", "type": "Soneta.X.Y", "kind": "ctor" },
        { "name": "PropWithContextAttr", "type": "Soneta.X.Y" },
        {
          "name": "Pars",
          "type": "Soneta.X.SomeWorker.Params",
          "props": [
            { "name": "DataOd", "type": "Soneta.Types.Date" },
            { "name": "DataDo", "type": "Soneta.Types.Date" }
          ]
        }
      ],
      "actions": [
        { "name": "Wyślij SMS", "method": "WyslijSmsa", "result": "object" }
      ],
      "props": [
        { "name": "PublicPropWithoutContextAttr", "type": "Soneta.X.Y" }
      ]
    }
  ]
}
  • Klucze top-level: description + jeden klucz na każdy DataType (pełna nazwa z namespace).
  • params łączy parametry konstruktora (z kind: "ctor") oraz property z atrybutem [Context] (bez pola kind) — wszystko, co Soneta inicjuje z Context przy tworzeniu workera.
  • Gdy typ parametru dziedziczy z Soneta.Business.ContextBase (klasa parametrów workera — zwykle nested Params w klasie workera), wpis zawiera dodatkowo props z listą publicznych, instancyjnych property tej klasy. To pod-parametry, które użytkownik widzi w oknie parametrów workera. Property samego ContextBase (np. Context) są pomijane.
  • actions — metody z atrybutem [Action]. name to tytuł z atrybutu, method to nazwa metody w C#, result to deklarowany typ wyniku (void dla metod bez wartości).
  • props — publiczne, instancyjne property z getterem, bez [Context] — kandydaci do bindowania w form.xml przez {Workers.<name>.<Property>}.
  • Sekcje puste (params/actions/props) są pomijane, żeby JSON pozostał zwięzły.
  • Extendery (rejestracje bez DataType) trafiają — wyłącznie w trybie bez filtra typu — pod klucz __extenders__.

Przykłady filtrowania jq

# Lista workerów dla typu:
jq '."Soneta.Handel.DokumentHandlowy"[] | .workerType' /tmp/out.json

# Tylko z akcjami menu Czynności:
jq '."Soneta.Handel.DokumentHandlowy"[] | select(.actions)' /tmp/out.json

# Konkretny worker po aliasie:
jq '."Soneta.Handel.DokumentHandlowy"[] | select(.name=="KSeFWyslij")' /tmp/out.json

# Workery, których parametr `Params` ma pole `Magazyn`:
jq '.[] | arrays | .[] | select((.params // [])
    | map(.props // []) | flatten | map(.name) | index("Magazyn"))' /tmp/out.json

Kody wyjścia

Kod Znaczenie
0 OK — wypisano listę workerów i extenderów
1 Błąd argumentów / nie istnieje katalog / brak DLL

Ograniczenia

  • Skanuje tylko górny poziom katalogu (SearchOption.TopDirectoryOnly) — jeśli DLL są rozproszone, skopiuj je do jednego katalogu.
  • Filtruje atrybut WorkerAttribute po nazwie i namespace Soneta*. Jeśli inny dodatek zarejestruje atrybut o tej samej nazwie w innym namespace, nie zostanie ujęty.
  • Skrypt wypisuje publiczne instancyjne property/metody. Property prywatne lub statyczne są pomijane (nie biorą udziału w bindowaniu / akcjach).
  • Property z modyfikatorem internal nie są ujęte — Soneta wymaga publicznych członków do bindowania UI.
  • Pierwsze uruchomienie pobiera pakiet NuGet Microsoft.CodeAnalysis.CSharp — wymaga połączenia internetowego (kolejne odpalenia działają offline).

Typowy workflow

  1. Inwentaryzacja workerów — uruchom scan-workers.csx, znajdź wszystkie workery zarejestrowane dla interesującego Cię typu danych (np. DokumentHandlowy).
  2. Wybór aliasu do bindingu — z sekcji workera odczytaj Alias i Property do bindowania — to bezpośrednio wartości do podstawienia w form.xml: {Workers.<Alias>.<Property>} (worker) lub {new <Alias>.<Property>} (extender).
  3. Lista akcji — kolumna „Menu Czynności" pokazuje, które pozycje pojawią się w menu Czynności dla danego obiektu.
  4. Code review — porównaj listę z oczekiwaną zawartością dodatku (wszystkie spodziewane rejestracje są obecne, aliasy się nie pokrywają, akcje mają komplet metod sterujących).

Powiązania

  • worker-extender.md — semantyka workerów/extenderów, atrybut [Context], [Action], metody sterujące IsVisibleXxx / IsEnabledXxx / GetNameXxx / IsCheckedXxx, bindowanie w form.xml.
  • context.md — jak działa Context i co może być źródłem parametrów workera.
  • scan-modules.md — lista modułów i tabel platformy (komplementarne do scan-workers).
  • scan-props.md — pola konkretnego rekordu (do których workery doklejają property kalkulowane).
Reference in New Issue View Git Blame Copy Permalink