Пример расширения Службы фоновых операций

Демонстрационный вариант расширения Службы фоновых операций, расположенный в репозитории Docsvision на GitHub. Расширение получает ID карточки документа и конвертирует приложенные файлы в формат PDF/A.

Перечень необходимых инструментов:

Visual Studio 2022 и выше

Сборка

Откройте /Samples.sln.
Соберите проект Others > SampleWorkerExtension.
Соберите проект Samples\Others\SampleWorkerExtension\SampleWorkerExtension.WebClientExtension\SampleWorkerExtension.WebExtension.
Выполните npm i, npm run build.
Соберите пример взаимодействия с сервисом конвертации.

Установка

Отправьте в GAC сборки, полученные в пункте 2 выше.

gacutil.exe -if DocsVision.SampleWorkerExtension.Manager.dll
gacutil.exe -if DocsVision.SampleWorkerExtension.ObjectModel.dll
gacutil.exe -if DocsVision.SampleWorkerExtension.WorkerService.dll
gacutil.exe -if ru\DocsVision.SampleWorkerExtension.WorkerService.resources.dll

Добавьте сборки DocsVision.SampleWorkerExtension.Role.dll вместе с ресурсами ru\DocsVision.SampleWorkerExtension.Role.resources.dll и конфигурационный файл SampleWorkerExtension.json (находится в проекте SampleWorkerExtension.Role) в папку Консоли управления Docsvision.
Если папка с расширениями отсутствует, создайте вручную. Например, C:\Program Files (x86)\Docsvision\ManagementConsole\SampleExtensions.

Добавьте сборку DocsVision.SampleWorkerExtension.WorkerExtension.dll в папку WorkerService. Например, C:\Program Files (x86)\Docsvision\WorkerService\5.5\Extensions.

В сборке DocsVision.SampleWorkerExtension.WorkerExtension.dll реализован класс наследник IRoleTemplateProvider. Если вы будете редактировать файл и переносить этот класс в другую сборку, не забудьте положить уже новую сборку в папку в папку WorkerService, иначе ваше расширение не будет доступно для Службы фоновых операций.

Установите серверное и клиентское расширения для Web-клиента, которые находятся в Others\SampleWorkerExtension\SampleWorkerExtension.WebClientExtension (инструкция внутри проекта).
Установите пример взаимодействия с сервисом конвертации.
Отредактируйте конфигурационный файл Сервиса внешнего API Консоли управления Docsvision по адресу C:\Program Files (x86)\Docsvision\ManagementConsoleExternalAPI\DocsVision.ManagementConsole.ExternalAPI.WindowsService.exe.config.

В секцию Libraries конфигурационного файла добавьте строку, содержащую SampleWorkerExtension.WorkerService следующим образом:

<Libraries>
  <add Path="DocsVision.BackOffice.ObjectModel, Version=5.5.0.0, Culture=neutral, PublicKeyToken=7148afe997f90519" />
  <add Path="DocsVision.SampleWorkerExtension.WorkerService, Version=1.0.0.0, Culture=neutral, PublicKeyToken=4a2caa47aa5b6b29" />
</Libraries>

Проверка

Откройте Консоль управления Docsvision и создайте новый процесс Службы фоновых операций с типом конфигурации Расширение для WorkerService.
В разметке документа Web-клиента (например, просмотр) создайте кнопку и добавьте для события При щелчке обработчик sendConversionTask.
В Web-клиенте создайте документ и приложите к нему файлы. Сохраните документ и в открывшейся разметке нажмите созданную кнопку. Через некоторое время в секции файлов появятся файлы, конвертированные в формат PDF/A.

Проект "SampleWorkerExtension"

Проект содержит создание сообщения для Службы фоновых операций в серверном расширении SampleWorkerExtension.ServerExtension и расширении Web-клиента SampleWorkerExtension.WebExtension.

Проект-расширение для Web-клиента SampleWorkerExtension.ServerExtension содержит скрипт для создания сообщения для Службы фоновых операций. Проект демонстрирует расширение функционала с помощью добавления новых сервисов, контроллеров. Реализован контроллер SampleWorkerController с методом SendToWorker, который вызывает сервис ISampleWorkerService. В сервисе осуществляется создание сообщения для Службы фоновых операций с переданным идентификатором карточки, откуда был вызван скрипт.

Проект "SampleWorkerExtension.WebClientServerExtension"

Проект содержит клиентские скрипты, в которых при нажатии на кнопку с помощью сервиса requestManager отправляется запрос на сервер. После конвертации файла в .pdf, он отображается в карточке.

Разработка

При разработке собственного расширения необходимо дорабатывать или переписывать класс:

public class SampleEventHandlerService : EventHandlerService, ISampleEventHandlerService

При создании собственных событий будет реализовываться управление обработкой событий:

  public static readonly EventDescription ConvertCardFiles = new EventDescription { Id = new Guid("B2C6F070-C7F1-4F07-914F-94652804DD1C"), AutoSendToSelf = true, Concurrent = false };

        private readonly Dictionary<Guid, EventHandlerInfo> handlersInfo = new Dictionary<Guid, EventHandlerInfo>
        {
            {
                ConvertCardFiles.Id,
                new EventHandlerInfo
                    { EventId = ConvertCardFiles.Id, EventArgsType = typeof(SampleEventArgs), EventHandlerName = nameof(ProcessCardFiles) }
            }
        };

Также при доработке компонента логики будет реализована своя логика обработки этих событий:

private const string SampleComponentTypeName = "SampleWorkerExtension.Manager.SampleApiManager, SampleWorkerExtension.Manager, Version=1.0.0.0, Culture=neutral, PublicKeyToken=4a2caa47aa5b6b29";

Очередь сообщений

Служба фоновых операций версии 5.5.136 и выше поддерживает поиск сообщений с определенным типом сервиса. Для этого в своем расширении для фабрики задания нужно задать свойство MessageTypes. Все сообщения с этим типом будут передаваться для обработки.

Если ваша текущая версия Службы фоновых операций меньше, потребуется либо обновиться, либо самостоятельно обеспечить выбор сообщений нужного типа.

Для формирования таймера или выполнения события по завершении промежутка времени можно использовать отложенные сообщения. Ниже дан пример формирования задания с отложенным исполнением:

EventService.RaiseDelayedEvent(approvalStage, ApprovalStage.NextTaskRequestedEvent.Id,
     new ApprovalStageNextTaskRequestedEventArgs
     {
         CardId = reconcileCard.GetObjectId(),
         PathId = approvalPath.GetObjectId(),
         StageId = approvalStage.GetObjectId()
     }, DateTime.Now);

Упрощённый подход

Данный подход позволяет не создавать полностью весь конвейер обработки карточек, изменяя лишь часть уже работающего. Чаще всего это замена сервиса из справочника видов для некоторого вида карточек.

При необходимости доработать что-то в уже существующих карточках (задание, группы задания): формирование описания, заполнение дат и своих полей в зависимости от некоторых условий, можно использовать упрощённый подход.

При таком подходе создаётся класс от существующего (того, что привязан в справочнике видов в секции Сервисы), переопределить или заменить метод из него и заменить его в справочнике видов. После перезапуска Службы фоновых операций события для этого вида начнут обрабатываться по новой логике.

Если ваша логика добавляет задержки, использует асинхронные операции, упрощённый подход использовать не рекомендуется, поскольку это затормозит обработку существующих карточек (согласования, рассылка заданий). В этом случае потребуется реализовать полноценное собственное расширение. Однако пока Консоль управления Docsvision не поддерживает отображение и вывод своих настроек для расширения, обеспечить их считывание требуется самостоятельно.

Чтобы задать читаемое название для собственных сервисов, отображаемое в виджетах и на страницах Консоли управления Docsvision, потребуется реализовать собственный ResDescriptionAttribute, унаследованный от DescriptionAttribute. Реализация атрибута привязана к сборке и её ResourceManager.