Skip to main content
Version: 8.1

Assembly package

Level: advanced

An assembly package is a package whose source and automatically generated code is compiled into a separate assembly. Since Creatio 8 Atlas, a new assembly package is created when you add a new package. This streamlines change transfer between environments.

The purpose of an assembly package is:

  • To streamline development. Since the assembly package is the only one compiled, the compilation time is reduced.
  • To accelerate feature deployment. Since the assembly package includes a precompiled part, the compilation is not necessary.

Assembly package structure and dependencies​

The assembly package structure in the file system is identical to the structure of a simple package. The main differences between an assembly package and a simple package are the values of Type (package type) and ProjectPath (relative path from the package root directory to the project file of the assembly package) properties in the descriptor.json file. Learn more about the structure of a simple package in a separate article: Package structure.

Creatio adds or updates auxiliary files of the assembly package:

  • when you download an assembly package to the file system with the file system development mode enabled
  • when you compile an assembly package with the file system development mode disabled
  • when you upload an assembly package to the version control system regardless of the file system development mode status

The auxiliary files of the assembly package:

  • [Package name].csproj is the project file that contains the assembly package to compile.
  • Directory.Build.targets is the file that excludes the assembly package from the main configuration compilation.

You can add a link to an external assembly to the current package in the following ways:

  • If you need to use an external assembly from another package, add a link to an external assembly from the current assembly package.
  • If you need to use an external assembly from the current package, Creatio adds a link to an external assembly to an assembly package automatically.

To add a link to an external assembly from another package to the current package:

  1. Open the [Package name].csproj file of the assembly package.
  2. Reference the required external assembly in any section of the file. The only exception is the Label="Package References" section that is generated automatically.

See an example that links to Quartz and a third-party library contained in the ...\Terrasoft.Configuration\Lib directory below.

Example with links to external assemblies
<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>

You can edit the [Package name].csproj file manually. The only exception is the Label="Package References" section that is generated automatically.

If you compile the package in Creatio IDE, the TargetFramework of the project will match the TargetFramework of the core If you compile the package in an external IDE, the default "net472" value will be used. The value is modifiable.

Unlike the main configuration project, the assembly package project does not include third-party libraries. If you require third-party libraries, connect the core abstractions or external package assemblies to the project file of the assembly package.

The assembly package contains the following link sections:

  • system libraries
  • external package assemblies (<ItemGroup Label="Package Assembly References"></ItemGroup>)
  • core libraries (<ItemGroup Label="Core References"></ItemGroup>)
  • libraries for dependent packages (<ItemGroup Label="Core References"></ItemGroup>)
  • external libraries (<ItemGroup Label="3rd Party References"></ItemGroup>)

Assembly package specifics​

  • Creatio saves the assembly package to the database.
  • Creatio copies the file content of the assembly package.
  • Creatio does not compile the configuration. The assembly package is already compiled on the development stage and includes the runtime assembly.
  • Creatio restarts the site, initializes the web services and class factories within the assembly package.

Recommendations for assembly package naming​

  • Do not use Terrasoft.Configuration namespace for the assembly package name.
  • Use the following pattern for the assembly package name: SomeMaintainer.SomePackageOrArea.SomeFunctionality. For example, Microsoft.Office360.Authorization.

Requirements for an assembly package​

  • Object access is not supported via the OData protocol version 3. Use the OData protocol version 4 to access objects in an assembly package. Learn more about OData in a separate article: OData basics.
  • Do not implement object business logic via event sub-processes in the Object Designer. Use EntityEventListener to work with the event model. The EntityEventListener event set does not match the Creatio IDE event model fully. Learn more about the Entity event layer in a separate article: Configure object events.
  • The C# code of the package does not support the use of Entity types (e. g., typecasting to them) or the creation of their instances using the new operator or reflection. This applies to code written in any IDE.
  • You cannot access new Entity object columns and methods within the assembly package via the Entity base class. For example, ColumnValues.GetByName(nameValues).
  • The types of the current assembly package are not available in the configuration. However, they are available for its dependency assembly packages.

Operations with assembly packages​

You can execute the following operations with assembly packages:

  • add an assembly package
  • move configuration elements to the assembly package
  • compile an assembly package
  • delete an assembly package

Add an assembly package​

  1. Click the button to go to the System Designer in Creatio .NET Framework.

  2. Click Advanced settings in the Admin area block.

  3. Click in the package workspace.

  4. Select the Compile into a separate assembly checkbox. Since Creatio 8 Atlas, the checkbox is selected by default.

  5. Create an assembly package and set up its dependencies.

  6. Code the custom functionality.

  7. Compile the assembly package in Creatio .NET Framework. Learn more about compiling an assembly package: Compile an assembly package.

  8. Transfer the assembly package to a .NET Core or .NET 6 environment.

  9. Compile the transferred assembly package. Learn more about compiling an assembly package: Compile an assembly package.

The platform order (.NET Framework and .NET Core/.NET 6) does not affect the development of an assembly package. However, it is important to compile it in both Creatio .NET Framework and .NET Core/.NET 6. This will enable users to use the package in both Creatio .NET Framework and .NET Core/.NET 6.

As a result, the assembly package will be ready for deployment to the end-users.

Move configuration elements to the assembly package​

  1. Prepare configuration elements for relocation to the assembly package by modifying the element code so that it follows the assembly package specifics.

  2. Create an assembly package. Learn more: Add an assembly package.

  3. Set up the assembly package dependencies. The assembly package dependencies must match the dependencies of the simple package from which to move the configuration elements.

  4. Move the configuration elements.

    • To move all configuration elements, click Move all elements in the menu of the package from which to move the configuration elements.

    • To move an individual configuration element, click Move to another package in the menu of the package from which to move the configuration elements.

  5. Compile the configuration.

  6. Update the dependencies of inheritor packages: change their parent package to the assembly package to which you moved the configuration elements.

As a result, Creatio will move the configuration elements to the assembly package.

Compile an assembly package​

The purpose of compiling the assembly package is to eliminate the need to recompile the entire configuration and accelerate development. Creatio lets you to compile an assembly package that contains C# code of configuration elements schemas.

Compile an assembly package for both Creatio .NET Framework and .NET Core/.NET 6. This lets you deliver an assembly package to other environments regardless of the framework. We do not recommend compiling an assembly package only for the framework of the current Creatio instance. In this case, the package must be compiled after the installation, which the user might not know.

You can compile an assembly package in several ways:

  • in a universal way
  • using the command line

Compile an assembly package in a universal way​

  1. Compile an assembly package in the current Creatio instance. You can use multiple compilation types.

  2. Install an assembly package into a Creatio instance that uses a different framework. For example, install the assembly package into Creatio .NET Core or .NET 6 if you developed the package in Creatio .NET Framework and vice versa. Install an assembly package together with all packages, dependencies, and configuration elements schemas. The installation of an assembly package is similar to that of a simple package. Learn more about installing a simple package in a separate article: Transfer the package.

  3. Compile the installed assembly package. You can use multiple compilation types.

  4. Export the compiled assembly package similarly to a simple package. Learn more about exporting a simple package in a separate article: Transfer the package.

    Creatio will save the binary files of the compiled assembly package to the following directories:

    • ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg[Package name]\Files\Bin[Package name].dll in Creatio .NET Framework.
    • ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg[Package name]\Files\Bin\netstandard[Package name].dll in Creatio .NET Core or .NET 6.
    Important

    Deliver the binary files of the compiled assembly package together with the assembly package to ensure the functionality operates as intended.

  5. Save the compiled assembly package (optional). Move the assembly package together with the binary files from ...\Files\Bin folder to the repository if you use a version control system. Save the assembly package and binary files both for Creatio .NET Framework and .NET Core/.NET 6 to the repository if you are going to use the package in both frameworks.

As a result, Creatio will compile the assembly package for .NET Framework and .NET Core/.NET 6. You can deliver the assembly packages to other environments or publish it on Creatio Marketplace.

Compilation types of assembly package:

  • compile the configuration and assembly packages
  • compile the assembly package

To compile the configuration and assembly packages, click the Compile all button in the drop-down list of the Compile button on the Creatio IDE’s toolbar.

To compile the assembly package:

  1. Click Compile in the package menu of Creatio IDE.

  2. Click Publish in the Source Code Designer. If you are editing a Source code type schema in an assembly package, Creatio compiles only the assembly package instead of the entire configuration. Otherwise, the entire configuration is compiled.

As a result, Creatio will compile the assembly package. If the assembly package inherits from uncompiled assembly packages, Creatio will compile them as well.

Creatio will save the binary files of the compiled assembly package to the following directories:

  • ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg[Package name]\Files\Bin[Package name].dll in Creatio .NET Framework.
  • ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg[Package name]\Files\Bin\netstandard[Package name].dll in Creatio .NET Core or .NET 6.

Compile an assembly package (command line)​

Important

Compile an assembly package for Creatio .NET Framework and .NET Core/.NET 6 using the command line if the current assembly package does not depend on other packages, including user-made packages.

You can compile an assembly package for Creatio .NET Framework and .NET Core/.NET 6 using the command line in several ways:

  • Run the commands below at the command line interface (command prompt).
  • Create and execute *.cmd or *.bat files that contain the commands below.
Commands that compile an assembly package for Creatio .NET Framework and .NET Core/.NET 6
set csprojPath = C: \Creatio\ Terrasoft.WebApp\ Terrasoft.Configuration\ Pkg\ PackageName\ Files\ PackageName.csproj
set framework_CoreLibPath = C: \frameworkDistributive\ 7.18 .5 .1990_ Studio_Softkey_MSSQL_ENU\ Terrasoft.WebApp\ bin
set framework_RelativePkgFolderPath = C: \frameworkDistributive\ 7.18 .5 .1990_ Studio_Softkey_MSSQL_ENU\ Terrasoft.WebApp\ Terrasoft.Configuration\ Pkg
set netCore_CoreLibPath = C: \netCoreDistributive\ 7.18 .5 .1989_ Studio_Linux_Softkey_PostgreSQL_ENU_NetCore
set netCore_RelativePkgFolderPath = C: \netCoreDistributive\ 7.18 .5 .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 is the assembly package name.

Creatio will save the binary files of the compiled assembly package to the following directories:

  • ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg[Package name]\Files\Bin[Package name].dll in Creatio .NET Framework.
  • ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg[Package name]\Files\Bin\netstandard[Package name].dll in Creatio .NET Core or .NET 6.
Important

Deliver the binary files of the compiled assembly package together with the assembly package to ensure the functionality operates as intended.

As a result, Creatio will compile the assembly packages for .NET Framework and .NET Core/.NET 6. You can deliver assembly packages to other environments or publish them on Creatio Marketplace.

Delete an assembly package​

To delete an assembly package, click Delete in the package menu in Creatio IDE, similarly to deleting a simple package.

Learn more about deleting a simple package in a separate article: Manage packages.

As a result, Creatio will delete the assembly package from the configuration.

See also​

OData basics

Configure object events

Packages overview

Environments overview

Configuration elements of the Client module type

Delivery using the Configuration section

Delivery in Creatio IDE

Convert a package