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

Как пользоваться

  1. Скачать debug.zip в админке («Серверные модули» / «Локальная отладка») и распаковать, например, в C:\Tools\debug.

  2. В админке у активности нажать «Отладить локально» / debug.json (можно указать Id объекта). Галочка «Записывать изменения на сервер» ставит в файле "apply": true; без неё - только просмотр. Файл не отправляйте и не коммитьте с "apply": true: запись перед запуском подтверждается, но флаг лучше включать осознанно. Положить файл в папку проекта модуля. В нём адрес сервера контура, ваш логин и params / sourceTypes / when из автоматизаций контура. Пароля в файле нет.

  3. Properties/launchSettings.json проекта модуля:

    {
      "profiles": {
        "debug": {
          "commandName": "Executable",
          "executablePath": "C:\\Tools\\debug\\debug.exe",
          "commandLineArgs": ""
        }
      }
    }
    
  4. 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)"
    }
  }
}

Дальше:

  1. Открыть TestServerAction.sln, конфигурация Debug (её указывает module).
  2. Точка останова в RunAsync.
  3. Выбрать профиль debug рядом с и нажать F5.
  4. В консоли ввести пароль своей учётной записи Pilot (или заранее задать DEBUG_PASSWORD).
  5. Отладчик остановится в модуле. В конце консоль покажет изменения, которые модуль собирался записать, и под отладчиком будет ждать нажатия клавиши. По умолчанию на сервер ничего не записывается. Чтобы записать, скачайте 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, при изменении формата править оба файла.