Как выполнить процедуру на сервере в 1С

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

Механизм строится на директивах компиляции: &НаКлиенте, &НаСервере, &НаСервереБезКонтекста. Они указывают платформе, где будет скомпилирован и выполнен каждый метод модуля формы. Из клиентской процедуры можно вызвать серверную — платформа сама выполнит серверный вызов, упакует параметры и вернёт результат. Обратный вызов (с сервера на клиента) в общем случае невозможен.

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

Где выполняется код: клиент и сервер в 1С

В файловом варианте работы «сервером» условно считается сам процесс клиентского приложения, и разделение кода почти не ощущается. В клиент-серверном варианте тонкий клиент не имеет прямого доступа к СУБД: любой запрос к базе требует обращения к серверу 1С:Предприятия по сети. Каждый такой вызов — это передача данных, ожидание и нагрузка на сервер.

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

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

Как объявить серверную процедуру в модуле формы

Откройте модуль управляемой формы и добавьте процедуру с директивой &НаСервере. Внутри неё доступны реквизиты формы, данные основного реквизита (например, объекта документа) и вся серверная функциональность: запросы, менеджеры объектов, транзакции.

Пример простейшей серверной процедуры, заполняющей реквизит формы:

&НаСервере
Процедура ЗаполнитьОстаткиНаСервере()
Запрос = Новый Запрос;
Запрос.Текст = "ВЫБРАТЬ Товары.Номенклатура КАК Номенклатура,
|Товары.КоличествоОстаток КАК Остаток
|ИЗ РегистрНакопления.ТоварыНаСкладах.Остатки КАК Товары";
РезультатЗапроса = Запрос.Выполнить().Выгрузить();
ТаблицаОстатков.Загрузить(РезультатЗапроса);
КонецПроцедуры

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

1. 1
   Откройте модуль управляемой формы в конфигураторе
2. 2
   Добавьте процедуру с директивой &НаСервере или &НаСервереБезКонтекста
3. 3
   Разместите внутри код работы с данными: запросы, чтение и запись объектов
4. 4
   Вызовите процедуру из клиентского обработчика по имени
5. 5
   Проверьте выполнение через отладку с включённой отладкой серверных вызовов

Вызов серверной процедуры из клиентского кода

Самый частый сценарий — обработчик события формы или команды выполняется на клиенте, а работа с данными нужна на сервере. Вызов выглядит как обычное обращение к процедуре по имени — платформа сама распознаёт серверный вызов.

&НаКлиенте
Процедура ЗаполнитьОстатки(Команда)
ЗаполнитьОстаткиНаСервере();
Элементы.ТаблицаОстатков.Обновить();
КонецПроцедуры

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

Если серверная процедура используется только как обработчик команды формы, клиентскую «прокладку» можно не писать: в свойствах команды укажите обработчик с директивой &НаСервере, и нажатие кнопки сразу приведёт к серверному вызову. Это сокращает код, но лишает возможности выполнить чисто клиентские действия (например, вопрос пользователю) до обращения к серверу.

&НаКлиенте
Процедура КомандаРассчитать(Команда)
    Сумма = РассчитатьИтогНаСервере(Объект.Ссылка);
    ПоказатьОповещениеПользователя("Итог: " + Сумма);
КонецПроцедуры

&НаСервереБезКонтекста
Функция РассчитатьИтогНаСервере(ДокументСсылка)
    Возврат ДокументСсылка.Товары.Итог("Сумма");
КонецФункции

Контекст или &НаСервереБезКонтекста: что выбрать

Контекстный серверный вызов (&НаСервере) передаёт на сервер все данные формы и возвращает их обратно. При большой форме с тяжёлыми табличными частями это заметный объём трафика. Бесконтекстный вызов передаёт только явно указанные параметры, поэтому работает быстрее, но внутри такой процедуры недоступны реквизиты и элементы формы — только переданные параметры.

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

Серверные процедуры в общих модулях

Когда одна и та же логика нужна в нескольких формах или вызывается из подсистем без формы, её выносят в общий модуль. Чтобы модуль выполнялся на сервере и был доступен для вызова с клиента, в его свойствах должны быть установлены флаги «Сервер» и «Вызов сервера». Флаг «Клиент (управляемое приложение)» при этом снимается.

Вызов из клиентского кода выглядит так:

&НаКлиенте
Процедура ПровестиДокументы(Команда)
КоличествоПроведённых = ОбработкаДокументов.ПровестиЗаПериод(НачалоПериода, КонецПериода);
ПоказатьОповещениеПользователя("Проведено документов: " + КоличествоПроведённых);
КонецПроцедуры

В экспортных методах серверного общего модуля недопустимы типы, доступные только на клиенте, и обращения к интерфейсу. Также помните, что параметры, передаваемые с клиента, должны быть сериализуемыми: ссылки, примитивные типы, структуры, массивы. Объекты типа «ДокументОбъект» между клиентом и сервером не передаются — передавайте ссылку.

Передача параметров и возврат результата

Параметры в серверную процедуру передаются так же, как в обычную, но с ограничением на сериализуемость типов. Параметры, объявленные с ключевым словом Знач, копируются; без него изменения изменяемых параметров могут быть возвращены клиенту, однако полагаться на это при работе через веб-клиент не стоит — надёжнее возвращать результат через функцию.

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

&НаСервереБезКонтекста
Функция ПолучитьДанныеКонтрагента(КонтрагентСсылка)
Результат = Новый Структура;
Результат.Вставить("ИНН", КонтрагентСсылка.ИНН);
Результат.Вставить("КПП", КонтрагентСсылка.КПП);
Возврат Результат;
КонецФункции

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

Проверка выполнения и типичные ошибки

Чтобы убедиться, что код выполняется именно на сервере, включите в конфигураторе отладку серверных вызовов: меню «Сервис → Параметры», флажки отладки по протоколу и разрешение отладки. В кластере серверов отладка должна быть разрешена при запуске службы агента (ключ -debug). После этого точки останова внутри серверных процедур начнут срабатывать.

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

Часто задаваемые вопросы