Пакет-сборка

Руководство
Сложный

Пакет-сборка — пакет, исходный и автогенерируемый код которого компилируется в отдельную сборку. Начиная с версии Creatio 8 Atlas при создании нового пакета по умолчанию создается пакет-сборка. Это позволяет быстрее и удобнее переносить изменения между средами.

Назначение пакета-сборки:

  • Увеличение скорости разработки за счет снижения времени компиляции, поскольку компилируется только пакет-сборка.
  • Увеличение скорости поставки функциональности за счет отсутствия необходимости компиляции, поскольку пакет-сборка содержит в себе предварительно скомпилированную часть.

Особенности пакета-сборки:

  • Не поддерживается доступ к объектам по протоколу OData версии 3. Для доступа к объектам в пакете-сборке используется протокол OData версии 4. Протокол OData описан в статье OData.
  • Не допускается реализация бизнес-логики объектов через событийные подпроцессы дизайнера объекта. Для работы с событийной моделью необходимо использовать EntityEventListener. Набор событий EntityEventListener не полностью соответствует событийной модели, доступной через Creatio IDE. Событийный слой Entity описан в статье Бизнес-логика объектов.
  • В C#-коде пакетов не допускается использование типов Entity (например, приведение к этим типам), создание экземпляров этих типов через оператор new или при помощи рефлексии, независимо от того, где создан этот экземпляр.
  • Новые колонки и методы объектов Entity, которые размещены в пакете-сборке, не доступны через базовый класс Entity (например, ColumnValues.GetByName(nameValues)).
  • Типы текущего пакета-сборки не доступны в конфигурации и доступны для других пакетов-сборок, которые зависят от текущего.

Структура и зависимости пакета-сборки 

Структура пакета-сборки в файловой системе не отличается от структуры простого пакета. Основное отличие пакета-сборки от простого пакета — значение свойств Type (тип пакета) и ProjectPath (относительный путь от корневого каталога пакета к файлу проекта пакета-сборки) файла descriptor.json. Структура простого пакета описана в статье Общие принципы работы с пакетами.

Вспомогательные файлы пакета-сборки создаются или актуализируются:

  • При выгрузке пакета-сборки в файловую систему, если режим разработки в файловой системе включен.
  • При компиляции пакета-сборки, если режим разработки в файловой системе выключен.
  • При фиксации пакета-сборки в системе контроля версий SVN с использованием инструментов Creatio IDE, независимо от статуса режима разработки в файловой системе. Подробнее читайте в статье Контроль версий в Creatio IDE.

Вспомогательные файлы пакета-сборки:

  • [Имя пакета].csproj — файл проекта, который содержит компилируемое содержимое пакета-сборки.
  • Directory.Build.targets — файл, который используется для исключения содержимого пакета-сборки из компиляции основной конфигурации.

Пакет-сборка позволяет ссылаться на внешние сборки.

Чтобы для пакета-сборки настроить ссылку на внешнюю сборку:

  1. Откройте файл [Имя пакета].csproj пакета-сборки.
  2. Добавьте необходимую внешнюю сборку в любую секцию файла. Исключением является секция Label="Package References", содержимое которой генерируется автоматически.

Пример настройки ссылок на Quartz и внешнюю библиотеку, которая содержится в каталоге ...\Terrasoft.Configuration\Lib приведен ниже.

Пример настройки ссылок на внешние сборки
<ItemGroup Label="3rd Party References">
    <Reference Include="Quartz">
        <HintPath>$(CoreLibPath)\Quartz.dll</HintPath>
        <Private>false</Private>
    </Reference>
    <Reference Include="ClassLibrary2">
        <HintPath>$(ConfLibPath)/ClassLibrary2.PackageName.dll</HintPath>
        <SpecificVersion>False</SpecificVersion>
        <Private>False</Private>
    </Reference>
</ItemGroup>

Содержимое файла [Имя пакета].csproj пакета-сборки допускается менять вручную. Исключением является секция Label="Package References", содержимое которой генерируется автоматически.

При компиляции через Creatio IDE TargetFramework проекта соответствует TargetFramework ядра. При компиляции через внешнюю IDE используется значение по умолчанию "net472", которое при необходимости можно изменить.

В отличие от основного проекта конфигурации, в проект пакета-сборки не включены сторонние библиотеки. Для работы со сторонними библиотеками в файл проекта пакета-сборки подключите абстракции ядра или внешние сборки пакета.

Секции со ссылками, которые содержатся в пакете-сборке:

  • Системные библиотеки.
  • Внешние сборки пакета (<ItemGroup Label="Package Assembly References"></ItemGroup>).
  • Библиотеки ядра (<ItemGroup Label="Core References"></ItemGroup>).
  • Библиотеки зависимых пакетов (<ItemGroup Label="Package References"></ItemGroup>).
  • Внешние сборки (<ItemGroup Label="3rd Party References"></ItemGroup>).

Создать пакет-сборку 

  1. В приложении на платформе .NET Framework перейдите в дизайнер системы по кнопке .
  2. В блоке Конфигурирование разработчиком (Admin area) перейдите по ссылке Управление конфигурацией (Advanced settings).
  3. В области работы с пакетами нажмите кнопку .

  4. Установите признак Компилировать в отдельную сборку (Compile into a separate assembly). Начиная с версии Creatio 8 Atlas, признак установлен по умолчанию.

  5. Cоздайте пакет-сборку и установите его зависимости.
  6. Разработайте пользовательскую функциональность.
  7. В приложении на платформе .NET Framework выполните компиляцию пакета-сборки. Компиляция пакета-сборки описана в пункте Компилировать пакет-сборку.
  8. Перенесите пакет-сборку на другую рабочую среду на платформе .NET Core.
  9. Выполните компиляцию перенесенного пакета-сборки. Компиляция пакета-сборки описана в пункте Компилировать пакет-сборку.

Очередность использования платформ (.NET Framework и .NET Core) для разработки пакета-сборки не имеет значения. Важно выполнить компиляцию пакета-сборки в приложениях на платформах .NET Framework и .NET Core. Это позволит пользователям использовать пакет-сборку в приложениях на платформах .NET Framework и .NET Core.

В результате пакет-сборка будет доступен для поставки конечным пользователям.

Переместить конфигурационные элементы в пакет-сборку 

  1. Подготовьте конфигурационные элементы к перемещению в пакет-сборку, переписав код в соответствии с особенностями пакета-сборки.
  2. Создайте пакет-сборку. Создание пакета-сборки описано в пункте Создать пакет-сборку.
  3. Установите зависимости пакета-сборки. Зависимости пакета-сборки должны совпадать с зависимостями простого пакета, из которого планируется переместить конфигурационные элементы.

  4. Выполните перемещение конфигурационных элементов.

    • Чтобы переместить все конфигурационные элементы, в меню пакета, из которого планируется переместить конфигурационные элементы, нажмите Переместить все элементы (Move all elements).

    • Чтобы переместить отдельный конфигурационный элемент, в меню конфигурационного элемента нажмите Переместить в другой пакет (Move to another package).

  5. Выполните компиляцию конфигурации.
  6. Обновите зависимости дочерних пакетов: замените родительский пакет на пакет-сборку, в который были перенесены конфигурационные элементы.

В результате конфигурационные элементы будут перемещены в пакет-сборку.

Компилировать пакет-сборку 

Назначение компиляции пакета-сборки — ускорение разработки, поскольку отсутствует необходимость перекомпиляции всей конфигурации. Creatio позволяет выполнить компиляцию пакета-сборки, который содержит схемы конфигурационных элементов в C#-кодом.

Под компиляцией пакета-сборки необходимо понимать компиляцию пакета-сборки для платформ .NET Framework и .NET Core. Компиляция пакета-сборки для платформ .NET Framework и .NET Core выполняется для поставки пакета-сборки на другие рабочие среды вне зависимости от платформы приложения Creatio, на которое планируется выполнить поставку. Мы не рекомендуем выполнять компиляцию пакета-сборки только для платформы текущего приложения Creatio, поскольку в этом случае после поставки пакета в приложение необходимо выполнить его компиляцию, о чем может не знать пользователь.

Способы компиляции пакет-сборки для платформ .NET Framework и .NET Core:

  • Универсальный способ.
  • С использованием командной строки.

Компилировать пакет-сборку (универсальный способ) 

  1. Выполните компиляцию текущего пакета-сборки в текущем приложении Creatio. Для этого используйте один из видов компиляции.
  2. Установите пакет-сборку на платформу, которая отличается от платформы текущего приложения Creatio. Например, если пакет-сборка разработан в приложении Creatio на платформе .NET Framework, то установите пакет-сборку в приложение Creatio на платформе .NET Core и наоборот. Устанавливать необходимо пакет-сборку со всеми пакетами, зависимостями и схемами конфигурационных элементов. Установка пакета-сборки не отличается от установки простого пакета. Об установке простого пакета читайте в статье Перенос пакета.
  3. Выполните компиляцию установленного пакета-сборки. Для этого используйте один из видов компиляции.

  4. Экспортируйте скомпилированный пакет-сборку. Экспорт пакета-сборки не отличается от экспорта простого пакета. Об экспорте простого пакета читайте в статье Перенести пакеты.

    Бинарные файлы скомпилированного пакета-сборки сохраняются по пути:

    • ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg\[Имя пакета]\Files\Bin\[Имя пакета].dll для приложений на платформе .NET Framework.
    • ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg\[Имя пакета]\Files\Bin\netstandard\[Имя пакета].dll для приложений на платформе .NET Core.

    Важно. Необходимо выполнять поставку бинарных файлов скомпилированного пакета-сборки вместе с самим пакетом-сборкой. В другом случае функциональность будет неработоспособной.

  5. Сохраните скомпилированный пакет-сборку (опционально). Если для хранения пакета-сборки используется система контроля версий, то из каталога ...\Files\Bin в репозиторий перенесите пакет-сборку вместе с бинарными файлами скомпилированного пакетами-сборки. Если планируется использовать пакет-сборку в приложениях Creatio на платформах .NET Framework и .NET Core, то в системе контроля версий храните пакет сборку и бинарные файлы скомпилированных пакетов-сборок для обоих платформ.

В результате получаем скомпилированные пакеты-сборки для платформ .NET Framework и .NET Core, которые готовы к поставке на другие рабочие среды или к публикации на Marketplace.

Виды компиляции пакета-сборки:

  • Компиляция конфигурации и всех пакетов-сборок.

    Выполняется нажатием кнопки Перекомпилировать все (Compile all) в выпадающем списке кнопки Компилировать (Compile) панели инструментов Creatio IDE.

  • Компиляция текущего пакета-сборки.

    • Выполняется выбором пункта Компилировать (Compile) меню пакета Creatio IDE.

    • Выполняется нажатием кнопки Опубликовать (Publish) в дизайнере исходного кода. Если редактируемая схема типа Исходный код (Source code) находится в пакете-сборке, то будет выполнена компиляция только пакета-сборки, а не всей конфигурации. В другом случае будет выполнена компиляция всей конфигурации.

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

Бинарные файлы скомпилированного пакета-сборки сохраняются по пути:

  • ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg\[Имя пакета]\Files\Bin\[Имя пакета].dll для приложений на платформе .NET Framework.
  • ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg\[Имя пакета]\Files\Bin\netstandard\[Имя пакета].dll для приложений на платформе .NET Core.

Компилировать пакет-сборку (командная строка) 

Важно. Выполнять компиляцию пакет-сборки для платформ .NET Framework и .NET Core с использованием командной строки допускается, если текущий пакет-сборка не зависит от других пакетов, в том числе пользовательских.

Способы компиляции пакета-сборки для платформ .NET Framework и .NET Core с использованием командной строки:

  • В интепретаторе команд (консоли) выполните команды, которые приведены ниже.
  • Создайте, а затем выполните *.cmd или *.bat-файлы с командами, которые приведены ниже.
Команды для компиляции пакета-сборки для платформ .NET Framework и .NET Core
set csprojPath=C:\Creatio\Terrasoft.WebApp\Terrasoft.Configuration\Pkg\PackageName\Files\PackageName.csproj
set framework_CoreLibPath=C:\frameworkDistributive\8.0.1.1990_Studio_Softkey_MSSQL_ENU\Terrasoft.WebApp\bin
set framework_RelativePkgFolderPath=C:\frameworkDistributive\8.0.1.1990_Studio_Softkey_MSSQL_ENU\Terrasoft.WebApp\Terrasoft.Configuration\Pkg
set netCore_CoreLibPath=C:\netCoreDistributive\8.0.1.1989_Studio_Linux_Softkey_PostgreSQL_ENU_NetCore
set netCore_RelativePkgFolderPath=C:\netCoreDistributive\8.0.1.1989_Studio_Linux_Softkey_PostgreSQL_ENU_NetCore\Terrasoft.Configuration\Pkg
    
set CoreLibPath=%framework_CoreLibPath%
set RelativePkgFolderPath=%framework_RelativePkgFolderPath%
set CoreTargetFramework=net472

dotnet build %csprojPath%

set CoreLibPath=%netCore_CoreLibPath%
set RelativePkgFolderPath=%netCore_RelativePkgFolderPath%
set CoreTargetFramework=netstandard2.0

dotnet build %csprojPath%

Pause

PackageName — имя пакета-сборки.

Бинарные файлы скомпилированного пакета-сборки сохраняются по пути:

  • ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg\[Имя пакета]\Files\Bin\[Имя пакета].dll для приложений на платформе .NET Framework.
  • ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg\[Имя пакета]\Files\Bin\netstandard\[Имя пакета].dll для приложений на платформе .NET Core.

Важно. Необходимо выполнять поставку бинарных файлов скомпилированного пакета-сборки вместе с самим пакетом-сборкой. В другом случае функциональность будет неработоспособной.

В результате получаем скомпилированные пакеты-сборки для платформ .NET Framework и .NET Core, которые готовы к поставке на другие рабочие среды или к публикации на Marketplace.

Удалить пакет-сборку 

Удаление пакета-сборки не отличается от удаления простого пакета и выполняется в пункте Удалить (Delete) меню пакета Creatio IDE.

Об удалении простого пакета читайте в статье Creatio IDE.

В результате пакет-сборка будет удален из конфигурации приложения.

Особенности установки пакета-сборки 

  • Содержимое пакета-сборки помещается в базу данных.
  • Копируется файловый контент пакета-сборки.
  • Компиляция конфигурации не запускается, поскольку пакет-сборка был скомпилирован при разработке и содержит в себе runtime-сборку.
  • Выполняется перезапуск сайта, инициализация веб-сервисов и фабрики классов, которые содержатся в пакете-сборке.
Смотрите также
OData
Бизнес-логика объектов
Общие принципы работы с пакетами
Понятие рабочей среды
Клиентский модуль
Creatio IDE
Управление поставками в Creatio IDE
Контроль версий в Creatio IDE