Отладка 1С

Адаптер отладки скачивается сам при первом запуске.

Расширение регистрирует отладчик 1Cpt: Enterprise Debugger (тип 1c-platform-tools) и работает через onec-debug-adapter — адаптер скачивается и обновляется автоматически при первом запуске отладки.

Требования

• Платформа 1С:Предприятие — для запуска клиента и локального сервера отладки (dbgs).
• Исходный код конфигурации в проекте: формат конфигуратора или формат EDT, каталог расширение находит само. Когда проектов в окне несколько, отладка идёт в проекте, где лежит rootProject.

Настройка

1. Строка подключения — из активного профиля запуска

Строка подключения, учётные данные и версия платформы берутся из активного профиля запуска (env.json для vrunner 2, autumn-properties.json для vrunner 3) — отдельно в launch.json их указывать не нужно. В файле профиля задайте подключение к ИБ:

// env.json (vrunner 2)
{ "default": { "--ibconnection": "/F./build/ib" } }

// autumn-properties.json (vrunner 3)
{ "vrunner": { "ibconnection": "/F./build/ib" } }

• /F<путь> — файловая ИБ (относительный путь достраивается от корня проекта);
• /S<сервер>\<база> — серверная ИБ.

Для автоматического входа в предприятие там же можно указать пользователя и пароль ИБ (db-user/db-pwd). Смена активного профиля меняет и параметры отладки.

2. Конфигурация запуска — launch.json

Откройте панель Run and Debug (Ctrl+Shift+D) → create a launch.json file → выберите 1Cpt: Enterprise Debugger.

Расширение сгенерирует конфигурацию по найденным каталогам исходного кода:

{
  "name": "Отладка 1С (запуск)",
  "type": "1c-platform-tools",
  "request": "launch",
  "platformPath": "${env:PROGRAMFILES}/1cv8",
  "rootProject": "${workspaceFolder}/src/cf",
  "debugServerHost": "localhost",
  "autoAttachTypes": ["ManagedClient", "Server"],
  "extensions": ["${workspaceFolder}/src/cfe/МоёРасширение", "${workspaceFolder}/tests/cfe/yaxunit-test"],
  "externalFilesSrc": ["${workspaceFolder}/src/epf", "${workspaceFolder}/src/erf"],
  "externalFilesBuilds": ["${workspaceFolder}/build/out/epf", "${workspaceFolder}/build/out/erf"]
}

Параметр	Назначение
rootProject	каталог исходного кода конфигурации: формат конфигуратора или формат EDT
extensions	каталоги исходников расширений (по одному на расширение): и решения, и тестовых из tests/cfe - иначе в тест не зайти точкой останова
platformPath	каталог с установленными версиями платформы 1С
platformVersion	конкретная версия платформы (необязательно — по умолчанию берётся --v8version активного профиля, сведённая к конкретной сборке; иначе последняя)
debugServerHost, debugServerPort	адрес HTTP-сервера отладки для серверной ИБ (порт по умолчанию 1550); для файловой ИБ сервер отладки запускается автоматически
autoAttachTypes	какие предметы отладки подключать автоматически: ManagedClient, Client, WebClient, MobileClient, Server, ServerEmulation, Job (фоновое задание), JobFileMode, WebService, HttpService, OData, ComConnector
user, password	автовход в предприятие (если не заданы — берутся db-user/db-pwd активного профиля)
externalFilesSrc	каталоги исходников внешних обработок и отчётов: формат конфигуратора или проект EDT
externalFilesBuilds	каталоги собранных .epf/.erf (обязательны для точек останова во внешних файлах)

Запуск и завершение сессии

1. Откройте Run and Debug (Ctrl+Shift+D).
2. Выберите конфигурацию Отладка 1С (запуск) и нажмите F5.

Что произойдёт: для файловой ИБ адаптер сам запустит локальный сервер отладки (dbgs) и клиент 1С:Предприятие; при заданных учётных данных вход выполнится автоматически. Предметы отладки из autoAttachTypes подключаются сами.

Завершение — Shift+F5 или кнопка ⏹ на панели отладки. Сессия закрывается, клиент 1С продолжает работать.

Изменение autoAttachTypes в launch.json во время активной сессии применяется сразу, без перезапуска.

Предметы отладки (Debug targets)

Во время сессии в панели Run and Debug появляется вид Цели отладки — список доступных, но не подключённых предметов отладки (тип, сеанс, пользователь).

• Кнопка Connect в заголовке вида подключает выбранный предмет вручную — например, фоновое задание, если Job не входит в autoAttachTypes.
• Список обновляется автоматически при появлении новых сеансов.

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

Точка ставится кликом слева от номера строки в .bsl-файле или клавишей F9.

Автоперенос на исполняемую строку. Точка, поставленная на пустой строке, комментарии, директиве (&НаКлиенте) или команде препроцессора (#Если), автоматически переносится вниз на ближайшую исполняемую строку — маркер сразу сдвигается в редакторе. Если исполняемых строк ниже нет (хвост модуля), точка серверу не отправляется и помечается как непроверенная.

Условная точка. ПКМ по области точек → Add Conditional Breakpoint (Добавить условную точку останова):

• Expression — выражение на языке 1С (например Сумма > 1000); останов произойдёт, только когда оно Истина;
• Hit Count — число проходов через точку, по достижении которого произойдёт останов.

Точка логирования (logpoint). ПКМ по области точек → Add Logpoint. Текст сообщения выводится в Debug Console без остановки выполнения; выражения подставляются в фигурных скобках:

Обработка {Ссылка}: сумма = {Объект.Сумма}

У существующей точки всё это редактируется через ПКМ по маркеру → Edit Breakpoint.

Отладка расширений конфигурации

Укажите каталоги исходников расширений в extensions. Точки ставятся в модулях расширения как обычно.

Дополнительно работает зеркалирование: если процедура базовой конфигурации перехвачена расширением (&Вместо, &ИзменениеИКонтроль), точка, поставленная в базовом модуле, автоматически дублируется в процедуру-заместитель — иначе она бы молча не срабатывала, потому что базовый код не выполняется. Для &После/&Перед зеркальная точка ставится на первую строку дополняющей процедуры.

Отладка внешних обработок и отчётов

Сервер отладки 1С адресует внешние файлы по пути к собранному .epf/.erf, поэтому нужны и исходники, и собранный файл:

1. Исходники — в каталогах из externalFilesSrc.
2. Собранный файл — в каталоге из externalFilesBuilds; имя файла должно совпадать с именем обработки или отчёта (МояОбработка.xml или МояОбработка.mdo → build/out/epf/МояОбработка.epf). Собрать можно командой Собрать обработки / Собрать отчёты (дерево 1С: Инструменты → Внешние файлы).
3. Точки ставятся прямо в исходниках (.bsl модулей и форм обработки).
4. Откройте обработку в предприятии — остановы работают как в конфигурации: переменные, шаги, вычисления.

Если собранного файла нет, точки этой обработки помечаются непроверенными и серверу не отправляются.

Управление выполнением

Действие	Клавиша
Продолжить	F5
Шаг через (не заходя в вызов)	F10
Шаг внутрь	F11
Шаг наружу (до выхода из процедуры)	Shift+F11
Остановить сессию	Shift+F5

Остановка по ошибке. В панели Run and Debug → раздел Breakpoints включите флажок Остановка по ошибке — выполнение будет останавливаться при исключениях времени выполнения. ПКМ по флажку → Edit Condition позволяет задать подстроку: останов только если текст ошибки её содержит.

Просмотр переменных

При останове панель Variables показывает переменные текущего кадра стека.

• Составные значения (структуры, массивы, таблицы значений, объекты) раскрываются стрелкой слева.
• Соответствие раскрывается в пары «ключ = значение»; значение-объект раскрывается дальше.
• Панель Call Stack показывает стек вызовов — клик по кадру переключает контекст переменных. Клиент и сервер — отдельные элементы списка (предметы отладки), у каждого свой стек.
• Показать значение в окне: ПКМ по переменной в Variables или Watch → Показать значение в окне — полное (неусечённое) значение открывается в отдельной вкладке редактора. Удобно для длинных строк, XML, JSON.

Изменение значений переменных

1. Остановитесь на точке.
2. В панели Variables дважды кликните по значению переменной (или ПКМ → Set Value, или F2).
3. Введите выражение на языке 1С — Истина, 123, "строка", ТекущаяДата(), Новый Массив — и нажмите Enter.

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

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

• Watch: панель Watch → + → выражение 1С. Пересчитывается на каждом останове и шаге.
• Наведение: при останове наведите курсор на переменную в коде — всплывёт её значение.
• Debug Console: внизу в консоли отладки можно ввести любое выражение 1С и получить результат (только при останове — нужен контекст кадра).

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

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

1. Запустите сессию отладки.
2. На панели отладки (между «шагом наружу» и «перезапуском») нажмите кнопку замера (значок спидометра) — или команду 1С: Отладка: Начать замер производительности. В статус-баре появится «Замер производительности…».
3. Выполните в 1С исследуемые действия (открытие формы, проведение документа).
4. Нажмите ту же кнопку (теперь значок остановки) — или 1С: Отладка: Закончить замер производительности.

Результаты:

• Таблица «Замер производительности» откроется автоматически: модуль, строка, код, количество выполнений, время (с вложенными вызовами и без), доля от общего времени, признак серверного вызова. Клик по заголовку сортирует, поле фильтра ищет по модулю и коду, двойной клик по строке открывает модуль на этой строке.
• Колонка слева от кода в модулях: 410 × 8.3 мс · 0.6 % (⚡ — был серверный вызов). Подробности — при наведении.
• Статус-бар показывает общее время; клик открывает таблицу повторно (или команда 1С: Отладка: Показать результаты замера производительности).

Скрыть всё — команда 1С: Отладка: Скрыть результаты замера производительности. При завершении сессии замер выключается сам.

Диагностика

Логи расширения и адаптера пишутся в Output → канал 1C: Platform Tools, компонент отладки помечен [dap].

Адаптер отладки расширение загружает само. Для Windows x64, Linux x64 и macOS в релизе есть сборки с рантаймом .NET внутри, устанавливать его не нужно; на Linux рантайму нужен системный пакет libicu, в большинстве дистрибутивов он уже стоит. Для остальных систем берётся универсальная сборка, ей нужен установленный .NET 8 Runtime; в этом случае в логе видно, что адаптер запускается через dotnet.

Если процесс адаптера завершается аварийно, расширение показывает уведомление с кодом возврата и пишет ту же строку в Output: сессия отладки не закрывается молча.

Чтобы адаптер передавал подробную трассировку (отправляемые точки останова, переносы строк, остановы, замер), задайте каналу 1C: Platform Tools уровень логирования Debug или подробнее: в панели Output выберите канал и нажмите шестерёнку «Set Log Level…» (либо команда Developer: Set Log Level…). При сообщении об ошибке отладки включите Debug, повторите сценарий и приложите вывод к issue.

Тонкая настройка адаптера

Необязательные параметры launch.json для нестандартных окружений:

Параметр	По умолчанию	Назначение
calcWaitingTimeMs	100	время ожидания результата вычислений сервером отладки (25–5000); увеличьте на медленных серверах, если переменные и выражения приходят пустыми
variablesRetryDelaysMs	[50, 100, 150]	паузы повторов при пустом списке локальных переменных сразу после останова
debugPollMinDelayMs	25	минимальная пауза опроса сервера отладки
debugPollMaxDelayMs	200	максимальная пауза опроса (адаптивный бэкофф при простое)