Заказать демо

Разработчикам

Portal Extension SDK

C# SDK для WebPart, Event Receiver, Timer Job, веб-сервисов и функциональных модулей. Версия SDK должна совпадать с версией установленного Portal. Своя операция с JSON на вход и на выход — пакет веб-сервиса, без отдельного маршрута в исходниках платформы.

NuGet feed

Добавьте источник пакетов в глобальную или проектную конфигурацию:

dotnet nuget add source https://korport.ru/api/nuget/v3/index.json -n korport

Или скопируйте nuget.config из скачанного SDK ZIP.

Быстрый старт

  1. Скачайте SDK той же версии, что и Portal (см. таблицу ниже).
  2. Установите шаблоны: dotnet new install ./portal-sdk-X.Y.Z/templates/portal-webpart
  3. Создайте проект: dotnet new portal-webpart -n MyWidget -o ./my-widget
  4. Соберите пакет: ../scripts/pack-portalpart.sh .
  5. Загрузите .portalpart в Админка → WebPart.

Документация: Старт и SDK, выбор типа расширения, WebPart, Event Receiver, Timer Job, Веб-сервисы, Модули, интеграции, отладка расширений.

На Docker и Kubernetes отладка пакетов с брейкпоинтами в IDE к контейнеру/поду не предусмотрена — обычно логи и hot deploy; на Native удобнее Attach к процессу. Подробности в документации по отладке.

Веб-сервисы

Своя REST-ручка на портале

Пакет .portalapi — одна операция. Портал публикует её как POST /api/v1/web-services/call/{id} и возвращает JSON. {id} — поле манифеста вида vendor.name, например contoso.orders.

Что делает ручка

Обработчик — класс на C#, реализующий IWebService из пакета Portal.WebService.Sdk. Метод HandleAsync получает параметры вызова, настройки администратора и того, кто вызвал, работает со списками и библиотеками и возвращает объект. Портал кладёт его в { "success": true, "data": … }.

Так закрывают операции, которых нет в обычном CRUD списков: сводка из нескольких списков, проверка перед записью, расчёт, постановка фонового задания. Произвольный адрес /api/v1/my-erp/sync пакет не регистрирует — у всех ручек один путь, разные ключи.

Кто вызывает

Только вошедший пользователь портала: заголовок Authorization: Bearer или сессия браузера. API-ключей и анонимного вызова нет. WebPart и внешняя система ходят тем же пользовательским JWT после POST /api/v1/auth/login.

Списки, библиотеки, права и КЭДО внутри ручки выполняются от этого пользователя. Элемент, который ему не виден, код не прочитает. Если операция должна быть уже, чем «любой вошедший», проверку группы делают в обработчике. Неизвестная или выключенная ручка отвечает 404, запрос без входа — 401.

Тело и настройки

JSON тела — параметры этого вызова (номер заявки, действие, фильтр). Пустое тело читается как {}, потолок — 1 МБ. Настройки ручки (id списка, режим, порог) задаёт администратор в карточке Админка → Веб-сервисы или секция webServices в module.json модуля. При обновлении ZIP той же ручки сохранённые настройки не сбрасываются.

Таймаут

Query-параметр timeout — секунды. Если его нет, портал ждёт 30 секунд. Допустимо от 1 до 600. Значение видно обработчику как context.Timeout, и по истечении лимита отменяется CancellationToken. Клиент для длинного расчёта передаёт, например, ?timeout=120.

Если время вышло, а клиент сам соединение не оборвал, ответ — HTTP 408 и JSON, не 500: 

{
  "success": false,
  "error": {
    "code": "TIMEOUT",
    "message": "Превышено время выполнения веб-сервиса (30 с)"
  }
}

Ноль, отрицательное число и значение больше 600 — ответ 400 с текстом про допустимый диапазон. Дольше 10 минут один HTTP-вызов не держат: такую работу ставят в очередь заданий и отдают клиенту идентификатор.

Как собрать и поставить

  1. Скачайте SDK той же версии, что Portal (таблица ниже).
  2. dotnet new install ./portal-sdk-X.Y.Z/templates/portal-webservice
  3. dotnet new portal-webservice -n orders -o ./orders
  4. В manifest.json задайте свой id (vendor.name), entry и entryType — класс обработчика.
  5. ./portal-sdk-X.Y.Z/scripts/pack-portalapi.sh ./orders — получится .portalapi. На Windows — pack-portalapi.ps1.
  6. Загрузите файл в Админка → Веб-сервисы. Для отладки соберите с CONFIGURATION=Debug, в пакет попадут PDB.

В модуле файл кладут в packages/ с типом web-service. Стартовый JSON настроек — массив webServices с definitionKey, равным id манифеста. Portal.WebService.Sdk.dll в ZIP не входит: типы даёт работающий портал.

Пример без записи в списки — examples/echo-webservice в архиве SDK, ключ contoso.echo. Им проверяют вход, конверт ответа и таймаут.

Версии SDK

Скачайте архив той же версии, что установлен у вас Portal.

Версия Дата SHA256
1.0.0 17.10.2026 e9a170c3d02d…7a5cd83e Скачать ZIP