Tisa.BpmCore 2026.1.9.321

Tisa.BpmCore

Описание

Tisa.BpmCore — библиотека для прямого доступа к данным платформы BPMSoft из приложений .NET Core. Позволяет создавать UserConnection и работать с EntitySchemaQuery, процессами и прочими API BPMSoft без веб-хоста — из консольных приложений, фоновых сервисов, веб-API и т.д.

Поддерживаемые фреймворки: .NET 8.0, .NET 9.0, .NET 10.0.

Установка

.NET CLI

dotnet add package Tisa.BpmCore

Актуальный номер версии пакета смотрите на nuget.org/packages/Tisa.BpmCore.

NuGet Package Manager

Install-Package Tisa.BpmCore

После установки пакета файл BPMSoft.WebHost.dll.config автоматически копируется в выходную директорию вашего проекта (bin/Debug/net8.0/ и т.д.). Это минимально настроенная рабочая конфигурация BPMSoft, которую необходимо донастроить под ваше окружение (см. также раздел «Настройка» ниже).

Требования для проектов, использующих пакет и для прямого создания UserConnection

В проектах, использующих пакет Tisa.BpmCore, и при необходимости прямого создания объекта UserConnection внутри приложения (без веб-хоста) дополнительно необходимы:

Целевая платформа: при использовании класса UserConnection в проекте с данным пакетом указывайте целевую платформу .NET 8.0 — BPMSoft в настоящее время поддерживает только её.

1. Файл конфигурации ядра BPMSoft

Используйте файл Tisa.BpmCore/Docs/App.config: в нём приведена полная конфигурация (все типовые секции и настройки) — удобно как справочник и для переноса фрагментов в свой проект. Файл входит в пакет Tisa.BpmCore и должен быть подключён к проекту (например, как контент или копия в выходную директорию).

Для запуска приложения с пакетом обычно используют BPMSoft.WebHost.dll.config — это минимально настроенная рабочая версия (см. «Шаг 1» в разделе «Настройка»); App.config не заменяет её автоматически, а дополняет документацией по полному составу настроек.

2. Ссылки на сборки платформы BPMSoft

Содержимое файла Tisa.BpmCore/Docs/BpmSoft.xml должно быть скопировано в проект (например, в .csproj в виде блока <ItemGroup> с <Reference>). Эти сборки не входят в NuGet-пакет вследствие лицензионных ограничений; пути HintPath нужно задать в соответствии с вашей установкой BPMSoft.

Список сборок BPMSoft для ссылок в проекте

• Autofac
• Autofac.Extensions.DependencyInjection
• BPMSoft.Authentication
• BPMSoft.Core.DI
• BPMSoft.Core.DI.Bindings
• BPMSoft.DB.PostgreSql
• BPMSoft.Licensing.Application
• BPMSoft.Messaging.Common
• BPMSoft.Monitoring
• BPMSoft.Redis
• BPMSoft.Redis.Abstractions
• BPMSoft.Redis.StackExchangeAdapters
• BPMSoft.Security
• BPMSoft.Store.WebAdapters
• BPMSoft.Web.Http.Abstractions
• BPMSoft.Web.Http.AspNetCore
• BPMSoft.Webhooks
• Ninject
• Ninject.Extensions.Factory
• StackExchange.Redis

Скопируйте блок <ItemGroup> с <Reference> из файла BpmSoft.xml в папке Docs пакета и при необходимости скорректируйте HintPath под вашу установку BPMSoft.

Настройка

Два файла конфигурации в Docs/

Шаг 1. Конфигурация BPMSoft (BPMSoft.WebHost.dll.config)

Файл BPMSoft.WebHost.dll.config — минимально настроенная рабочая XML-конфигурация платформы BPMSoft (секции bpmsoft, connectionStrings, redis, appSettings и др. в объёме, нужном для запуска). После установки пакета он появится в выходной директории с шаблонными значениями.

Откройте файл и замените плейсхолдеры:

Строка подключения к БД

Строку подключения достаточно задать в одном месте — либо здесь в XML, либо в appsettings.json (см. Шаг 2). Если она указана в appsettings.json, значение из XML-конфига будет переопределено автоматически.

<connectionStrings>
    <add name="db"
         connectionString="Pooling=true;Database=YOUR_DATABASE;Host=localhost;Port=5432;Username=postgres;Password=YOUR_PASSWORD;maxPoolSize=50;Timeout=5;CommandTimeout=400"/>
    <add name="redis"
         connectionString="host=localhost;db=0;port=6379"/>
</connectionStrings>

Ключи безопасности (appSettings)

Замените шаблонные значения на свои:

<add key="InitializationSecurityVector" value="CHANGE_ME_16CHARS"/>
<add key="CurrentSecurityKey" value="CHANGE_ME_24CHARS_KEY__X"/>
<add key="MsgUserPasswordDESCryptoServiceKey" value="CHANGE_ME"/>
<add key="UserManagementSauPassword" value="CHANGE_ME"/>

Важно: значения этих ключей должны совпадать с теми, которые используются на вашем экземпляре BPMSoft. Скопируйте их из конфигурации сервера BPMSoft.

Альтернативный путь к конфигурации

Вместо размещения файла в выходной директории можно указать путь через переменную окружения:

set BPMSOFT_CONFIG_PATH=C:\MyApp\config\BPMSoft.WebHost.dll.config

BpmFactory ищет конфигурационный файл в следующем порядке:

1. Переменная окружения BPMSOFT_CONFIG_PATH
2. BPMSoft.WebHost.dll.config в директории приложения (AppContext.BaseDirectory)
3. App.config в директории приложения

Шаг 2. Конфигурация приложения (appsettings.json)

Настройте секцию подключения к BPMSoft в appsettings.json вашего приложения.

Строка подключения: ConnectionString в appsettings.json — необязательна. Если она не указана, BpmFactory автоматически возьмёт её из BPMSoft.WebHost.dll.config (секция connectionStrings/db). Это позволяет хранить строку подключения только в одном месте.

Вариант A: Использование через токены (рекомендуется для API-приложений)

{
  "BpmSoft": {
    "Url": "https://your-bpmsoft-instance.com",
    "UserName": "Supervisor",
    "Password": "your-password",
    "ConnectionString": "Pooling=true;Database=...;Host=...;Username=...;Password=..."
  },
  "Tokens": {
    "DEFAULT": "BpmSoft"
  }
}

ConnectionString можно опустить — тогда используется значение из XML-конфига:

{
  "BpmSoft": {
    "Url": "https://your-bpmsoft-instance.com",
    "UserName": "Supervisor",
    "Password": "your-password"
  },
  "Tokens": {
    "DEFAULT": "BpmSoft"
  }
}

В этом сценарии IBpmCoreService.ValidateToken("DEFAULT") найдёт секцию Tokens:DEFAULT → "BpmSoft" → прочитает BpmSoft:Url, UserName, Password (и ConnectionString, если задана).

Вариант B: Прямая конфигурация через секцию BpmCore

{
  "BpmCore": {
    "BaseUrl": "https://your-bpmsoft-instance.com",
    "User": "Supervisor",
    "Password": "your-password",
    "ConnectionString": "Pooling=true;Database=...;Host=...;Username=...;Password=..."
  }
}

ConnectionString также можно опустить.

Шаг 3. Регистрация сервисов в DI

В Program.cs или Startup.cs:

using Tisa.BpmCore.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Регистрация BpmCore
builder.Services.AddBpmCore(builder.Configuration);

Или с ручной настройкой:

builder.Services.AddBpmCore(options =>
{
    options.BaseUrl = "https://your-bpmsoft-instance.com";
    options.User = "Supervisor";
    options.Password = "your-password";
    options.ConnectionString = "Pooling=true;Database=...";
    options.Timeout = TimeSpan.FromSeconds(60);
});

Использование

Получение UserConnection

UserConnection — центральный объект BPMSoft SDK для доступа к данным. BpmFactory создаёт и кеширует его (singleton, потокобезопасно).

Через IBpmCoreService (DI)

public class MyService
{
    private readonly IBpmCoreService _bpmCore;

    public MyService(IBpmCoreService bpmCore)
    {
        _bpmCore = bpmCore;
    }

    public void DoWork()
    {
        _bpmCore.ValidateToken("DEFAULT");
        var userConnection = BpmFactory.CreateUserConnection(_bpmCore);

        // Используйте userConnection для EntitySchemaQuery, Select и т.д.
    }
}

Через IConfiguration (без токенов)

var config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .Build();

var userConnection = BpmFactory.CreateUserConnection(config, "BpmCore");

Работа с данными BPMSoft (EntitySchemaQuery)

using BPMSoft.Core.Entities;

var esq = new EntitySchemaQuery(userConnection.EntitySchemaManager, "Contact");
esq.AddAllSchemaColumns();
var contacts = esq.GetEntityCollection(userConnection);

foreach (var contact in contacts)
{
    Console.WriteLine(contact.GetTypedColumnValue<string>("Name"));
}

Прямой доступ к БД через Npgsql

При вызове AddBpmCore(configuration) в DI автоматически регистрируется NpgsqlDataSource (singleton) с той же строкой подключения, что использует BpmFactory. Дублировать строку подключения не нужно.

Через DI (рекомендуется)

using Npgsql;

public class MyRepository(NpgsqlDataSource dataSource)
{
    public async Task<string?> GetContactNameAsync(Guid id, CancellationToken ct)
    {
        await using var cmd = dataSource.CreateCommand(
            "SELECT \"Name\" FROM \"Contact\" WHERE \"Id\" = @id");
        cmd.Parameters.AddWithValue("id", id);
        return (string?)await cmd.ExecuteScalarAsync(ct);
    }
}

Без DI

var cs = BpmFactory.GetConnectionString(configuration);
await using var dataSource = NpgsqlDataSource.Create(cs);
await using var conn = await dataSource.OpenConnectionAsync();

С EF Core

builder.Services.AddDbContext<MyDbContext>((sp, options) =>
{
    var cs = BpmFactory.GetConnectionString(builder.Configuration);
    options.UseNpgsql(cs);
});

BpmFactory.GetConnectionString() определяет строку подключения по тому же приоритету: appsettings.json → BPMSoft.WebHost.dll.config.

После первого вызова CreateUserConnection строка также доступна через свойство BpmFactory.ConnectionString.

Режимы инициализации

BpmFactory автоматически выбирает режим в зависимости от наличия конфигурационного файла:

Полный режим необходим для автономных приложений, работающих напрямую с БД BPMSoft. Упрощённый может использоваться в окружениях, где платформа уже инициализирована хостом.

Диагностика

При полной инициализации BpmFactory записывает подробный лог в файл bpmfactory-diag.log в директории приложения. Лог содержит:

• Состояние Redis-конфигурации на каждом этапе
• Результаты инициализации HttpContext
• Статус ClassFactory и CoreApiContainer
• Ошибки загрузки сборок и Workspace

При возникновении ошибок проверьте этот файл в первую очередь.

Структура проекта

Tisa.BpmCore/
├── Abstractions/       # Интерфейсы (IBpmCoreService, IBpmClient, ...)
├── Clients/            # HTTP-клиенты для REST API BPMSoft
├── Data/               # Модели данных
├── Exceptions/         # Кастомные исключения
├── Extensions/         # Методы расширения (AddBpmCore, ...)
├── Infrastructure/     # BpmFactory, BpmCoreService, BpmCoreOptions
├── Requests/           # Модели запросов
├── Responses/          # Модели ответов
└── Resources/          # Ресурсы

Требования

• .NET 8.0 SDK или выше
• PostgreSQL (или MSSQL — требуется изменить секцию db/general в конфиге)
• Redis — для кеширования и сессий BPMSoft
• BPMSoftSDK — подтягивается автоматически как транзитивная зависимость

Безопасность

• Не храните пароли и строки подключения в системе контроля версий
• Для локальной разработки используйте User Secrets
• В production используйте Azure Key Vault, HashiCorp Vault или переменные окружения
• Файл BPMSoft.WebHost.dll.config из пакета содержит шаблонные значения — замените их перед использованием
• Путь к конфигурации можно задать через переменную окружения BPMSOFT_CONFIG_PATH

FAQ

Ошибка: «Группа секций 'bpmsoft' не найдена в конфигурации»

Файл BPMSoft.WebHost.dll.config отсутствует в выходной директории или повреждён. Убедитесь, что:

1. Пакет Tisa.BpmCore установлен
2. Файл копируется при сборке (проверьте bin/Debug/net8.0/BPMSoft.WebHost.dll.config)
3. Файл содержит корректную секцию <bpmsoft> с типом BPMSoft.Core.AppConfigurationSectionGroup

Ошибка: «Строка подключения не найдена»

Строка подключения не найдена ни в одном из источников. Укажите её хотя бы в одном месте:

• BPMSoft.WebHost.dll.config — секция <connectionStrings>, элемент с name="db"
• appsettings.json — поле ConnectionString в секции BpmSoft или BpmCore
• Переменная окружения BpmSoft__ConnectionString или BpmCore__ConnectionString

Как использовать MSSQL вместо PostgreSQL?

В файле BPMSoft.WebHost.dll.config замените секцию <db><general .../> — укажите типы движков MSSQL:

<db>
    <general connectionStringName="db"
             securityEngineType="BPMSoft.DB.MSSql.MSSqlSecurityEngine, BPMSoft.DB.MSSql"
             executorType="BPMSoft.DB.MSSql.MSSqlExecutor, BPMSoft.DB.MSSql"
             engineType="BPMSoft.DB.MSSql.MSSqlEngine, BPMSoft.DB.MSSql"
             metaEngineType="BPMSoft.DB.MSSql.MSSqlMetaEngine, BPMSoft.DB.MSSql"
             metaScriptType="BPMSoft.DB.MSSql.MSSqlMetaScript, BPMSoft.DB.MSSql"
             typeConverterType="BPMSoft.DB.MSSql.MSSqlTypeConverter, BPMSoft.DB.MSSql"
             binaryPackageSize="1048576" currentSchemaName="dbo"/>
</db>

И добавьте соответствующую строку подключения:

<add name="db" connectionString="Data Source=localhost;Initial Catalog=YOUR_DB;User ID=sa;Password=YOUR_PASSWORD;Encrypt=False;"/>

Как переопределить файл конфигурации в своём проекте?

Если шаблонный конфиг из пакета не подходит, создайте свой BPMSoft.WebHost.dll.config в корне проекта:

<ItemGroup>
  <Content Include="BPMSoft.WebHost.dll.config">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </Content>
</ItemGroup>

Локальный файл приоритетнее файла из пакета благодаря PreserveNewest.

Лицензия

MIT License

Поддержка

По вопросам и сообщениям об ошибках: support@tisn.ru