Przejdź do treści

Rozszerzenia .NET

Logikę, której nie da się ustawić w konfiguracji, dopisuje się w C#: w bibliotece Navigator.Extension albo w osobnej bibliotece akcji. Z tego artykułu dowiesz się, jak działa każda z nich, jak napisać akcję i jak wgrać rozszerzenie do Navigatora.

Zanim zaczniesz

  • Rozszerzenia piszesz w Visual Studio, w .NET Framework w tej samej wersji co Navigator.
  • Projekt Navigator.Extension danej instalacji jest w systemie kontroli wersji. Dostęp daje opiekun środowiska. Każda instalacja, np. produkcyjna i testowa, ma własny projekt.
  • Projekty odwołują się do biblioteki Navigator.Model.dll z folderu bin aplikacji Navigatora. Wersja biblioteki musi odpowiadać wersji Navigatora.
  • Dane czytaj i zapisuj przez Navigator.Model.API. To zalecany sposób dla nowych rozwiązań.
Rozwiązanie Kiedy się wykonuje Kiedy stosować
Navigator.Extension Przy zdarzeniach w systemie: zapis, usunięcie, krok obiegu, przycisk, OCR i inne. Logika, która ma działać przy każdym zdarzeniu danego rodzaju.
Biblioteka akcji Gdy wywoła ją przycisk albo krok obiegu. Akcje, które administrator podpina w procedurach i pod przyciski, tak jak akcje systemowe.

Rozwiązanie ma dwa projekty: Navigator.Extensions, czyli bibliotekę wgrywaną do Navigatora, i Start do testów.

Navigator przy każdym zdarzeniu wywołuje metodę Main klasy Navigator.Extensions.ExtendTran:

public static string Main(SqlManager sql, ETable table, string objectIds, EType type, int? buttonId, int userId)
Parametr Opis
sql Połączenie z bazą w transakcji zdarzenia.
table Tabela obiektu, np. ETable.Do dla dokumentów, ETable.Co dla kontrahentów.
objectIds ID obiektów rozdzielone przecinkami, np. "1521,1522".
type Rodzaj zdarzenia (patrz niżej).
buttonId ID przycisku, gdy zdarzenie wywołał przycisk.
userId ID użytkownika, który wywołał zdarzenie.
EType Kiedy
A, U, D Dodanie, aktualizacja, usunięcie pojedynczego wpisu w bazie.
SA Po dodaniu obiektu razem z obiektami pochodnymi, np. dokumentu z uprawnieniami.
SU Po aktualizacji obiektu razem z obiektami pochodnymi.
BD Przed usunięciem obiektu.
AC Po skopiowaniu obiektu.
C Kliknięcie przycisku na formularzu.
M Kliknięcie przycisku menu.
WU Krok obiegu.
WAU Cofnięcie kroku obiegu.
AO Po OCR załącznika dokumentu.
BE, AE Przed i po eksporcie do Excela.
LI Zalogowanie użytkownika.

Kod autoryzacyjny przy logowaniu

Przy zdarzeniu LI tekst zwrócony przez Main jest kodem autoryzacyjnym: Navigator poprosi użytkownika o wpisanie dokładnie tego tekstu. Rozszerzenie generuje kod i samo wysyła go użytkownikowi, np. e-mailem. Pusta wartość oznacza logowanie bez kodu.

Komunikaty i przerwanie operacji

Main zwraca tekst komunikatu dla użytkownika. Najwygodniej zbudować go klasą Navigator.Model.Global.Message:

Komunikat Kod
Sukces new Message("Operacja zakończona pomyślnie")
Ostrzeżenie new Message("Zadanie może być uszkodzone", EMessageType.Alert)
Błąd new Message("Kwoty się nie zgadzają", EMessageType.Error)

Wyjątek przerywa operację i wycofuje transakcję, np. nie pozwala zapisać dokumentu: throw new Exception("Operacja nie powiodła się");. Użytkownik zobaczy treść wyjątku.

Testowanie w projekcie Start

  1. W App.config projektu Start, w sekcji connectionStrings, wpisz serwer i bazę testową.
  2. W Program.cs wywołaj Main dla wybranego zdarzenia, np.:
// zapis dokumentu o ID 1 przez użytkownika 1
ExtendTran.Main(sql, ETable.Do, "1", EType.SU, null, 1);
// przed usunięciem kontrahenta o ID 8545
ExtendTran.Main(sql, ETable.Co, "8545", EType.BD, null, 119);
// kliknięcie przycisku 1845 na dokumencie 10816
ExtendTran.Main(sql, ETable.Do, "10816", EType.C, 1845, 1);
  1. Uruchom projekt w debugerze i śledź działanie kodu.

Biblioteka akcji

Akcje to publiczne metody statyczne z atrybutem z Navigator.Model.Extension:

Atrybut Parametry W Navigatorze
[ButtonAction] Stałe: (SqlManager sql, ETable table, int[] objectIds, int userId). Navigator sam przekazuje ID zaznaczonych obiektów i użytkownika. Akcja. Podpina się ją pod przycisk albo krok obiegu, bez formularza konfiguracji.
[WorkflowAction] Dowolne. Każdy parametr staje się polem w konfiguracji akcji. Metoda z parametrami. Podpina się ją w procedurze obiegu, a pod przycisk przez procedurę.

Obie zwracają Message, a błąd zgłaszają wyjątkiem, tak jak w Navigator.Extension.

[ButtonAction]
public static Message FakturyKontrahenta(SqlManager sql, ETable table, int[] objectIds, int userId)
{
    var document = new Navigator.Model.API.V1.Document.Document(objectIds[0], false);
    // ...
    return new Message("Dopisano faktury kontrahenta");
}

[WorkflowAction]
public static Message UtworzZamowienie(SqlManager sql, int doId, int userId)
{
    // ...
    return new Message("Utworzono zamówienie");
}

Stałe, do których akcja często się odwołuje, np. GUID-y pól i ID typów dokumentów, trzymaj w osobnej klasie, np. Constants.

Nowa biblioteka

  1. W rozwiązaniu Navigator.Extension dodaj projekt Class Library (.NET Framework) w wersji frameworka zgodnej z Navigatorem.
  2. W Properties/AssemblyInfo.cs ustaw [assembly: AssemblyProduct("Navigator")]. Po tym Navigator rozpoznaje bibliotekę jako swoje rozszerzenie.
  3. Dodaj referencję do Navigator.Model.dll.
  4. Napisz akcje. Do testów użyj projektu Start.

Akcje można też dodać w samym projekcie Navigator.Extensions, w nowej klasie z tymi samymi atrybutami.

Wgranie rozszerzenia

  1. Zbuduj projekt. Biblioteka jest w folderze bin\Debug albo bin\Release projektu.
  2. W Ustawienia > Personalizacja > Rozszerzenia:
    • nową bibliotekę dodaj przyciskiem Dodaj,
    • nową wersję istniejącej biblioteki, także Navigator.Extensions, wgraj w jej edycji.
  3. Sprawdź listę metod biblioteki: akcje [ButtonAction] mają typ Akcja, a [WorkflowAction] typ Metoda z parametrami.

Akcje z rozszerzeń konfiguruje się tak samo jak akcje systemowe (patrz Akcje systemowe).

Co dalej