Отладка серверного кода 1С 8.3: агент с ключом -debug, конфигуратор и точки останова

Серверная отладка в клиент-серверной 1С включается ключом -debug в строке запуска агента сервера ragent.exe, после чего службу нужно перезапустить. Затем в конфигураторе разрешают автоподключение предметов отладки «Сервер», и точки останова в процедурах &НаСервере начинают срабатывать.

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

Что проверить до включения отладки на сервере

Включение серверной отладки требует перезапуска службы агента. Подготовьте окружение заранее, чтобы не делать это дважды.

• 🖥️ Доступ к серверу. Нужны права локального администратора на Windows или sudo на Linux: придётся править параметры службы.
• 🔢 Версия платформы. Конфигуратор, из которого вы отлаживаете, должен быть той же версии, что и сервер, вплоть до последней цифры номера. При расхождении клиент просто не подключится к кластеру.
• 👤 Пользователь базы. Отлаживать удобнее под пользователем с полными правами, иначе часть кода просто не выполнится.
• 🔌 Сеть. Между машиной с конфигуратором и сервером 1С должны быть открыты порты. Для протокола TCP это порт отладчика на вашей машине (по умолчанию 1560), для HTTP это порт сервера отладки (по умолчанию 1550).
• 🧪 Какой сервер. Лучше всего отлаживать на тестовом сервере с копией базы.

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

Шаг 1. Добавляем ключ -debug в службу агента кластера

Ключ указывают в командной строке процесса ragent. Остальные параметры менять не нужно.

Windows: правка параметров службы

1. Откройте services.msc и найдите службу агента сервера 1С. Обычно она называется «Агент сервера 1С:Предприятия 8.3 (x86-64)». Посмотрите её «Имя службы» на вкладке «Общие»: оно понадобится дальше.
2. Остановите службу.
3. Откройте редактор реестра regedit и перейдите в ветку HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\<имя службы>.
4. Откройте параметр ImagePath и добавьте -debug после пути к ragent.exe.
5. Запустите службу.

Строка до и после правки выглядит примерно так (путь и версия у вас свои):

"C:\Program Files\1cv8\8.3.24.1548\bin\ragent.exe" -srvc -agent -regport 1541 -port 1540 -range 1560:1591 -d "C:\Program Files\1cv8\srvinfo"

"C:\Program Files\1cv8\8.3.24.1548\bin\ragent.exe" -debug -srvc -agent -regport 1541 -port 1540 -range 1560:1591 -d "C:\Program Files\1cv8\srvinfo"

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

💡 Если вы ставите сервер заново, ключ можно не вписывать вручную. При установке сервера как службы через ragent -instsrvc достаточно указать -debug среди параметров, и он сразу попадёт в строку запуска.

Linux: systemd или init-скрипт

Порядок зависит от того, как установлен сервер.

Имя юнита покажет команда:

systemctl list-units --type=service | grep -i 1c

TCP или HTTP: выбираем протокол

У отладки 1С 8.3 два протокола. Голый ключ -debug включает протокол TCP. Для HTTP пишут -debug -http.

Протокол в конфигураторе должен совпадать с протоколом сервера. Если сервер запущен с -debug -http, а конфигуратор настроен на TCP, сервер в списке предметов отладки не появится.

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

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

На Windows в PowerShell:

Get-CimInstance Win32_Process -Filter "name='ragent.exe'" | Select-Object CommandLine

Можно и без консоли: в «Диспетчере задач» на вкладке «Подробности» включите столбец «Командная строка».

На Linux:

ps -ef | grep ragent

В выводе должен быть ключ -debug, а для HTTP ещё и -http. При протоколе HTTP на сервере дополнительно появится процесс dbgs, он и есть сервер отладки.

Шаг 3. Запускаем базу в режиме предприятия с отладкой

В конфигураторе откройте Сервис → Параметры, вкладка «Отладка». Выберите тот же протокол, что и на сервере. Для HTTP укажите адрес сервера отладки, например http://srv1c:1550.

Дальше есть три способа запустить клиент так, чтобы он сразу был подключён к отладчику.

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

Меню Отладка → Начать отладку → Тонкий клиент или клавиша F5. Конфигуратор сам запускает клиента с нужными параметрами и подключает его. Это самый быстрый путь, когда отлаживаете у себя.

Из стартера с параметром /DEBUG

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

"C:\Program Files\1cv8\common\1cestart.exe" ENTERPRISE /S"srv1c\buh" /DEBUG /DEBUGGERURL"tcp://dev-pc:1560"

Для HTTP адрес отладчика будет вида http://srv1c:1550. Те же параметры можно вписать в настройках базы в окне запуска: кнопка «Изменить», последняя страница мастера, поле «Дополнительные параметры запуска».

Когда ошибка воспроизводится только у пользователя

Попросите пользователя закрыть программу и запустите её с его рабочего места с параметрами /DEBUG и /DEBUGGERURL, как показано выше. Удобно сделать на рабочем столе отдельный ярлык с этими ключами и пользоваться им только на время разбора.

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

Шаг 4. Подключаем серверные предметы отладки и ставим точки останова

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

Автоподключение сервера

Откройте Отладка → Подключение. В окне видны предметы, уже подключённые к отладчику. Нажмите «Автоматическое подключение» и отметьте:

• ✅ Сервер — для серверных вызовов из клиентских сеансов;
• ✅ Фоновое задание — если отлаживаете регламентные и фоновые задания;
• ✅ Тонкий клиент — чтобы видеть и клиентскую часть.

После этого при первом серверном вызове из базы серверный предмет сам появится в списке. Если его нет, вернитесь к шагу 2: почти всегда причина в ключе или протоколе.

Точки останова

• 🔴 Обычная — F9 на нужной строке модуля.
• 🟡 С условием — Shift+Alt+F9. Условие пишется на встроенном языке, например Документ.Номер = "00-000123". Отладчик остановится только на нужном документе, а не на каждом из тысячи.
• ⛔ Остановка по ошибке — Отладка → Остановка по ошибке. Отладчик встанет на той строке, где возникло исключение, даже если оно перехвачено в Попытка ... Исключение. Это самый быстрый способ найти источник ошибки, текст которой «теряется» в цепочке вызовов.

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

Шаг 5. Разбираем значения переменных и стек вызовов

Когда выполнение остановилось, жёлтая стрелка показывает текущую строку. Дальше работают клавиши пошагового выполнения.

Вычисление выражений и табло

Окно «Вычислить выражение» (Shift+F9) принимает любое выражение на встроенном языке. Туда можно ввести не только имя переменной, но и Выборка.Количество(), Запрос.Текст или ЗначениеЗаполнено(Контрагент).

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

Табло (Отладка → Табло) держит список выражений постоянно и обновляет их на каждом шаге. Сюда удобно вынести 3–5 переменных, за которыми следите в цикле.

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

Стек вызовов

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

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

Замер производительности

На той же паре «сервер + отладчик» работает замер производительности: Отладка → Замер производительности. Он показывает, сколько раз выполнилась каждая строка и сколько времени заняла, включая серверные вызовы. Если задача не «где ошибка», а «почему медленно», начинайте с замера, а не с пошаговой отладки.

Почему серверная отладка не срабатывает: разбор частых проблем

Частые вопросы