Przegląd

Każda wtyczka jest instalowana w swoim własnym folderze wewnątrz folderu Plugins (V6+). Jeden folder ‒ jedna wtyczka. W folderze muszą znajdować się co najmniej dwa pliki: plik DLL wtyczki oraz Manifest.xml. Oprócz tych plików, folder wtyczki i podfoldery mogą zawierać dodatkowe biblioteki, pliki konfiguracyjne, zasoby i inne.

Aplikacja Syrve POS otrzymuje pełne informacje o wtyczce z pliku Manifest.xml.

Pliki kontraktu API Syrve POS (Resto.Front.Api.Vx.dll, Resto.Front.Api.Vx.xml) są potrzebne tylko podczas fazy tworzenia i kompilacji wtyczki, nie powinny być dystrybuowane i instalowane razem z wtyczką, w czasie działania kontrakty będą używane bezpośrednio z folderu aplikacji Syrve POS. Podczas podłączania kontraktów do projektu przez bezpośrednie odwołanie do pliku dll należy ustawić Copy Local = False. Gdy pakiet NuGet jest podłączony przez PackageReference dla wersji przed V7Preview2, kopiowanie musi być wyłączone przez <PrivateAssets>all</PrivateAssets> (opis), począwszy od V7Preview2 kopiowanie jest automatycznie wyłączone.

Struktura pliku Manifest.xml

Wymagane parametry

• FileName — string, nazwa pliku DLL wtyczki (bez ścieżki, tylko nazwa pliku i rozszerzenie). Taki plik powinien znajdować się obok Manifest.xml. Wielkość liter może, ale nie musi mieć znaczenia w zależności od systemu plików, dlatego jako ogólna zasada wielkość liter powinna być traktowana jako istotna, a nazwa pliku określona w manifeście powinna się z nią zgadzać.
• TypeName — string, nazwa klasy wtyczki w pliku DLL FileName (pełna nazwa, łącznie z przestrzenią nazw). Wrażliwe na wielkość liter.
• ApiVersion — string, wersja API używana przez wtyczkę (V4/V5/V6Preview4/V6/…). Wrażliwe na wielkość liter. Określona wersja musi odpowiadać zaimplementowanej wersji interfejsu IFrontPlugin.
• LicenseModuleId — 32-bitowa liczba całkowita znakowa, ID modułu licencyjnego. Ta liczba musi odpowiadać wartości określonej w atrybucie PluginLicenseModuleId.

Dodatkowe parametry

• IsSingleInstance — true/false, czy wtyczka powinna działać pojedynczo w grupie terminali. Domyślnie false, co oznacza, że wtyczka będzie uruchamiana na każdym terminalu, na którym jest zainstalowana. Użyj tego parametru, aby system uruchamiał wtyczkę tylko na jednym terminalu; może to być szczególnie przydatne, jeśli nie jest wymagane, aby kilka kopii wtyczki przetwarzało te same dane. Na przykład, jeśli wtyczka śledzi zmiany zamówień i wysyła je do zewnętrznego serwera, jedna wtyczka wystarczy. Ponieważ szczegóły zamówień są synchronizowane między terminalami w grupie, kopie wtyczki działające jednocześnie na kilku terminalach widziałyby te same zamówienia i wysyłałyby duplikaty wywołań do zewnętrznego serwera z tymi samymi danymi. Odpowiada atrybutowi SingleInstancePlugin w wersjach przed V5.
• RestartOnCrash — true/false, czy wtyczka powinna być ponownie uruchomiona po awarii. Domyślnie true, co oznacza, że wtyczka, która uległa awarii, zostanie ponownie uruchomiona. Wtyczka jest uznawana za awaryjną, jeśli jej proces hosta zakończy się kodem zwrotu różnym od zera. Ustawione są następujące ograniczenia:
  • Jeśli ten parametr nie występuje w manifeście, wtyczka zostanie ponownie uruchomiona tylko wtedy, gdy ulegnie awarii po 10 sekundach działania. Jest to wymagane, aby uniknąć ponownego uruchamiania wtyczek, które wykonują szereg kontroli na starcie i jeśli warunki działania nie są spełnione, zamykają się przez celową awarię. Aby poprawnie zamknąć wtyczkę, lepszym rozwiązaniem byłoby użycie metody PluginContext.Shutdown(), jednak w praktyce większość wtyczek jest wykonana nieprawidłowo. Domyślne zachowanie może ulec zmianie w przyszłości. Jeśli manifest wyraźnie określa, że restart jest wymagany, minimalny czas działania przed awarią nie jest ograniczony.
  • W przypadku nieodwracalnie uszkodzonych wtyczek obowiązuje ograniczenie: nie więcej niż cztery awarie na godzinę. Jeśli wtyczka ulegnie awarii po raz piąty w ciągu jednej godziny, zostanie uznana za uszkodzoną i nie zostanie ponownie uruchomiona w tej sesji Syrve POS.

Przestarzałe podejście dla V4/V5

API V5 i wcześniejsze wersje używały innego podejścia, które zakładało umieszczenie kilku plików DLL w folderze wtyczki (wtyczka i jej zależności). Syrve POS skanował wszystkie takie pliki DLL, aby znaleźć klasę implementującą interfejs znacznikowy IFrontPlugin i odczytywał dodatkowe parametry z atrybutów znalezionej klasy. To podejście miało szereg wad i od wersji V6 stosowany jest manifest. Manifest jest wymagany dla V6, ale wersje API V4/V5 obsługują oba sposoby: jeśli manifestu nie ma, skanowane są pliki DLL, ale jeśli plik Manifest.xml istnieje, jest on używany do odczytu danych. Podejście z użyciem pliku manifestu jest bardziej niezawodne i działa szybciej niż skanowanie plików DLL, dlatego zaleca się dodanie tego opcjonalnego pliku do folderów wtyczek V4/V5.

Jednak wtyczki V4/V5 muszą przestrzegać warunków kontraktu i określać atrybuty do skanowania, nawet jeśli używany jest manifest. Ponieważ manifesty są obsługiwane od wersji Syrve POS 6.4, wcześniejsze wersje zawsze skanowały pliki DLL niezależnie od dostępności manifestu.

Przykłady

<?xml version="1.0" encoding="utf-8" ?>
<Manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.w3.org/2001/XMLSchema ../Binaries/syrve/Manifest.xsd">
  <FileName>Resto.Front.Api.SamplePlugin.dll</FileName>
  <TypeName>Resto.Front.Api.SamplePlugin.SamplePlugin</TypeName>
  <ApiVersion>V6</ApiVersion>
  <LicenseModuleId>21005108</LicenseModuleId>
</Manifest>

Ten przykład, jak również schemat pliku Manifest.xsd, można znaleźć w pakiecie offline Syrve POS API SDK Syrve POS API SDK.