#std690

Обработчики обновления информационной базы

Стандарт действует для конфигураций на базе Библиотеки стандартных подсистем (БСП) и уточняет требования других стандартов.

Подробности по подсистеме см. в документации ИТС: https://its.1c.ru/db/bspdoc.

1.

Основные сведения о библиотеке (основной конфигурации)

1.1.

При разработке конфигураций на базе библиотек каждая библиотека должна сообщать сведения, необходимые для корректного обновления информационной базы:

  • имя;
  • версию;
  • список обработчиков обновления;
  • зависимости от других библиотек.

Эти сведения размещайте в специальном общем модуле, имя которого начинается с ОбновлениеИнформационнойБазы....

Пример: в УТ 11 модуль называется ОбновлениеИнформационнойБазыУТ.

Имена модулей всех используемых библиотек явно перечисляйте в общем модуле ПодсистемыКонфигурацииПереопределяемый:

Процедура ПриДобавленииПодсистем(МодулиПодсистем) Экспорт

    МодулиПодсистем.Добавить("ОбновлениеИнформационнойБазыУТ");

КонецПроцедуры

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

При создании общего модуля ОбновлениеИнформационнойБазы... используйте шаблон:

Шаблон модуля

////////////////////////////////////////////////////////////////////////////////
// Обновление информационной базы <библиотеки или конфигурации>.
//
/////////////////////////////////////////////////////////////////////////////

#Область ПрограммныйИнтерфейс

#Область ДляВызоваИзДругихПодсистем

// СтандартныеПодсистемы.ОбновлениеВерсииИБ

#Область СведенияОБиблиотекеИлиКонфигурации

// Заполняет основные сведения о библиотеке или основной конфигурации.
// Библиотека, имя которой имя совпадает с именем конфигурации в метаданных, определяется как основная конфигурация.
// 
// Параметры:
//  Описание - Структура:
//
//   * Имя                 - Строка - имя библиотеки, например, "СтандартныеПодсистемы".
//   * Версия              - Строка - версия в формате из 4-х цифр, например, "2.1.3.1".
//
//   * ИдентификаторИнтернетПоддержки - Строка - уникальное имя программы в сервисах Интернет-поддержки.
//   * ТребуемыеПодсистемы - Массив - имена других библиотек (Строка), от которых зависит данная библиотека.
//                                    Обработчики обновления таких библиотек должны быть вызваны ранее
//                                    обработчиков обновления данной библиотеки.
//                                    При циклических зависимостях или, напротив, отсутствии каких-либо зависимостей,
//                                    порядок вызова обработчиков обновления определяется порядком добавления модулей
//                                    в процедуре ПриДобавленииПодсистем общего модуля
//                                    ПодсистемыКонфигурацииПереопределяемый.
//   * РежимВыполненияОтложенныхОбработчиков - Строка - "Последовательно" - отложенные обработчики обновления выполняются
//                                    последовательно в интервале от номера версии информационной базы до номера
//                                    версии конфигурации включительно или "Параллельно" - отложенный обработчик после
//                                    обработки первой порции данных передает управление следующему обработчику, а после
//                                    выполнения последнего обработчика цикл повторяется заново.
//   * ЗаполнятьДанныеНовыхПодсистемПриПереходеСДругойПрограммы - Булево - если установить Истина, то при переходе с
//                                    другой программы будут автоматически выполнены обработчики начального заполнения
//                                    новых подсистем. При описании обработчика обновления можно при необходимости
//                                    отключить его выполнение, указав свойство НеВыполнятьПриПереходеСДругойПрограммы.
//
Процедура ПриДобавленииПодсистемы(Описание) Экспорт

    Описание.Имя    = "<Имя библиотеки>";
    Описание.Версия = "XX.XX.XX.XX";
    Описание.ТребуемыеПодсистемы.Добавить("СтандартныеПодсистемы");
    Описание.РежимВыполненияОтложенныхОбработчиков = "Последовательно";

КонецПроцедуры

#КонецОбласти

#Область ОбработчикиОбновленияИнформационнойБазы

// Добавляет в список процедуры-обработчики обновления данных ИБ
// для всех поддерживаемых версий библиотеки или конфигурации.
// Вызывается перед началом обновления данных ИБ для построения плана обновления.
//
// Параметры:
//  Обработчики - см. ОбновлениеИнформационнойБазы.НоваяТаблицаОбработчиковОбновления
//
// Пример:
//  Для добавления своей процедуры-обработчика в список:
//  Обработчик = Обработчики.Добавить();
//  Обработчик.Версия              = "1.1.0.0";
//  Обработчик.Процедура           = "ОбновлениеИБ.ПерейтиНаВерсию_1_1_0_0";
//  Обработчик.РежимВыполнения     = "Оперативно";
//
Процедура ПриДобавленииОбработчиковОбновления(Обработчики) Экспорт

    // Обработчики, выполняемые при каждом обновлении ИБ

    // Обработчики, выполняемые при переходе на определенную версию

    // Обработчики, выполняемые при заполнении пустой ИБ

КонецПроцедуры

// См. ОбновлениеИнформационнойБазыПереопределяемый.ПередОбновлениемИнформационнойБазы.
Процедура ПередОбновлениемИнформационнойБазы() Экспорт

КонецПроцедуры

// Вызывается после завершения обновления данных ИБ.
// В зависимости от тех или иных условий можно отключить штатное открытие формы
// с описанием изменений в новой версии программы при первом входе в нее (после обновления),
// а также выполнить другие действия.
//
// Не рекомендуется выполнять в данной процедуре какую-либо обработку данных.
// Такие процедуры следует оформлять штатными обработчиками обновления, выполняемыми на каждую версию "*".
// 
// Параметры:
//   ПредыдущаяВерсия     - Строка - версия до обновления. "0.0.0.0" для "пустой" ИБ.
//   ТекущаяВерсия        - Строка - версия после обновления. Как правило, соответствует Метаданные.Версия.
//   ВыполненныеОбработчики - ДеревоЗначений:
//     * НачальноеЗаполнение - Булево - если Истина, то обработчик должен срабатывать при запуске на "пустой" базе.
//     * Версия              - Строка - например, "2.1.3.39". Номер версии конфигурации, при переходе
//                                      на которую должна быть выполнена процедура-обработчик обновления.
//                                      Если указана пустая строка, то это обработчик только для начального заполнения
//                                      (должно быть указано свойство НачальноеЗаполнение).
//     * Процедура           - Строка - полное имя процедуры-обработчика обновления/начального заполнения. 
//                                      Например, "ОбновлениеИнформационнойБазыУПП.ЗаполнитьНовыйРеквизит"
//                                      Обязательно должна быть экспортной.
//     * РежимВыполнения     - Строка - режим выполнения обработчика обновления. Допустимые значения:
//                                      Монопольно, Отложенно, Оперативно. Если значение не заполнено, обработчик
//                                      считается монопольным.
//     * ОбщиеДанные         - Булево - если Истина, то обработчик должен срабатывать до
//                                      выполнения любых обработчиков, использующих разделенные данные.
//                                      Допустимо указывать только для обработчиков с режимом выполнения Монопольно и Оперативно.
//                                      Если указать значение Истина для обработчика с режимом
//                                      выполнения Отложенно, будет выдано исключение.
//     * УправлениеОбработчиками - Булево - если Истина, то обработчик должен иметь параметр типа Структура, в котором
//                                          есть свойство РазделенныеОбработчики - таблица значений со структурой,
//                                          возвращаемой этой функцией.
//                                      При этом колонка Версия игнорируется. В случае необходимости выполнения
//                                      разделенного обработчика в данную таблицу необходимо добавить строку с
//                                      описанием процедуры обработчика.
//                                      Имеет смысл только для обязательных (Версия = *) обработчиков обновления 
//                                      с установленным флагом ОбщиеДанные.
//     * Комментарий         - Строка - описание действий, выполняемых обработчиком обновления.
//     * Идентификатор       - УникальныйИдентификатор - необходимо заполнять для обработчиков отложенного обновления,
//                                                 для остальных заполнение не требуется. Требуется для идентификации
//                                                 обработчика в случае его переименования.
//     
//     * БлокируемыеОбъекты  - Строка - необходимо заполнять для обработчиков отложенного обновления,
//                                      для остальных заполнение не требуется. Полные имена объектов через запятую, 
//                                      которые следует блокировать от изменения до завершения процедуры обработки данных.
//                                      Если заполнено, то также требуется заполнить и свойство ПроцедураПроверки.
//     * ПроцедураПроверки   - Строка - необходимо заполнять для обработчиков отложенного обновления,
//                                      для остальных заполнение не требуется. Имя функции, которая для переданного объекта 
//                                      определяет, завершена ли для него процедура обработки данных. 
//                                      Если переданный объект обработан, то следует вернуть значение Истина. 
//                                      Вызывается из процедуры ОбновлениеИнформационнойБазы.ПроверитьОбъектОбработан.
//                                      Параметры, передаваемые в функцию:
//                                         Параметры - см. ОбновлениеИнформационнойБазы.МетаданныеИОтборПоДанным.
//     * ПроцедураЗаполненияДанныхОбновления - Строка - указывается процедура, которая регистрирует данные,
//                                      подлежащие обновлению данным обработчиком.
//     * ЗапускатьТолькоВГлавномУзле  - Булево - только для обработчиков отложенного обновления с режимом выполнения Параллельно.
//                                      Указать Истина, если обработчик обновления должен выполняться только в главном
//                                      узле РИБ.
//     * ЗапускатьИВПодчиненномУзлеРИБСФильтрами - Булево - только для обработчиков отложенного обновления с режимом
//                                      выполнения Параллельно.
//                                      Указать Истина, если обработчик обновления должен также выполняться в
//                                      подчиненном узле РИБ с фильтрами.
//     * ЧитаемыеОбъекты              - Строка - объекты, которые обработчик обновления будет читать при обработке данных.
//     * ИзменяемыеОбъекты            - Строка - объекты, которые обработчик обновления будет изменять при обработке данных.
//     * ПриоритетыВыполнения         - ТаблицаЗначений - таблица приоритетов выполнения между отложенными обработчиками,
//                                      изменяющими или читающими одни и те же данные. Подробнее см. в комментарии
//                                      к функции ОбновлениеИнформационнойБазы.ПриоритетыВыполненияОбработчика.
//     * ВыполнятьВГруппеОбязательных - Булево - следует указывать, если обработчик требуется
//                                      выполнять в одной группе с обработчиками на версии "*".
//                                      При этом возможно менять порядок выполнения обработчика
//                                      относительно других путем изменения приоритета.
//     * Приоритет           - Число  - для внутреннего использования.
//     * МонопольныйРежим    - Неопределено
//                           - Булево - если указано Неопределено, то обработчик 
//                                      должен безусловно выполняться в монопольном режиме.
//                                      Для обработчиков перехода на конкретную версию (версия <> *):
//                                        Ложь   - обработчик не требует монопольного режима для выполнения.
//                                        Истина - обработчик требует монопольного режима для выполнения.
//                                      Для обязательных обработчиков обновления (Версия = "*"):
//                                        Ложь   - обработчик не требует монопольного режима.
//                                        Истина - обработчик может требовать монопольного режима для выполнения.
//                                                 В такие обработчики передается параметр типа структура
//                                                 со свойством МонопольныйРежим (типа Булево).
//                                                 При запуске обработчика в монопольном режиме передается
//                                                 значение Истина. В этом случае обработчик должен выполнить
//                                                 требуемые действия по обновлению. Изменение параметра
//                                                 в теле обработчика игнорируется.
//                                                 При запуске обработчика в немонопольном режиме передается
//                                                 значение Ложь. В этом случае обработчик не должен вносить никакие
//                                                 изменения в ИБ.
//                                                 Если в результате анализа выясняется, что обработчику требуется
//                                                 изменить данные ИБ, следует установить значение параметра в Истина
//                                                 и прекратить выполнение обработчика.
//                                                 В этом случае оперативное (немонопольное) обновление ИБ будет
//                                                 отменено и будет выдана ошибка с требованием выполнить обновление в
//                                                 монопольном режиме.
//   ВыводитьОписаниеОбновлений - Булево - если установить Ложь, то не будет открыта форма
//                                с описанием изменений в новой версии программы. По умолчанию Истина.
//   МонопольныйРежим           - Булево - признак того, что обновление выполнилось в монопольном режиме.
//
Процедура ПослеОбновленияИнформационнойБазы(Знач ПредыдущаяВерсия, Знач ТекущаяВерсия,
        Знач ВыполненныеОбработчики, ВыводитьОписаниеОбновлений, Знач МонопольныйРежим) Экспорт

КонецПроцедуры

// См. ОбновлениеИнформационнойБазыПереопределяемый.ПриПодготовкеМакетаОписанияОбновлений.
Процедура ПриПодготовкеМакетаОписанияОбновлений(Знач Макет) Экспорт

КонецПроцедуры

// Позволяет переопределить режим обновления данных информационной базы.
// Для использования в редких (нештатных) случаях перехода, не предусмотренных в
// стандартной процедуре определения режима обновления.
//
// Параметры:
//   РежимОбновленияДанных - Строка - в обработчике можно присвоить одно из значений:
//              "НачальноеЗаполнение"     - если это первый запуск пустой базы (области данных);
//              "ОбновлениеВерсии"        - если выполняется первый запуск после обновление конфигурации базы данных;
//              "ПереходСДругойПрограммы" - если выполняется первый запуск после обновление конфигурации базы данных, 
//                                          в которой изменилось имя основной конфигурации.
//
//   СтандартнаяОбработка  - Булево - если присвоить Ложь, то стандартная процедура
//                                    определения режима обновления не выполняется, 
//                                    а используется значение РежимОбновленияДанных.
//
Процедура ПриОпределенииРежимаОбновленияДанных(РежимОбновленияДанных, СтандартнаяОбработка) Экспорт

КонецПроцедуры

// Добавляет в список процедуры-обработчики перехода с другой программы (с другим именем конфигурации).
// Например, для перехода между разными, но родственными конфигурациями: базовая -> проф -> корп.
// Вызывается перед началом обновления данных ИБ.
//
// Параметры:
//  Обработчики - ТаблицаЗначений:
//    * ПредыдущееИмяКонфигурации - Строка - имя конфигурации, с которой выполняется переход;
//                                           или "*", если нужно выполнять при переходе с любой конфигурации.
//    * Процедура                 - Строка - полное имя процедуры-обработчика перехода с программы
//                                           ПредыдущееИмяКонфигурации.
//                                  Например, "ОбновлениеИнформационнойБазыУПП.ЗаполнитьУчетнуюПолитику"
//                                  Обязательно должна быть экспортной.
//
// Пример:
//  Обработчик = Обработчики.Добавить();
//  Обработчик.ПредыдущееИмяКонфигурации  = "УправлениеТорговлей";
//  Обработчик.Процедура                  = "ОбновлениеИнформационнойБазыУПП.ЗаполнитьУчетнуюПолитику";
//
Процедура ПриДобавленииОбработчиковПереходаСДругойПрограммы(Обработчики) Экспорт

КонецПроцедуры

// Вызывается после выполнения всех процедур-обработчиков перехода с другой программы (с другим именем конфигурации),
// и до начала выполнения обновления данных ИБ.
//
// Параметры:
//  ПредыдущееИмяКонфигурации    - Строка - имя конфигурации до перехода.
//  ПредыдущаяВерсияКонфигурации - Строка - имя предыдущей конфигурации (до перехода).
//  Параметры                    - Структура:
//    * ВыполнитьОбновлениеСВерсии   - Булево - по умолчанию Истина. Если установить Ложь, 
//        то будут выполнена только обязательные обработчики обновления (с версией "*").
//    * ВерсияКонфигурации           - Строка - номер версии после перехода. 
//        По умолчанию, равен значению версии конфигурации в свойствах метаданных.
//        Для того чтобы выполнить, например, все обработчики обновления с версии ПредыдущаяВерсияКонфигурации, 
//        следует установить значение параметра в ПредыдущаяВерсияКонфигурации.
//        Для того чтобы выполнить вообще все обработчики обновления, установить значение "0.0.0.1".
//    * ОчиститьСведенияОПредыдущейКонфигурации - Булево - по умолчанию Истина. 
//        Для случаев когда предыдущая конфигурация совпадает по имени с подсистемой текущей конфигурации, следует
//        указать Ложь.
//
Процедура ПриЗавершенииПереходаСДругойПрограммы(ПредыдущееИмяКонфигурации, ПредыдущаяВерсияКонфигурации, Параметры) Экспорт

КонецПроцедуры

// Конец СтандартныеПодсистемы.ОбновлениеВерсииИБ

#КонецОбласти

#КонецОбласти

#КонецОбласти
1.2.

Обработчики обновления данных ИБ предназначены для дополнительной обработки данных после реструктуризации базы:

  • инициализация новых констант, новых реквизитов и реквизитов новых предопределенных элементов;
  • перенос данных из устаревших структур метаданных в новые;
  • генерация новых данных;
  • другие операции подготовки данных.

Для автогенерируемых строк, записываемых в ИБ программно (например, при заполнении наименований предопределенных элементов), руководствуйтесь #std784: требованиями по локализации автогенерированных данных.

1.3.

Обработчик обновления состоит из двух частей:

  • описательной: когда обработчик должен выполняться и где находится в конфигурации;
  • программной: код модификации данных ИБ в экспортной процедуре.

Описание нового обработчика добавляйте в ПриДобавленииОбработчиковОбновления по шаблону:

Обработчик = Обработчики.Добавить();
Обработчик.Версия = "<номер версии>";
Обработчик.Процедура = "<полное имя экспортной процедуры>";
Обработчик.НачальноеЗаполнение = {Истина|Ложь};
Обработчик.РежимВыполнения = {"Монопольно"|"Оперативно"|"Отложенно"};

Поля строки таблицы Обработчики:

  • Версия (Строка): номер версии конфигурации, при обновлении на которую вызывается обработчик.
  • Формат: Р.П.В.С (редакция, подредакция, версия, сборка).
  • Если указано *, обработчик выполняется при каждом обновлении ИБ (обычно для служебных системных данных).
  • Если Версия не задана, НачальноеЗаполнение должно быть Истина.
  • Процедура (Строка): полный путь к процедуре-обработчику, например "Справочник.Валюты.ЗаполнитьКодДляПоиска".
  • НачальноеЗаполнение (Булево): если Истина, обработчик вызывается при первом запуске пустой ИБ (0.0.0.0), созданной из поставки.
  • РежимВыполнения (Строка): Монопольно, Оперативно, Отложенно.
  • Монопольно: без активных пользовательских сеансов, регламентных заданий, внешних соединений и веб-сервисов.
  • Оперативно: в редких случаях, когда важно минимизировать ожидание пользователей при динамическом переходе на исправительные релизы без изменения структуры данных.
  • Отложенно: в фоне, после завершения монопольных/оперативных обработчиков, когда пользователи уже могут входить в программу.

Если обязательный обработчик (Версия = "*") требует определить необходимость монопольного режима программно, учитывайте двухфазный вызов:

  • первый вызов: Параметры.МонопольныйРежим = Ложь, данные ИБ модифицировать нельзя;
  • если требуется изменение данных, обработчик ставит Параметры.МонопольныйРежим = Истина и завершает выполнение;
  • второй вызов: Параметры.МонопольныйРежим = Истина, данные можно модифицировать.

Если используется параллельный режим отложенного обновления (РежимВыполненияОтложенныхОбработчиков = "Параллельно"), применяйте отдельные требования к таким обработчикам.

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

Обработчик = Обработчики.Добавить();
Обработчик.РежимВыполнения = "Монопольно";
Обработчик.Версия = "11.1.0.0";
Обработчик.Процедура = "Справочник.МойСправочник.ЗаполнитьКодДляПоиска";

Пример реализации обработчика

// Обработчик обновления УТ 11.1.0.0
//
// Перебираются все элементы справочника, в которых не заполнен код для поиска,
// и заполняется кодом справочника без лидирующих нулей и префиксов.
//
Процедура ЗаполнитьКодДляПоиска() Экспорт
...
2.

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

2.1.

Процедура-обработчик должна быть экспортной.

Размещайте ее в модуле менеджера объекта метаданных, который она обновляет.

Пример: если в справочник Подразделения добавлен новый реквизит, обработчик заполнения этого реквизита размещается в модуле менеджера этого справочника.

2.2.

Если обработчик нельзя однозначно связать с конкретным объектом метаданных, допускается размещение в серверном общем модуле, тематически связанном с обработкой.

В этом случае процедура должна находиться в служебной части модуля, в подразделе Обновление ИБ.

3.

Реализация обработчиков обновления

3.1.

К процедуре-обработчику предъявляются требования:

  • не должно быть интерактивного взаимодействия с пользователем;
  • алгоритм не должен прерывать или зацикливать обработку, не должен оставлять необработанные данные и не должен требовать действий пользователя для продолжения;
  • в параллельных отложенных обработчиках нельзя вызывать исключения, которые остановят всю процедуру обновления;
  • в остальных обработчиках исключение допустимо только при критической ошибке, когда другие способы обхода проблемы исчерпаны;
  • обработчик должен быть идемпотентным: повторный запуск на тех же данных дает тот же результат и не создает дубликаты;
  • в пределах одной версии обработчики не должны зависеть от порядка выполнения; если зависимость есть, обработчики объединяют;
  • при использовании #std701: планов обмена РИБ с отборами учитывайте, что в подчиненном узле могут быть неполные данные (например, есть движения, но нет регистратора), и такие данные нужно пропускать.
3.2.

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

3.2.1.

Отключайте бизнес-логику при обработке данных. В большинстве случаев используйте признак ОбменДанными.Загрузка:

ДокументОбъект.ОбменДанными.Загрузка = Истина;

При необходимости частичного отключения логики допустим дополнительный признак:

ДокументОбъект.ДополнительныеСвойства.Вставить("ОтключитьМоюБизнесЛогику");
3.2.2.

Для большинства данных отключайте регистрацию изменений на узлах планов обмена, чтобы не отправлять весь объем обработанных данных во все узлы.

  • В РИБ обработка данных должна выполняться независимо в каждом узле.
  • При обмене между произвольными конфигурациями обработка не должна сама по себе инициировать выгрузку в базы-получатели.

Исключение: создание ссылочных объектов, которые должны переноситься механизмами обмена в другие узлы РИБ с тем же значением реквизита Ссылка.

3.2.3.

Вместо простого вызова:

ДокументОбъект.Записать();

используйте:

ДокументОбъект.ОбменДанными.Загрузка = Истина; // отключить всю бизнес-логику при записи
ДокументОбъект.ДополнительныеСвойства.Вставить("ОтключитьМеханизмРегистрацииОбъектов");
ДокументОбъект.ОбменДанными.Получатели.АвтоЗаполнение = Ложь;
ДокументОбъект.Записать();

Для БСП 2.1.4 и выше используйте процедуру ЗаписатьДанные общего модуля ОбновлениеИнформационнойБазы:

ОбновлениеИнформационнойБазы.ЗаписатьДанные(ДокументОбъект);
3.3.

Перед процедурой-обработчиком должен быть комментарий.

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

Следующие строки должны отвечать на вопросы:

  • какие данные будут изменены;
  • какие изменения будут внесены.

Пример комментария

// Обработчик обновления УТ 11.1.0.0
//
// Перебираются все элементы справочника, в которых не заполнен код для поиска,
// и заполняется кодом справочника без лидирующих нулей и префиксов.
//
Процедура ЗаполнитьКодДляПоиска() Экспорт
4.

Переход на новые версии библиотек

4.1.

При постановке конфигурации на поддержку новой версии библиотеки увеличивайте номер версии конфигурации.

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

См. также
Проверки

#acc:1363

Источник

https://its.1c.ru/db/v8std#content:690