Отладка расширений с брейкпоинтами

Инструкция для разработчика расширений Portal: WebPart, Event Receiver, Timer Job, provisioner модуля.

Нужны установленный Portal и Extension SDK той же версии — SDK для сборки вашего расширения.

┌──────────────────────────────────────────────────────────┐
│  Установленный Portal                                    │
│    Api загружает вашу WebPart / provisioner              │
│    Worker загружает Event Receiver / Timer Job           │
└──────────────────────────────────────────────────────────┘
              │  Attach (если канал установки позволяет)
              ▼
┌──────────────────────────────────────────────────────────┐
│  IDE: проект расширения + PDB                            │
│    брейкпоинт в вашем .cs → Stop при вызове              │
└──────────────────────────────────────────────────────────┘

Что понадобится

1. .NET SDK 10 (тот же major, что у Portal) — dotnet --version.
2. IDE с Attach к .NET-процессу (Rider, Visual Studio, VS Code + C#).
3. Extension SDK той же версии, что Portal (NuGet, примеры, скрипты pack-*).
4. Экземпляр Portal, куда можно ставить пакеты (предпочтительно staging / dev).
5. Права ставить расширения в админке (и при Attach — доступ к процессу Api/Worker на сервере или к Docker-хосту).

Какой процесс «держит» ваш код

Тип расширения	Процесс Portal	Как спровоцировать hit
WebPart	Api	Открыть / обновить страницу с WebPart, action WebPart
Module provisioner	Api	Установить / переустановить .portalmod
Event Receiver	Worker	Создать / изменить элемент списка (событие → job)
Timer Job	Worker	Run в админке или дождаться расписания

К процессу Api или Worker подключаетесь через Attach в IDE.

Основной сценарий: Debug-пакет + Attach

Шаг 1. Соберите пакет с символами

Скрипты — из Extension SDK (или копии pack-*.sh / pack-*.ps1 рядом с проектом). По умолчанию Release; для брейкпоинтов нужен Debug (в ZIP попадут .dll и .pdb):

CONFIGURATION=Debug ./pack-portalpart.sh ./my-widget
CONFIGURATION=Debug ./pack-portalevent.sh ./my-handler
CONFIGURATION=Debug ./pack-portaltimer.sh ./my-job
CONFIGURATION=Debug ./pack-portalmod.sh ./my-module

PowerShell: -Configuration Debug.

Увеличьте version в manifest.json / module.json, если переустанавливаете поверх уже установленного пакета.

Шаг 2. Установите пакет в Portal

Как обычно: Админка (WebParts / Event Receivers / Timer Jobs / Модули) или API установки пакета.
Перезапуск Api/Worker для hot deploy не нужен — см. Hot deploy.

После загрузки файлы расширения оказываются в каталоге вида:

%TEMP%/portal-plugins/{key}/{contentHash}/

рядом лежат DLL и PDB — отладчик подхватит символы оттуда (пути зависят от ОС и канала установки).

Шаг 3. Attach в IDE

1. Откройте в IDE проект вашего расширения (не платформу).
2. Поставьте брейкпоинт в серверном C#-коде.
3. Debug → Attach to Process (формулировка зависит от IDE) к нужному процессу — см. таблицу по каналам ниже.
4. Спровоцируйте hit (страница, событие списка, Run job).

Шаг 4. По каналам установки

Канал	Брейкпоинты (Attach)	Рабочий способ отладки
Native Linux / Windows	Да — Attach к службе Api/Worker	Debug-пакет + Attach (см. ниже)
Docker Compose	Нет «из коробки»	Логи + hot deploy
Kubernetes	Нет «из коробки»	Логи + hot deploy

Узнать канал: выбор установки, install.mode в каталоге данных или экран лицензии.

Пример: WebPart на Native Linux

CONFIGURATION=Debug ./pack-portalpart.sh ./my-widget
# установить .portalpart в админке (version ↑)
systemctl status portal-api   # PID → Attach в IDE
# браузер — страница с WebPart

Пример: Event Receiver / Timer Job

Attach к Worker, не к Api. После установки Debug-пакета — событие списка или Run Timer Job.

---

Docker и Kubernetes: как отлаживать

Штатные образы portal/api и portal/worker — Production, без отладчика (vsdbg).
Поэтому сценарий «Debug-пакет → Attach из Rider/VS» на Docker/K8s не поддерживается.

Рекомендуемый цикл (основной)

Тот же hot deploy, что и в проде: пакет ставится в работающий Portal без рестарта контейнеров/подов.

1. В коде расширения пишите диагностику через лог SDK (api.Log.Info, Error, … — см. SDK WebPart / ER / Timer Job).
2. Соберите пакет (CONFIGURATION=Debug не обязателен, если брейкпоинты недоступны; для единообразия можно Debug).
3. Установите / обновите пакет в админке (увеличьте version).
4. Воспроизведите сценарий в браузере.
5. Смотрите логи:

Docker Compose (из каталога установки):

docker compose logs -f backend    # WebPart, provisioner
docker compose logs -f worker     # Event Receiver, Timer Job

Kubernetes (namespace часто portal, имена могут отличаться — kubectl get pods -n portal):

kubectl logs -n portal -l app.kubernetes.io/component=backend -f --tail=200
kubectl logs -n portal -l app.kubernetes.io/component=worker -f --tail=200

6. Правка → снова pack → установка → повтор.

Это штатный и поддерживаемый способ отладки расширений на Docker/K8s.

Отдельный staging (тот же канал)

Не отлаживайте на боевом проде. Поднимите второй экземпляр Portal того же канала (docker или k8s) — отдельная БД/данные, своя лицензия на инсталляцию (лицензии: канал должен совпадать).
На staging тот же цикл «пакет + логи»; брейкпоинты по-прежнему недоступны без отладчика в образе.

Перенос на Native ради Attach возможен только с лицензией канала native (ключ Docker/K8s на Native не подойдёт — LICENSE_CHANNEL_MISMATCH).

Чего не делать

• Не рассчитывать на Attach к контейнеру/поду со штатным образом.
• Не ставить самодельный vsdbg в Production-образ на бою без понимания рисков (неподдерживаемый путь; при необходимости — только на изолированном staging и на свой страх).

Подробнее про обновление пакета: WebParts CLI, Hot deploy.

---

Логи на Native (дополнительно к Attach)

На Native удобнее Attach; логи всё равно полезны:

Канал	Api	Worker
Native Linux	journalctl -u portal-api -f	journalctl -u portal-worker -f
Native Windows	Журнал / вывод PortalApi	PortalWorker

---

Частые проблемы

Симптом	Что проверить
Брейкпоинт не срабатывает / «пустой»	Пакет собран Debug с PDB; версия в манифесте увеличена и пакет переустановлен; Attach к тому процессу (Api vs Worker); после hot-reload иногда нужно отключить Attach и подключить снова
Attach не видит процесс	На Native — права/не тот хост; на Docker/K8s Attach со штатным образом не поддерживается — см. логи
Старое поведение после установки	Жёсткое обновление страницы (CSS/JS с ?v=); для Worker — дождаться reload по Valkey или проверить логи Worker
На Docker/K8s нет брейкпоинтов	Ожидаемо. Цикл: логи SDK → pack → установка → docker compose logs / kubectl logs

---

Ограничения

• Release-сборка с оптимизациями часто ломает точное попадание в строки — для брейкпоинтов собирайте Debug.
• Hot-redeploy выгружает collectible ALC; после переустановки пакета символы перезагружаются — при необходимости переподключите Attach.
• Штатные Docker/K8s-образы Api/Worker не предназначены для отладки из IDE (нет vsdbg).

---

Чеклист

1. SDK той же версии, что Portal
2. Пакет собран и установлен / обновлён (version ↑)
3. Native: Debug + PDB → Attach к Api или Worker
4. Docker / K8s: логи в коде → docker compose logs / kubectl logs → цикл pack → установка

---

См. также

• Extension SDK
• Hot deploy
• WebParts, Event Receivers, Timer Jobs, Модули
• Какой вариант установки выбрать