iikoFront API docs SDK

Управление версиями

Разделение API на несколько версий необходимо для совершенствования без ущерба обратной совместимости. С одной стороны, постоянно возникают новые потребности и необходимо вносить изменения, с другой стороны, любое изменение программного интерфейса может нарушить работу существующих плагинов. Для решения этой дилеммы история развития API делится на версии: в определённый момент разработка очередной версии прекращается, интерфейс фиксируется, дальнейшее развитие продолжается в рамках следующей версии. Какие бы изменения ни вносились в будущем, разработанный под зафиксированную версию плагин будет исправно функционировать до тех пор, пока эта версия не перестанет поддерживаться.

Жизненный цикл версий

Большие LTS-версии (от Long-Term Support) выпускаются примерно раз в два года и поддерживаются около четырёх лет. До октября 2026 года промежуточные preview-версии выходили каждые три месяца и поддерживались в течение 3 версий iikoRMS. С ноября 2026 года, начиная с iikoRMS 9.8.1, обновления iikoRMS выходят ежемесячно, а каждая Preview поддерживается в течение трёх кварталов — девяти последовательных месячных выпусков включительно. Период поддержки Preview перекрывается: выпуск новой Preview не прекращает поддержку предыдущих. LTS-версии продолжают выпускаться примерно раз в два года и поддерживаться около четырёх лет. Если между выпусками iikoRMS в API нет изменений, новая Preview не выпускается, а поддержка предыдущей Preview продлевается до следующего месячного выпуска на один месяц.

LTS-версии нумеруются по порядку целыми числами — V1, V2, V3, V4, V5, V6 и так далее. Preview-версии являются копиями промежуточных состояний разрабатываемой LTS-версии, поэтому содержат в названии номер разрабатываемой LTS-версии и нумеруются по порядку с префиксом «Preview». Например, в прежней схеме во время разработки V9 выходили версии V9Preview1–V9Preview7, после чего вышла сама V9.

Схема релизов с ноября 2026 года

Каждый минорный цикл включает шесть ежемесячных выпусков с окончаниями .1–.6. Первый цикл начинается с 9.8.1 в ноябре 2026 года. Календарь ниже строится из данных новой схемы.

Матрица объединяет уже выпущенные версии и план на будущее. По вышедшим релизам она показывает фактические данные; будущие строки являются примерным графиком и могут измениться. Например, если V10Preview6 выйдет в 9.8.4, а в 9.8.5 изменений API не будет, новая Preview в 9.8.5 не фиксируется и поддержка V10Preview6 продлевается на месяц. В 9.8.6 тогда выйдет V10Preview7, а не V10Preview8. Для LTS сохраняется прежний цикл: выпуск примерно раз в два года и поддержка около четырёх лет.

Исторический график выпуска (до 9.7)

Легенда:
LTS разработка
LTS поддержка
Preview версия

После выпуска очередной LTS-версии роли перераспределяются следующим образом:

Цикл preview-версий чуть проще:

Выбор версии

По умолчанию рекомендуется использовать стабильную LTS-версию, это позволит минимизировать трудозатраты по миграции на новые версии API. Если необходимы новые функции, ещё недоступные в LTS-версиях, рекомендуется использовать актуальную preview-версию. С ноября 2026 года Preview выпускаются ежемесячно, но переходить на каждую новую версию не обязательно: используемая Preview поддерживается в течение трёх кварталов. Разработку под версии, объявленные устаревшими, лучше даже не начинать, это бесперспективно, эти версии поддерживаются лишь для обратной совместимости на период, когда новая версия API уже вышла, а плагины на неё пока не перешли. Разрабатываемую версию использовать не рекомендуется, поскольку её интерфейс ещё не зафиксирован, обратная совместимость не обеспечивается, возможны любые изменения. Эта версия доступна для изучения нововведений и раннего начала разработки плагина для будущей версии API, чтобы к моменту её выпуска иметь готовый или почти готовый плагин, предоставляющий новые возможности.

Версия API, под которую разработан плагин, определяется по версии интерфейса IFrontPlugin, который он реализует. Например, если плагин ссылается на сборку Resto.Front.Api.V6.dll и реализует интерфейс IFrontPlugin из этой сборки, это V6-плагин.

Предполагается, что V6-плагин использует программный интерфейс версии V6. Тем не менее, при необходимости плагин может одновременно использовать все поддерживаемые версии API. Учитывая, что начиная с V6 пространства имён не содержат номер версии API, во избежание коллизий между одноимёнными типами из разных сборок придётся использовать extern alias. Например, чтобы из V6-плагина получить доступ к операции, которая появилась только в V7Preview2, помимо обычной ссылки на V6 необходимо добавить ссылку V7Preview2 с указанием alias V7Preview2, и затем из PluginContext.Services извлечь сервис V7Preview2::Resto.Front.Api.IOperationService. Механизм PackageReference поддерживает extern alias начиная с Visual Studio 2019 16.7. Важно: не следует одновременно реализовывать интерфейсы IFrontPlugin разных версий, такой плагин не будет загружен.

Соответствие версий iikoRMS и версий API

1 Версия V6Preview4 была экспериментальной, она выпущена в начале цикла разработки iikoRMS 6.4. Кроме того, были пропущены V6Preview6 и V6Preview7, вместо них сразу вышла LTS-версия V6.
2 Поддержка V6 продлена до iikoRMS 9.2.
3 Версия V7Preview2 выпущена с опозданием в 7.3.5 (вместо 7.2).
4 Поддержка версии V7Preview7 была продлена до 8.6 включительно из-за проблем с автообновлением плагинов с V7Preview7 на V7.
5 Срок жизни Preview-версий начиная с V8Preview4 увеличен на одну версию iikoRMS.
6 Поддержка V9Preview6 прекращена в iikoRMS 9.7.

Начиная с версии iikoRMS 8.5 цикл поддержки Preview-версий увеличивается: версия V8Preview4, которая была выпущена в 8.3, будет удалена лишь в 8.6, т.е. поддерживается в 8.3, 8.4, 8.5.

Обратная совместимость

Обратная совместимость предполагает гарантию того, что плагин, разработанный под определённую версию API, будет одинаково работать с любыми версиями iikoRMS, поддерживающими эту версию API.

Программная совместимость

Программная совместимость запрещает изменения в публичном интерфейсе — необходимо фиксировать структуры данных, сигнатуры методов и прочее. Понятно, что если удалить какой-то публичный класс или метод, плагин перестанет компилироваться с новым SDK, а скомпилированный под старый SDK будет падать во время работы (TypeLoadException, MissingMethodException и т. п.). Возможны и не столь очевидные нарушения обратной совместимости. Однако, если не брать в расчёт экзотические случаи, на практике добавление нового класса, свойства или метода вполне может оказаться безопасным. Зато появляется возможность начать использовать новые функции, не дожидаясь очередного релиза. С учётом этого сейчас принята такая политика:

Изменения в поведении

В общем случае, изменения в поведении выпущенных версий API не допускаются. Если какая-то функция в определённых условиях работала, она и продолжит работать, а если не работала, она продолжит точно так же не работать. Исключение — деструктивные сценарии использования API, когда последствия хуже нарушения обратной совместимости. Например, если из-за уязвимости в API ошибочные действия плагина могли привести к повреждению данных или остановке работы приложения iikoFront, то в API появится соответствующая защита. Это не будет считаться изменением поведения, поскольку корректно работающие плагины не заметят никаких изменений.

Срок поддержки

Под продолжительностью поддержки определённой версии API понимается период, в течение которого выпускаются обновления iikoRMS, поддерживающие эту версию API. В самом продукте iikoRMS нет календарного ограничения на возможность использования той или иной версии API. Все версии API, поддерживаемые конкретной сборкой iikoRMS, поддерживаются ею бессрочно. Таким образом, если пользователь iikoRMS не обновляется, он теоретически может продолжать использовать старые плагины как угодно долго. Однако, на практике пользователь вынужден обновлять iikoRMS ради поддержки изменений в законодательстве, новых функций и исправленных ошибок, а это значит, что и разработчик плагина должен своевременно выпускать обновления плагина, совместимые с новыми версиями API.