Разработка конфигурационного серверного кода в пользовательском проекте

Общие сведения

До версии 7.11.1 для разработки конфигурационного серверного кода в файловой системе использовалось только предварительно настроенное решение Visual Studio, которое поставлялось вместе с дистрибутивом bpm'online. Подробнее о решении Terrasoft.Configuration.sln и особенностях разработки серверного кода в файловой системе рассказывается в статьях "Разработка в файловой системе" и "Работа с серверным кодом в Visual Studio".

Этот подход связан с определенными неудобствами, возникающими при разработке, — довольно низкой производительностью, связанной с перекомпиляцией всей конфигурационной части bpm'online (Terrasoft.Configuration.dll). Особенно это ощутимо, если приложение содержит сразу несколько продуктов линейки bpm'online. Кроме того, разработку серверного кода в файловой системе можно было выполнять только взаимодействуя с базой данных приложения, развернутого on-site.

В связи с описанными неудобствами, такой подход рационально использовать только в том случае, когда нужно выполнять сложную конфигурационную доработку bpm'online. Для разработки несложного серверного кода рациональнее использовать встроенные средства разработки bpm'online (см. статью "Встроенные средства разработки". Однако они не поддерживают полную функциональность IDE — отладку (debugging), автозавершение (IntellISense), рефакторинг (Refactoring) и др.

Начиная с версии 7.11.1 в bpm'online появилась возможность разработки несложного серверного кода в пользовательских проектах Visual Studio.

Для разработки и отладки отдельных классов или небольших блоков серверной функциональности можно создать отдельный проект библиотеки классов и выполнить его настройку. Далее, подключив в зависимости проекта нужные библиотеки классов bpm'online (например, Terrasoft.Core), можно выполнять разработку и отладку серверного кода. При этом для отладки и проверки результата разработки можно использовать как локальную базу данных, подключившись к ней с помощью утилиты WorkspaceConsole, так и размещенное в облаке приложение, подключившись к нему с помощью специально разработанной утилиты — Executor.

Основные преимущества этого подхода:

• Высокая скорость проверки изменений, компиляции и запуска на выполнение.
• Полноценное использование функциональности Visual Studio.
• Возможность использования любых инструментов для непрерывного цикла разработки (Continuous Integration), например, Unit-тестирования.
• Простота настройки проекта — не нужны исходные коды конфигурации.
• Можно использовать базу данных приложения, развернутого как локально, так и в облаке.

Предварительные настройки

Для подключения библиотек классов bpm'online, развертывания локальной базы данных из архивной копии, а также для работы с утилитой WorkspaceConsole удобно использовать дистрибутив bpm'online, распакованный на локальный диск компьютера разработчика. Во всех примерах этой статьи используется дистрибутив bpm'online, распакованный в локальный каталог C:\bpmonline7.11.1.

Для примера работы с облачным приложением bpm'online используется утилита Executor, находящаяся в каталоге C:\Executor. Скачать утилиту, настроенную для выполнения примера, можно по ссылке.

Разработка конфигурационного серверного кода для on-site приложения

Для разработки конфигурационной серверной логики при наличии доступа к локальной базе данных приложения bpm'online необходимо выполнить следующие действия:

1. Восстановить базу данных из резервной копии (при необходимости)

Процесс развертывания базы данных bpm'online из резервной копии подробно описан в статье "Установка bpm’online" документации пользователя. Архивная копия базы данных приложения размещена в каталоге db дистрибутива приложения (например, C:\bpmonline7.11.1\db).

2. Настроить утилиту WorkspaceConsole

Для работы с развернутой базой данных необходимо настроить утилиту WorkspaceConsole, используя файлы приложения. Подробно настройка утилиты описана в статье "Настройка утилиты WorkspaceConsole". Краткая последовательность действий:

• Перейти в каталог Terrasoft.WebApp\DesktopBin\WorkspaceConsole дистрибутива приложения (например, C:\bpmonline7.11.1\Terrasoft.WebApp\DesktopBin\WorkspaceConsole).
• Запустить один из пакетных файлов PrepareWorkspaceConsole.x64.bat или PrepareWorkspaceConsole.x86.bat, в зависимости от версии Windows.

• Указать параметры подключения к базе данных в файле Terrasoft.Tools.WorkspaceConsole.exe.config, размещенном в каталоге Terrasoft.WebApp\DesktopBin\WorkspaceConsole дистрибутива приложения (например, C:\bpmonline7.11.1\Terrasoft.WebApp\DesktopBin\WorkspaceConsole). Например, если на сервере dbserver развернута база данных bpmonline7.11.1DB, то строка подключения будет иметь следующий вид:

<connectionStrings>
<add name="db" connectionString="Data Source=dbserver; Initial Catalog=bpmonline7.11.1DB; Persist Security Info=True; MultipleActiveResultSets=True; Integrated Security=SSPI; Pooling = true; Max Pool Size = 100; Async = true; Connection Timeout=500" />
</connectionStrings>

3. Создать и настроить проект Visual Studio

Для этого нужно создать обычный проект библиотеки классов (рис. 1). Как создать новое решение Visual Studio и управлять проектами решения подробно описано в разделе "Solutions and Projects in Visual Studio" документации Microsoft.

Рис. 1. — Создание решения и проекта библиотеки классов в Visual Studio

На вкладке [Debug] окна свойств созданного проекта библиотеки классов необходимо указать в свойстве [Start external program] полный путь к настроенной утилите WorkspaceConsole (рис. 2). Утилита WorkspaceConsole используется как внешнее приложение для отладки разрабатываемой программной логики.

Рис. 2. — Свойства вкладки [Debug]

В свойстве [Command line arguments] необходимо указать следующие аргументы запуска WorkspaceConsole.

• -filename — полный путь к отладочной версии разрабатываемой библиотеки классов.
• -typeName — полное имя класса, в котором реализуется разрабатываемая программная логика, включая названия всех пространств имен. Например, BpmonlineCustomServerLogic.MyContactCreator.
• -operation — операция WorkspaceConsole. Должно быть указано значение "ExecuteScript".
• -workspaceName — название рабочего пространства. Должно быть указано значение "Default".

Пример строки аргументов запуска WorkspaceConsole:

-filename="C:\Projects\BpmonlineCustomServerLogic\BpmonlineCustomServerLogic\bin\Debug\BpmonlineCustomServerLogic.dll" -typeName=BpmonlineCustomServerLogic.MyContactCreator -operation=ExecuteScript -workspaceName=Default

Подробнее о параметрах запуска можно узнать из статьи "Параметры WorkspaceConsole".

Для работы с классами серверной части ядра bpm'online необходимо в созданном проекте установить зависимости от нужных библиотек классов bpm'online. Например, добавить зависимость от библиотеки Terrasoft.Core.dll (рис. 3). Подробнее о добавлении зависимостей можно узнать из статьи "Managing references in a project" документации Microsoft.

Рис. 3. — Библиотека Terrasoft.Core в зависимостях проекта

Библиотеки классов пространства имен Terrasoft можно найти в каталоге Terrasoft.WebApp\DesktopBin\WorkspaceConsole дистрибутива приложения.

4. Выполнить разработку функциональности

Для этого нужно в созданный проект библиотеки классов добавить класс, полное название которого должно совпадать с названием, указанным в аргументе -typeName строки аргументов запуска утилиты WorkspaceConsole (например, BpmonlineCustomServerLogic.MyContactCreator). Класс должен реализовать интерфейс Terrasoft.Core.IExecutor.

Пример реализации класса приведен ниже:

using System;
using Terrasoft.Core;

namespace BpmonlineCustomServerLogic
{
    public class MyContactCreator : IExecutor
    {
        public void Execute(UserConnection userConnection)
        {
            // Получение экземпляра схемы [Контакты].
            var schema = userConnection.EntitySchemaManager.GetInstanceByName("Contact");
            var length = 10;
            for (int i = 0; i < length; i++)
            {
                // Создание нового контакта.
                var entity = schema.CreateEntity(userConnection);
                // Установка свойств контакта.
                entity.SetColumnValue("Name", string.Format("Name {0}", i));
                entity.SetDefColumnValues();
                // Сохранение контакта в базу данных.
                entity.Save(false);
            }
            // Вывод сообщения в консоль.
            Console.WriteLine($"{length} contacts created");
        }
    }
}

После запуска проекта на выполнение (клавиша F5) появится окно утилиты WorkspaceConsole с соответствующим сообщением (рис. 4).

Рис. 4. — Отображение результата выполнения программы в окне WorkspaceConsole

Также можно установить точку останова на любой строке исходного кода и во время выполнения программы посмотреть текущие значения переменных, т. е. выполнить отладку. Подробнее об использовании точек останова в среде Visual Studio можно узнать из статьи "Use Breakpoints in the Visual Studio Debugger" документации Microsoft.

Результат выполнения приведенного выше программного кода можно посмотреть в в разделе [Контакты] приложения bpm'online (рис. 5), либо выполнив запрос в базу данных (рис. 6).

Рис. 5. — Добавленные контакты

Рис. 6. — Запрос к таблице контактов базы данных

Разработка конфигурационного серверного кода для облачного приложения

Для разработки конфигурационной серверной логики при отсутствии прямого доступа к базе данных приложения bpm'online необходимо выполнить следующие действия:

1. Создать проект библиотеки классов.

Необходимо создать обычный проект библиотеки классов (рис. 1). Как создать новое решение Visual Studio и управлять проектами решения, подробно описано в разделе "Solutions and Projects in Visual Studio" документации Microsoft. В качестве имени проекта необходимо указать, например, значение "BpmonlineCustomServerLogic.Cloud".

Для работы с классами серверной части ядра bpm'online необходимо в созданном проекте установить зависимости от нужных библиотек классов bpm'online. Например, добавить зависимость от библиотеки Terrasoft.Core.dll (рис. 3). Подробнее о добавлении зависимостей можно узнать из статьи "Managing references in a project" документации Microsoft.

На вкладке [BuildEvents] окна свойств созданного проекта библиотеки классов необходимо указать в свойстве [Post-build event command line] полный путь к настроенной утилите Executor (рис. 7), например, C:\Executor\Executor.exe. Также на этой вкладке необходимо выбрать условие запуска события сборки библиотеки.

Рис. 7. — Свойства вкладки [Build Events]

2. Выполнить разработку функциональности

Для этого нужно в созданный проект библиотеки классов добавить класс, который должен реализовать интерфейс Terrasoft.Core.IExecutor. Пример реализации класса приведен ниже:

using System;
using System.Web;
using Terrasoft.Core;
using Terrasoft.Core.Entities;

namespace BpmonlineCustomServerLogic.Cloud
{
    public class MyContactReader : IExecutor
    {
        public void Execute(UserConnection userConnection)
        {
            // Получение экземпляра схемы [Контакты].
            var entitySchema = userConnection.EntitySchemaManager.GetInstanceByName("Contact");
            // Создание экземпляра класса запроса.
            var esq = new EntitySchemaQuery(entitySchema);
            // Добавление в запрос всех колонок схемы.
            esq.AddAllSchemaColumns();
            // Получение коллекции записей раздела [Контакты].
            var collection = esq.GetEntityCollection(userConnection);
            foreach (var entity in collection)
            {
                // Вывод в http-ответ запроса от утилиты Executor необходимых значений.
                HttpContext.Current.Response.Write(entity.GetTypedColumnValue<string>("Name"));
                HttpContext.Current.Response.Write(Environment.NewLine);
            }
        }
    }
}

3. Настроить утилиту Executor

Для этого необходимо перейти в каталог, содержащий утилиту Executor, например, C:\Executor. Затем в конфигурационном файле указать значения для следующих элементов настройки:

• Loader — URL загрузчика приложения bpm'online. Как правило, это URL сайта bpm'online, например "https://mycloudapp.bpmonline.com".
• WebApp — URL приложения bpm'online. Как правило, это путь к конфигурации по умолчанию приложения bpm'online, например "https://mycloudapp.bpmonline.com/0".
• Login — имя пользователя bpm'online, например, "Supervisor".
• Password — пароль пользователя bpm'online.
• LibraryOriginalPath — путь к исходной копии библиотеки классов. Как правило, это путь, по которому создается библиотека классов после компиляции в Visual Studio, например, "C:\Projects\BpmonlineCustomServerLogic\BpmonlineCustomServerLogic.Cloud\bin\Debug\BpmonlineCustomServerLogic.Cloud.dll".
• LibraryCopyPath — путь, по которому будет создана копия библиотеки классов для работы с удаленным сервером. Это может быть любая временная папка или каталог, содержащий утилиту Executor, например, "C:\Executor\BpmonlineCustomServerLogic.Cloud.dll".
• LibraryType — полное имя класса, в котором реализуется разрабатываемая программная логика, включая названия всех пространств имен. Например, "BpmonlineCustomServerLogic.Cloud.MyContactReader".
• LibraryName — название библиотеки классов, например, "BpmonlineCustomServerLogic.Cloud.dll".

4. Выполнить разработанный программный код

Результат выполнения разработанного программного кода можно увидеть в окне [Output] Visual Studio после каждой успешной сборки библиотеки классов (рис. 8).

Рис. 8. — Результат выполнения программного кода

Для запуска процесса сборки следует воспользоваться командами меню [Build Solution] и [Rebuild Solution] (рис. 9).

Рис. 9. — Команды меню [Build]