Как написать внешнюю обработку в 1С

Внешняя обработка — это файл с расширением .epf, который выполняет прикладную логику в 1С без изменения конфигурации. Её используют, когда нужно добавить печатную форму, пакетную обработку данных, загрузку из Excel или сервисную операцию, а снимать конфигурацию с поддержки нельзя или нежелательно. Обработка запускается через меню «Файл — Открыть» или подключается к справочнику «Дополнительные отчеты и обработки» в типовых решениях на БСП.

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

Ниже — полный цикл: от создания пустой обработки в конфигураторе до подключения её в типовую конфигурацию и проверки результата. Примеры кода приведены для управляемых форм, так как именно они используются в современных конфигурациях (УТ 11, ERP, БП 3.0, ЗУП 3.1).

Что потребуется перед началом работы

Для разработки нужен конфигуратор 1С той же версии платформы, что и рабочая база. Если обработка пишется под конкретную типовую конфигурацию, открывайте конфигуратор именно этой базы — тогда будут доступны автоподстановка, проверка синтаксиса и обращение к объектам метаданных по именам.

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

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

Создание файла обработки в конфигураторе

Откройте конфигуратор нужной базы и выполните: Файл — Новый — Внешняя обработка. Появится окно с пустой структурой обработки: у неё есть модуль объекта, но нет ни одной формы. Задайте имя (например, «ЗагрузкаЦенИзExcel») и синоним — он будет отображаться пользователю.

Далее добавьте основную форму: правой кнопкой по ветке «Формы» — Добавить, тип формы — «Форма обработки», установите флажок «Назначить форму основной». Если обработка сервисная и интерфейс не нужен (например, только дополнительная печатная форма), форму можно не создавать вовсе — вся логика разместится в модуле объекта.

Сохраните файл: Файл — Сохранить как, укажите имя файла .epf. Рекомендуется сразу завести отдельный каталог для разработки и хранить там версии файлов, потому что встроенной истории изменений у внешних обработок нет.

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

Проектирование формы: реквизиты, команды, элементы

На форме обработки размещаются реквизиты (параметры, которые вводит пользователь), команды (кнопки) и элементы отображения. Например, для обработки загрузки цен понадобятся реквизиты «ПутьКФайлу» (строка), «ТипЦен» (ссылка на справочник) и таблица значений «ДанныеФайла» для предпросмотра.

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

Команда формы создаётся на закладке «Команды», затем перетаскивается в дерево элементов — так появляется кнопка. Для команды автоматически создаётся обработчик на клиенте. Помните про деление на клиентский и серверный контекст: работа с файловой системой и диалогами — на клиенте, запросы к базе и запись данных — на сервере.

Написание кода: клиент и сервер

В управляемых формах код делится директивами компиляции: &НаКлиенте, &НаСервере, &НаСервереБезКонтекста. Типовой шаблон: клиентская процедура обрабатывает нажатие кнопки и собирает параметры, затем вызывает серверную процедуру, которая выполняет основную работу с данными.

Пример минимальной логики — обработка, которая пересчитывает итоги по выбранному документу:

&НаКлиенте
Процедура ВыполнитьОбработку(Команда)
Если Не ЗначениеЗаполнено(ДокументОснование) Тогда
Сообщить("Выберите документ");
Возврат;
КонецЕсли;
КоличествоИзмененных = ВыполнитьОбработкуНаСервере(ДокументОснование);
Сообщить("Обработано строк: " + КоличествоИзмененных);
КонецПроцедуры

&НаСервереБезКонтекста
Функция ВыполнитьОбработкуНаСервере(ДокументСсылка)
ДокОбъект = ДокументСсылка.ПолучитьОбъект();
Счетчик = 0;
Для Каждого СтрокаТЧ Из ДокОбъект.Товары Цикл
СтрокаТЧ.Сумма = СтрокаТЧ.Количество * СтрокаТЧ.Цена;
Счетчик = Счетчик + 1;
КонецЦикла;
ДокОбъект.Записать();
Возврат Счетчик;
КонецФункции

Обратите внимание: серверная функция объявлена с &НаСервереБезКонтекста, поэтому она не имеет доступа к данным формы — все параметры передаются явно. Это правильный стиль: методы без контекста выполняются быстрее и проще отлаживаются. Если нужен доступ к реквизитам формы напрямую, используйте &НаСервере.

Для массовых операций используйте запросы вместо обхода выборки в цикле: один запрос с конструкцией «ВЫБРАТЬ ... ИЗ Документ.РеализацияТоваровУслуг ГДЕ Дата МЕЖДУ &Начало И &Конец» выполнится на порядки быстрее, чем поочередное получение объектов.

Модуль объекта и подключение к типовой конфигурации

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

Функция СведенияОВнешнейОбработке() Экспорт
ПараметрыРегистрации = Новый Структура;
ПараметрыРегистрации.Вставить("Вид", "ДополнительнаяОбработка");
ПараметрыРегистрации.Вставить("Версия", "1.0");
ПараметрыРегистрации.Вставить("БезопасныйРежим", Истина);
ПараметрыРегистрации.Вставить("Наименование", "Загрузка цен из файла");

Команды = Новый ТаблицаЗначений;
Команды.Колонки.Добавить("Идентификатор");
Команды.Колонки.Добавить("Представление");
Команды.Колонки.Добавить("Использование");
Команды.Колонки.Добавить("ПоказыватьОповещение");

Команда = Команды.Добавить();
Команда.Идентификатор = "ОткрытьОбработку";
Команда.Представление = "Загрузка цен из файла";
Команда.Использование = "ОткрытиеФормы";
Команда.ПоказыватьОповещение = Ложь;

ПараметрыРегистрации.Вставить("Команды", Команды);
Возврат ПараметрыРегистрации;
КонецФункции

Значения поля «Вид» стандартизированы БСП: ДополнительнаяОбработка, ДополнительныйОтчет, ЗаполнениеОбъекта, СозданиеСвязанныхОбъектов, ПечатнаяФорма. От вида зависит, где появится команда: в разделе «Дополнительные обработки», в кнопке «Заполнение» документа или в меню «Печать».

Дополнительная печатная форма

Для печатной формы вид указывается «ПечатнаяФорма», добавляется колонка «МенеджерПечати» с именем объекта (например, «Документ.РеализацияТоваровУслуг»), а в модуле объекта реализуется процедура Печать(МассивОбъектов, КоллекцияПечатныхФорм, ОбъектыПечати, ПараметрыВывода). В ней формируется табличный документ и помещается в коллекцию печатных форм.

Глобальная обработка без БСП

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

Способы расширения функциональности

Внешняя обработка (.epf)

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

Расширение конфигурации

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

Доработка конфигурации

Крайний вариант: полная свобода, но усложняет обновление. Используйте только если расширение не покрывает задачу.

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

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

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

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

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

Открытие обработки

Норма

Форма открывается без ошибок, реквизиты доступны для ввода

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

Ошибка компиляции модуля или «Объект не найден» при открытии

Выполнение под пользователем

Норма

Обработка отрабатывает под учётной записью с рабочими правами

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

Ошибка «Нарушение прав доступа» у рядовых пользователей

Изменение данных

Норма

Изменено ожидаемое число объектов, значения корректны

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

Затронуты лишние объекты или данные частично не записались

Подключение через БСП

Норма

Обработка появилась в списке и запускается из интерфейса

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

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

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

Самая частая ошибка новичков — попытка обратиться к данным базы из клиентской процедуры. В управляемом приложении на клиенте недоступны запросы, менеджеры объектов и прямая запись: код «Документы.Реализация.НайтиПоНомеру()» в процедуре &НаКлиенте не скомпилируется. Вся работа с базой — только на сервере.

Вторая группа ошибок связана с транзакциями. Если обработка изменяет много объектов, оборачивайте массовые операции в транзакцию (НачатьТранзакцию / ЗафиксироватьТранзакцию / ОтменитьТранзакцию) либо осознанно пишите пообъектно с обработкой исключений — иначе при сбое в середине получите частично обработанные данные.

Третья типичная проблема — переносимость. Обработка, написанная под одну конфигурацию, не заработает в другой, если там иначе называются реквизиты или объекты. Перед переносом проверьте все обращения к метаданным, а лучше — разрабатывайте и тестируйте непосредственно в целевой конфигурации.

FAQ

Чем внешняя обработка отличается от внешнего отчёта?

Технически — расширением файла (.epf против .erf) и назначением. Отчёт строится на СКД и предназначен для вывода данных, обработка — для действий над данными. В БСП они регистрируются с разными видами: ДополнительныйОтчет и ДополнительнаяОбработка.

Можно ли написать внешнюю обработку без конфигуратора?

Нет, файл .epf создаётся только конфигуратором. Альтернатива — внешний отчёт на СКД, который тоже требует конфигуратора. Для совсем простых задач иногда достаточно стандартной групповой обработки «Групповое изменение реквизитов», встроенной в типовые конфигурации.

Почему типовая конфигурация не принимает файл обработки?

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

Как обновить обработку, уже подключённую к базе?

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

Работает ли внешняя обработка в веб-клиенте?

Да, если код написан с учётом ограничений веб-клиента: недоступны прямая работа с файловой системой без расширения работы с файлами, COM-объекты и некоторые другие возможности. Тестируйте обработку именно в том клиенте, которым пользуются сотрудники.

Можно ли запускать внешнюю обработку по расписанию?

Напрямую — нет, внешние обработки не поддерживают регламентные задания. Обходные пути: регламентное задание БСП для дополнительных обработок с видом выполнения «ВызовСервернойПроцедуры», либо запуск через пакетный режим 1С с параметром /Execute.