Как передать параметр в фоновое задание 1С

Фоновые задания в 1С позволяют выполнять длительные операции — загрузку данных, расчёты, формирование отчётов — без блокировки интерфейса пользователя. Почти всегда такой операции нужны входные данные: период отчёта, ссылка на документ, настройки обмена. Передача параметров в фоновое задание выполняется через метод ФоновыеЗадания.Выполнить(), у которого есть свои правила и ограничения.

Главное правило: параметры передаются как массив значений, и они должны быть сериализуемыми — то есть платформа должна уметь упаковать их и распаковать в сеансе фонового задания. Нарушение этого правила — самая частая причина ошибок при запуске фоновых задач.

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

Синтаксис запуска фонового задания с параметрами

Запуск фонового задания выполняется на сервере методом глобального контекста ФоновыеЗадания.Выполнить(). Метод принимает четыре аргумента: имя процедуры или метода общего модуля, массив параметров, уникальный ключ и наименование задания. Именно второй аргумент — массив — и содержит передаваемые параметры.

Имя процедуры указывается строкой в формате "ИмяОбщегоМодуля.ИмяЭкспортнойПроцедуры". Процедура должна быть экспортной и располагаться в серверном общем модуле (или в модуле менеджера объекта). Ключ задания нужен для контроля уникальности: два активных задания с одинаковым ключом и именем метода одновременно запустить нельзя — платформа выдаст ошибку.

Процедура ЗапуститьОбработкуНаСервере(Период, Организация)

ПараметрыПроцедуры = Новый Массив;
ПараметрыПроцедуры.Добавить(Период);
ПараметрыПроцедуры.Добавить(Организация);

ФоновыеЗадания.Выполнить(
"ДлительныеОперацииСервер.ВыполнитьОбработкуДанных",
ПараметрыПроцедуры,
Новый УникальныйИдентификатор,
"Обработка данных за период");

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

В общем модуле процедура объявляется с параметрами в том же порядке, в каком они добавлены в массив:

Процедура ВыполнитьОбработкуДанных(Период, Организация) Экспорт

// Логика обработки

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

Какие типы данных можно передавать

Платформа сериализует параметры при передаче в фоновый сеанс, поэтому подходят не все типы. Безопасный набор: примитивные типы (строка, число, дата, булево), ссылки на объекты базы данных, структуры, массивы, соответствия, списки значений, таблицы значений, хранилище значения, уникальный идентификатор.

Нельзя передавать объекты, привязанные к текущему сеансу: данные форм, элементы формы, COM-объекты, объекты типа «Запрос» с открытыми соединениями, временные таблицы менеджера временных таблиц. Попытка передать такой объект приведёт к ошибке сериализации ещё на этапе запуска задания.

Ссылки передаются безопасно: в фоновом сеансе они остаются валидными, и по ним можно получать объект для записи. Но если нужно передать большой набор данных (например, результат сложного отбора), эффективнее передать параметры отбора и выполнить запрос уже внутри фонового задания, чем гонять сериализованную таблицу значений через границу сеансов.

Сравнение способов передачи данных

Примитивные значения и ссылки

Самый надёжный вариант. Минимальные накладные расходы, нет риска ошибок сериализации.

Структуры и массивы

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

Таблица значений

Подходит для небольших наборов данных. Большие таблицы замедляют запуск задания из-за сериализации.

Адрес временного хранилища

Для больших данных: положить данные в хранилище на сервере, передать только адрес-строку. В фоновом задании получить по адресу.

Передача сложных данных через структуру и хранилище

Когда параметров много, удобнее упаковать их в структуру и передать одним элементом массива. Это упрощает сигнатуру процедуры и снижает риск перепутать порядок аргументов.

ПараметрыОбработки = Новый Структура;
ПараметрыОбработки.Вставить("ДатаНачала", ДатаНачала);
ПараметрыОбработки.Вставить("ДатаОкончания", ДатаОкончания);
ПараметрыОбработки.Вставить("Организация", Организация);
ПараметрыОбработки.Вставить("СписокСкладов", СписокСкладов);

ПараметрыПроцедуры = Новый Массив;
ПараметрыПроцедуры.Добавить(ПараметрыОбработки);

ФоновыеЗадания.Выполнить("ОбработкиСервер.СформироватьДанные", ПараметрыПроцедуры);

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

АдресХранилища = ПоместитьВоВременноеХранилище(ТаблицаДанных, Новый УникальныйИдентификатор);

ПараметрыПроцедуры = Новый Массив;
ПараметрыПроцедуры.Добавить(АдресХранилища);

ФоновыеЗадания.Выполнить("ЗагрузкаДанныхСервер.ОбработатьТаблицу", ПараметрыПроцедуры);

Как получить результат из фонового задания

Фоновое задание не возвращает значение напрямую — вызов ФоновыеЗадания.Выполнить() лишь ставит задачу в очередь. Стандартный приём возврата результата: передать в параметрах адрес временного хранилища, в которое фоновая процедура по завершении поместит результат.

Процедура СформироватьДанные(ПараметрыОбработки, АдресРезультата) Экспорт

Результат = Новый Структура;
Результат.Вставить("Успешно", Истина);
Результат.Вставить("ОбработаноЗаписей", 150);

ПоместитьВоВременноеХранилище(Результат, АдресРезультата);

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

На клиенте или в вызывающем коде остаётся дождаться завершения задания и забрать результат по адресу. В типовых конфигурациях для этого используется подсистема «Длительные операции» (БСП): функция ДлительныеОперации.ВыполнитьВФоне() сама формирует массив параметров, создаёт хранилище результата и умеет ожидать завершения с выводом индикатора пользователю.

1. 1
   Создайте экспортную процедуру в серверном общем модуле с нужными параметрами
2. 2
   В вызывающем коде сформируйте массив и добавьте параметры в том же порядке
3. 3
   При необходимости добавьте в массив адрес временного хранилища для результата
4. 4
   Вызовите ФоновыеЗадания.Выполнить() с именем метода, массивом, ключом и наименованием
5. 5
   Внутри процедуры поместите результат во временное хранилище по переданному адресу
6. 6
   Дождитесь завершения задания и получите результат из хранилища

Отладка и контроль выполнения

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

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

Полезная практика — в начале фоновой процедуры записывать в журнал регистрации полученные параметры (в разумном объёме). Это позволяет быстро установить, дошли ли данные до задания и в том ли виде, который ожидался.

Контрольные точки

Как проверить результат

Состояние задания в консоли фоновых заданий

Норма

Статус «Завершено»

Тревожный признак

Статус «Ошибка» — смотрите ИнформацияОбОшибке

Содержимое временного хранилища по адресу результата

Норма

По адресу лежит ожидаемая структура или значение

Тревожный признак

Неопределено — задание не записало результат

Журнал регистрации

Норма

Нет ошибок сеанса фонового задания

Тревожный признак

Ошибки сериализации или несоответствия параметров

Типичные ошибки и ограничения

Самая частая ошибка — попытка передать несериализуемый объект: данные формы, табличный документ, привязанный к форме, COM-объект. Платформа выбрасывает исключение сразу при вызове Выполнить(), поэтому проблема диагностируется легко.

Вторая по частоте — несовпадение числа параметров: в массив добавили два значения, а процедура объявлена с тремя, или наоборот. Третья — передача «тяжёлой» таблицы значений вместо адреса хранилища, что замедляет запуск и расходует память. Наконец, часто забывают, что фоновое задание выполняется под правами того же пользователя, но без интерактивного контекста: вызовы Вопрос(), Предупреждение() или открытие форм внутри задания приведут к ошибке.

Если конфигурация построена на БСП, предпочтительнее использовать ДлительныеОперации.ВыполнитьВФоне() вместо прямого вызова ФоновыеЗадания.Выполнить(): библиотека сама управляет ключами, хранилищем результата, ожиданием и сообщениями об ошибках пользователю.

FAQ

Можно ли передать в фоновое задание таблицу значений?

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

Почему возникает ошибка «Несоответствие числа параметров»?

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

Можно ли передать ссылку на документ?

Да, ссылки передаются без ограничений и остаются валидными в фоновом сеансе. Внутри задания по ссылке можно получить объект вызовом ПолучитьОбъект() и изменить его с записью в базу.

Как вернуть результат из фонового задания?

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

Можно ли передать структуру с вложенными структурами?

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

Что делать, если фоновое задание завершается с ошибкой сразу после запуска?

Откройте консоль фоновых заданий или журнал регистрации и посмотрите текст ошибки. Чаще всего это ошибка сериализации параметра, неверное имя метода или процедура, объявленная не как экспортная в серверном общем модуле.