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.dllz folderubinaplikacji 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. |
Navigator.Extension¶
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¶
- W
App.configprojektu Start, w sekcjiconnectionStrings, wpisz serwer i bazę testową. - W
Program.cswywołajMaindla 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);
- 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¶
- W rozwiązaniu Navigator.Extension dodaj projekt Class Library (.NET Framework) w wersji frameworka zgodnej z Navigatorem.
- W
Properties/AssemblyInfo.csustaw[assembly: AssemblyProduct("Navigator")]. Po tym Navigator rozpoznaje bibliotekę jako swoje rozszerzenie. - Dodaj referencję do
Navigator.Model.dll. - 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¶
- Zbuduj projekt. Biblioteka jest w folderze
bin\Debugalbobin\Releaseprojektu. - W Ustawienia > Personalizacja > Rozszerzenia:
- nową bibliotekę dodaj przyciskiem Dodaj,
- nową wersję istniejącej biblioteki, także Navigator.Extensions, wgraj w jej edycji.
- 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¶
- Przykłady zapytań SQL: zapytania do list, filtrów i warunków.