Структура папок

Общая информация

Каждый плагин устанавливается в свою собственную папку внутри папки Plugins (V4+). Одна папка — один плагин. Внутри папки должны находиться как минимум два файла — dll-файл плагина и его манифест Manifest.xml (V6+, см. замечание о V4/V5). Помимо них в папке плагина и во вложенных папках могут располагаться дополнительные библиотеки, конфигурационные файлы, ресурсы и так далее.

Приложение iikoFront получает всю информацию о плагине из файла Manifest.xml.

Файлы контрактов iikoFront API (Resto.Front.Api.Vx.dll, Resto.Front.Api.Vx.xml) нужны только на этапе разработки и компиляции плагина, не следует распространять и устанавливать их вместе с плагином, в рантайме будут использоваться контракты из папки самого приложения iikoFront. При подключении контрактов к проекту через прямую ссылку на dll-файл следует указывать Copy Local = False. При подключении NuGet-пакета через PackageReference для версий до V7Preview2 копирование необходимо отключить с помощью <PrivateAssets>all</PrivateAssets> (описание), начиная с V7Preview2 копирование отключается автоматически.

Структура файла Manifest.xml

Обязательные параметры

• FileName — строка, имя dll-файла с плагином (без пути, только имя файла с расширением). Файл с таким именем должен лежать рядом с Manifest.xml. Регистр может иметь или не иметь значение в зависимости используемой файловой системы, поэтому следует считать, что в общем случае регистр важен и в манифесте имя файла должно быть указано с учётом регистра.
• TypeName — строка, имя класса плагина внутри dll-файла FileName (полное имя, включая namespace). Case sensitive.
• ApiVersion — строка, версия Api, используемая плагином (V4/V5/V6Preview4/V6/…). Case sensitive. Указанная версия должна совпадать с версией реализуемого интерфейса IFrontPlugin.
• LicenseModuleId — 32-битное знаковое целое число, идентификатор модуля лицензии. Это число должно совпадать со значением, указанным в атрибуте PluginLicenseModuleId.

Дополнительные параметры

• IsSingleInstance — true/false, запускать ли плагин в единственном экземпляре в пределах группы терминалов. По умолчанию false, то есть плагин будет запускаться на каждом терминале, где он установлен. С помощью данного флага можно задать ограничение, чтобы плагин запустился только на одном терминале, это может быть удобно, если несколько экземпляров плагина не должны обрабатывать одни и те же данные. Например, если плагин следит за изменением заказов и отправляет их на внешний сервер, достаточно одного экземпляра плагина. Учитывая синхронизацию заказов между терминалами в пределах группы, работающие параллельно на разных терминалах экземпляры такого плагина видели бы одни и те же заказы и дублировали бы вызовы к внешнему серверу, отправляя одни и те же данные. Соответствует атрибуту SingleInstancePlugin из версий до V5.
• RestartOnCrash — true/false, перезапускать ли плагин после падения. По умолчанию true, то есть упавший плагин будет перезапущен. Плагин считается упавшим, если его хост-процесс завершился с ненулевым кодом возврата. Установлены следующие ограничения:
  • Если данная настройка отсутствует в манифесте, плагин будет перезапущен, только если он упал, проработав не менее 10 секунд. Это необходимо для того, чтобы не перезапускать плагины, которые при запуске выполняют ряд проверок и при отсутствии условий для работы выключаются через преднамеренное падение. Для корректного завершения работы плагина следовало бы вызывать метод PluginContext.Shutdown(), но фактически многие плагины реализованы ошибочно. Поведение по умолчанию может измениться в будущем. Если в манифесте явно указано, что требуется перезапуск, ограничения минимальной продолжительности работы перед падением не будет.
  • На случай безнадёжно сломанных плагинов предусмотрено ограничение — не более четырёх падений в час. Если плагин упадёт в пятый раз в течение часа, он будет признан безнадёжным и не будет больше перезапускаться в этом сеансе работы приложения iikoFront.

Устаревший вариант для V4/V5

При выпуске версий API до V5 включительно использовался старый вариант — в папке плагина оказывалось несколько dll-файлов (сам плагин и его зависимости), приложение iikoFront сканировало все эти dll-файлы в поисках класса, реализующего маркерный интерфейс IFrontPlugin и считывало дополнительные параметры из атрибутов найденного класса. Этот подход имел ряд недостатков, и начиная с V6 его сменил вариант с манифестом. Если для V6 манифест обязателен, то для ранее выпущенных версий API (V4/V5) будут поддерживаться оба варианта: при отсутствии манифеста по-старинке будут сканироваться dll-файлы, а если файл Manifest.xml есть, то данные будут прочитаны из него. Вариант с манифестом надёжнее и быстрее, чем сканирование dll-файлов, поэтому рекомендуется добавить этот необязательный файл и для плагинов на V4/V5.

Однако, плагинам на V4/V5 даже при использовании манифеста необходимо продолжать придерживаться контракта и по-прежнему указывать атрибуты для сканирования. Поскольку поддержка манифестов добавлена в приложение iikoFront начиная с версии 6.4, ранее выпущенные версии приложения всегда будут сканировать dll-файлы независимо от наличия манифеста.

Примеры

<?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/iiko/Manifest.xsd">
  <FileName>Resto.Front.Api.SamplePlugin.dll</FileName>
  <TypeName>Resto.Front.Api.SamplePlugin.SamplePlugin</TypeName>
  <ApiVersion>V6</ApiVersion>
  <LicenseModuleId>21005108</LicenseModuleId>
</Manifest>

Данный пример, как и схему xml-файла Manifest.xsd можно посмотреть в iikoFront API SDK.