Assembly package

Advanced
PDF

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.

The assembly package specifics:

  • 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.
  • 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: Business logic of objects.
  • 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.

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: Packages basics.

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.

An assembly package can link external assemblies.

To link to an external assembly from an assembly 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>)

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 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) does not affect the development of an assembly package. However, it is important to compile it in both Creatio .NET Framework and .NET Core. This will enable users to use the package in both Creatio .NET Framework and .NET Core.

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: Create 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 compile assembly packages that contain client module schemas (i. e., those with JavaScript code).

You can compile the assembly package in several ways:

  • Compile the configuration and all assembly packages.

    Click Compile all in the Compile drop-down list of the Creatio IDE toolbar.

  • Compile the current assembly package.

    • Click Compile in the package menu in Creatio IDE.

    • Alternatively, click Publish in the Source Code Designer. If you are editing a Source code type schema in an assembly package, Creatio will compile only the assembly package instead of the entire configuration. Otherwise, Creatio will compile the entire configuration.

As a result, Creatio will compile the assembly package. If assembly packages the current assembly package inherits are not compiled, Creatio will compile them as well.

Creatio will save the compiled assembly package to:

  • ...\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.

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: Creatio IDE.

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

Import an assembly package 

Import an assembly package similarly to importing a simple package. Learn more about importing a simple package in a separate article: Transfer the package.

The assembly package import 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.