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

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

Например, в предыдущей версии в справочнике Заявки в реквизите АвторРешения сохранялась ссылка на сотрудника, который принял решение по данной заявке. Но выяснилось, что после удаления сотрудников из приложения исчезает и информация о том, какой именно сотрудник принимал решение по данной заявке, что нехорошо.

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

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

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

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

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

Тип «Проект»

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

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

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

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

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

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

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

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

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

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

Параметры аннотации — идентификатор алгоритма настройки и порядковый номер выполнения. Идентификатор служит для того, чтобы однозначно отличать один обработчик от другого и не допустить повторного выполнения. Порядковый номер определяет порядок выполнения обработчиков обновления проекта. Идентификатор и номер должны быть уникальны в рамках приложения. Идентификатор не может повторяться с идентификаторами, используемыми в аннотации @НастройкаПриложения. Данная аннотация может быть использована только на методах без параметров либо на методах, принимающих два параметра типа Версия (исходная версия и целевая версия).

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

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

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

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

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

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

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

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

Версия проекта. Во время работы приложения «1С:Шина» отображает ее в диалоге О приложении

Тип Версия

Имя

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

Тип Строка, не более 200 символов

ОбновлениеСВерсии

Минимальная версия, с которой можно применить обновление на текущий проект. Значение ОбновлениеСВерсии должно быть не больше, чем значение Версия

Тип Версия

Представление

Название проекта, понятное пользователю. Во время работы приложения «1С:Шина» отображает его в диалоге О приложении

Обязательное, тип Строка, не более 200 символов

ПредставлениеРазработчика

Название фирмы — разработчика проекта. Во время работы приложения «1С:Шина» отображает его в диалоге О приложении

Тип Строка, не более 200 символов

ПроектПоставщика

Это поле заполняется при создании проекта кастомизации и обновляется при переводе на новую версию поставщика. Содержит информацию о проекте поставщика:

Разработчик

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

Тип Строка, не более 200 символов

Имя

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

Тип Строка, не более 200 символов

Версия

Версия проекта поставщика. Во время работы приложения «1С:Шина» отображает ее в диалоге О приложении

Тип Версия

Разработчик

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

Тип Строка, не более 200 символов

РежимСовместимости

Одна из предыдущих версий конфигурации сервера, которую можно выбрать для запуска приложения «1С:Шина» на текущей версии сервера. Позволяет сохранить поведение соответствующих элементов проекта при переходе на новую версию

Тип Строка

ЯзыкиЛокализации

Языки, для которых есть перевод интерфейса этого приложения.

Тип ЧитаемыйМассив<Язык>

ЯзыкПоУмолчанию

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

Тип Язык