Обновление данных приложения для новой версии проекта

В процессе развития проекта возникают ситуации, когда при переходе на новую версию проекта нужно обновить данные, которые содержатся в приложении.

Например, в предыдущей версии в справочнике Заявки в реквизите АвторРешения сохранялась ссылка на сотрудника, который принял решение по данной заявке. Но выяснилось, что после удаления сотрудников из приложения исчезает и информация о том, какой именно сотрудник принимал решение по данной заявке. Чтобы это исправить, в новой версии разработчики добавили в этот справочник еще один реквизит — АвторРешенияСтрокой типа Строка. Теперь, чтобы существующие данные приложения адаптировать к новой логике, нужно обойти все заявки и в новый реквизит АвторРешенияСтрокой записать ФИО того сотрудника, который указан в реквизите АвторРешения.

Другой пример — когда приложение содержит какие-то стандартные классификаторы, которые обновляются со временем. При переходе на новую версию проекта нужно обновить тот классификатор, который уже используется в приложении.

Для решения подобных задач предназначен элемент проекта вида Проект и аннотации @НастройкаПриложения и @ОбновлениеПроекта. Ими следует помечать методы-обработчики, осуществляющие первоначальную настройку приложения, и методы-обработчики, осуществляющие обновление данных, соответственно. Эти события вы можете обработать в модуле проекта.

Элемент проекта вида «Проект»

Элемент Проект описывает все приложение в целом. автоматически создает такой элемент в новом проекте. Он расположен в самом верху проекта.

Тип «Проект»

Для проекта целиком создает один тип встроенного языка — Проект. Этот тип доступен и на сервере, и на клиенте.

Этот тип не имеет конструктора и имеет единственный экземпляр, который доступен как свойство глобального контекста:

// Получить менеджера проекта
пер МенеджерПроекта = Проект

Модуль проекта

В проекте модуль, расширяющий тип Проект, называется модулем проекта. Он исполняется на сервере.

В этот модуль вы можете добавить обработчики первоначальной настройки и обновления данных приложения.

Обработчик первоначальной настройки приложения

Чтобы метод осуществлял первоначальные настройки приложения, его следует пометить аннотацией @НастройкаПриложения(Ид, Номер). Обработчик первоначальной настройки вызывается при первом применении проекта. Параметры аннотации:

идентификатор алгоритма настройки — служит для того, чтобы однозначно отличать один обработчик от другого и не допустить повторного выполнения;
порядковый номер выполнения — определяет порядок выполнения обработчиков настройки приложения.

Идентификатор и номер должны быть уникальны в рамках приложения. Идентификатор не может совпадать с идентификаторами в аннотации @ОбновлениеПроекта.

Аннотацию @НастройкаПриложения можно использовать только на методах без параметров или с единственным параметром типа Версия. Пример:

@НастройкаПриложения(Ид="ЗапускРегламентныхЗаданий", Номер = 1)
метод ВключитьЗапланированныеЗадания()
    ОбменДанными.ВключитьЗаданиеПоОбменуИзмениями()
;

Обработчик обновления данных приложения

Чтобы метод осуществлял обновления данных приложения, его следует пометить аннотацией @ОбновлениеПроекта(Ид, Номер). Обработчик обновления данных запускается, если изменился номер версии, указанный в описании проекта (и если при этом обработчик не вызывался ранее). Параметры аннотации:

идентификатор алгоритма настройки — служит для того, чтобы однозначно отличать один обработчик от другого и не допустить повторного выполнения;
порядковый номер выполнения — определяет порядок выполнения обработчиков обновления проекта.

Идентификатор и номер должны быть уникальны в рамках приложения. Идентификатор не может совпадать с идентификаторами, используемыми в аннотации @НастройкаПриложения.

Аннотацию @ОбновлениеПроекта можно использовать только на методах без параметров либо на методах, принимающих два параметра типа Версия (исходная и целевая версии).

Таким образом, в методе, помеченном данной аннотацией, вы можете адаптировать существующие пользовательские данные к логике новой версии приложения. Например, возвращаясь к примерам в начале, вы можете обойти все заявки и в новый реквизит АвторРешенияСтрокой записать ФИО того сотрудника, который указан в реквизите АвторРешения, или можете дописать в классификатор новые данные.

@ОбновлениеПроекта(Ид="ДобавлениеНовогоРеквизита", Номер=1)
метод ОбновитьДанные(ИсходнаяВерсия : Версия, ЦелеваяВерсия : Версия)
   если ИсходнаяВерсия < Версия{3.0.0}
   // Обновить до целевой версии
          ...
    ;
;

Аннотации @НастройкаПриложения и @ОбновлениеПроекта можно использовать только в модуле проекта.

Эти обработчики исполняются в режиме без проверок прав доступа, и все подсистемы считаются используемыми.

Во время работы этих обработчиков у экземпляров типов имя-справочника, имя-http-сервиса, имя-ключа-доступа и имя-регистра-сведений отключается вызов обработчиков всех событий, кроме событий вычисления разрешений доступа и ключей доступа. События вычисления разрешений и ключей вызовет не в момент записи сущностей, а отложенно, после того как завершится исполнение обработчиков настройки и обновления приложения, но до того как будет завершено обновление приложения.

Свойства элемента проекта вида «Проект»

Пример описания проекта:

Id: 3654b904-7806-44d2-93d7-72d11b768f14
Представление: "Демонстрационное приложение"
Версия: 1.0
Поставщик: e1c
Имя: ДемонстрационноеПриложение
ПредставлениеПоставщика: "e1c"
РежимСовместимости: 5.0
ЯзыкиЛокализации: [Русский, Английский]
ЯзыкПоУмолчанию: Русский
ЯзыкРазработки: Русский

Версия

Версия проекта. Во время работы приложения отображает ее в диалоге О приложении.

Тип Версия

Имя

Имя проекта. На значение свойства накладываются ограничения в соответствии с правилами формирования имен языка, так как оно входит в пространство имен проекта.