debug
Запуск серверного модуля Pilot (*.servext.dll) на машине разработчика под отладчиком.
Модуль получает настоящие IModifierBase / IModifierBackend, подключённые к серверу Pilot
под учёткой разработчика, - точки останова в Visual Studio работают на реальных данных.
Доступ к машине с Docker не нужен, сервер не останавливается.
Требуется .NET 8 Runtime (утилита публикуется не самодостаточной) и сетевой доступ к серверу Pilot.
Без веб-админки
Утилита подключается к серверу Pilot напрямую, админка для неё не обязательна: она только выдаёт готовый
debug.json и zip. Без неё соберите утилиту сами (dotnet publish -c Release) и задайте всё в
debug.json вручную (образец - debug.example.json) или ключами:
debug --server http://сервер:порт/база --login admin --source <guid> --module bin/Debug/Имя.servext.dll
Как пользоваться
Скачать
debug.zipв админке («Серверные модули» / «Локальная отладка») и распаковать, например, вC:\Tools\debug.В админке у активности нажать «Отладить локально» / debug.json (можно указать Id объекта). Галочка «Записывать изменения на сервер» ставит в файле
"apply": true; без неё - только просмотр. Файл не отправляйте и не коммитьте с"apply": true: запись перед запуском подтверждается, но флаг лучше включать осознанно. Положить файл в папку проекта модуля. В нём адрес сервера контура, ваш логин иparams/sourceTypes/whenиз автоматизаций контура. Пароля в файле нет.Properties/launchSettings.jsonпроекта модуля:{ "profiles": { "debug": { "commandName": "Executable", "executablePath": "C:\\Tools\\debug\\debug.exe", "commandLineArgs": "" } } }F5 с профилем «debug». debug найдёт
debug.json(в текущей папке или выше) и самый свежий*.servext.dllвbin\рядом с ним, спросит пароль (или возьмётDEBUG_PASSWORD), вызоветRunAsyncи напечатает, что модуль собирался записать. На сервер ничего не пишется.
Записать изменения по-настоящему: --apply или "apply": true. Перед запуском утилита покажет сервер и логин и
спросит подтверждение (y); без вопроса - ключ --yes (кроме прода, см. «Запись на прод»). Изменения идут от имени разработчика и записываются
по ходу выполнения: накопленное в modifier уходит на сервер перед
следующим обращением модуля к modifier/backend и в конце RunAsync. Цепочка шагов, где следующий читает
результат предыдущего (версии файлов, атрибуты), видит на сервере уже записанное. На точке останова сразу после
SetAttribute изменения ещё нет: оно появится, когда код дойдёт до следующего вызова Pilot или до конца RunAsync.
Если F5 не останавливается на точках: --wait / Debug / Attach to Process / debug.exe (Managed .NET Core).
Остальные ключи: debug --help.
Откуда берутся настройки. debug.json ищется в текущей папке и выше; утилита печатает, какой файл взят, и
предупреждает, если он найден автоматически: server из него определяет, куда уйдёт пароль, а module - какая dll будет выполнена.
Не запускайте утилиту в папках, которым не доверяете.
Какой код выполняется. Всегда локальная сборка модуля из bin\ вашего проекта. Версия, загруженная на сервер
(через админку или напрямую), не используется. С сервера берутся только данные: объекты, типы, файлы.
Поэтому перед запуском проект нужно собрать (F5 в Visual Studio делает это сам).
Пример: TestServerAction
server-extensions\
├─ Debug\ / утилита; zip из админки не нужен, если репозиторий уже есть
│ └─ bin\Release\net8.0\publish\debug.exe (dotnet publish -c Release)
└─ TestServerAction\
├─ TestServerAction.csproj
├─ debug.json / из админки, кладётся сюда, рядом с .csproj
├─ Properties\launchSettings.json / профиль «debug»
└─ bin\Debug\TestServerAction.servext.dll / именно он и запускается
debug.json (как выдала админка):
{
"server": "http://localhost:5547/pilot-ice_ru",
"login": "ivanov",
"module": "bin/Debug/TestServerAction.servext.dll",
"activity": "TestServerAction",
"sourceId": "4a912f46-a397-42a8-a8a3-ebf7572cd1d0",
"when": "StateAttributeChanged",
"sourceTypes": [ "task_toReviewDocument" ],
"params": {}
}
sourceId - объект, на котором будто бы сработало событие. Он должен быть одного из типов sourceTypes,
иначе модуль, скорее всего, ничего не сделает. Другой объект: поменять здесь или --source <guid>.
Properties\launchSettings.json. Путь относительный: Visual Studio подставляет $(ProjectDir) (папку проекта),
так что профиль работает в любой копии CICD, если Debug опубликован (dotnet publish -c Release).
Модуль лежит не рядом с Debug или утилита скачана zip-ом - абсолютный путь, например C:\\Tools\\debug\\debug.exe.
{
"profiles": {
"debug": {
"commandName": "Executable",
"executablePath": "$(ProjectDir)..\\Debug\\bin\\Release\\net8.0\\publish\\debug.exe",
"commandLineArgs": "",
"workingDirectory": "$(ProjectDir)"
}
}
}
Дальше:
- Открыть
TestServerAction.sln, конфигурация Debug (её указываетmodule). - Точка останова в
RunAsync. - Выбрать профиль debug рядом с и нажать F5.
- В консоли ввести пароль своей учётной записи Pilot (или заранее задать
DEBUG_PASSWORD). - Отладчик остановится в модуле. В конце консоль покажет изменения, которые модуль собирался записать,
и под отладчиком будет ждать нажатия клавиши. По умолчанию на сервер ничего не записывается.
Чтобы записать, скачайте json с галочкой «Записывать изменения на сервер» (или впишите
--applyвcommandLineArgs, или"apply": trueв json). Перед запуском консоль спросит подтверждение; изменения пишутся сразу по ходу выполнения.
Запись на прод
Админка сама вписывает в debug.json поле "contour" (test, stage или prod) по контуру, для которого вы
скачали файл. Если там prod, запись на сервер подтверждается не ответом y, а вводом слова prod; ключ --yes на прод
не действует. Это сделано для случая, когда --yes когда-то прописали в launchSettings.json или скрипт для тестового
сервера, а потом подменили адрес на боевой: без осознанного ввода слова ничего не запишется. Нужна запись на прод
без вопроса (скрипт) - отдельный явный ключ --yes-prod. Для test, stage и старых файлов без поля contour
всё работает как раньше, просмотр без --apply не меняется.
Если задан --server с адресом, отличным от server в кейсе, и в кейсе есть contour, контур считается недостоверным
и запись подтверждается словом prod, как для прода. Файл без contour защиты не имеет: старые файлы пересоздайте в админке.
Отличия от сервера
- Права разработчика, а не сервера: недоступный ему объект модуль не увидит.
ev.Changesпустой (изменения, вызвавшие событие, не воспроизводятся);Target/RelationType- null.GetService<T>(): естьIAutomationNotifier(только печатает) иIAutomationFileProvider(файлы с сервера); остальные сервисы возвращают null с предупреждением.paramsразбираются так же, как на сервере (Newtonsoft: строки с датой /DateTime, массивы /List<object>, вложенные объекты /Dictionary<string, object>). Шаблоны (templates) сценария не подставляются.- Внешние вызовы модуля (почта, HTTP, файлы) выполняются по-настоящему.
- В режиме записи изменения уходят несколькими пакетами по ходу выполнения, а сервер применяет все изменения
активности одним пакетом после
RunAsync. Если активность упадёт, уже записанные шаги останутся на сервере. - Builder, полученный до обращения к Pilot (
var b = modifier.EditObject(x); backend.GetObject(...); b.SetAttribute(...)), в режиме записи теряет изменения: после записи пакета он уже не связан сmodifier. БеритеEditObjectзаново.
Сборка
dotnet publish -c Release / dist/debug.zip и копия в wwwroot/downloads админки
(ссылка появится после пересборки образа админки).
Что связано снаружи
proadmin/.../DebugCaseBuilder.cs формирует debug.json в формате DebugCase.cs, при изменении формата править оба файла.