Skip to main content
Version: 8.2

Assembly package

Level: advanced

An assembly package is a package whose source and automatically generated code is compiled into a separate assembly. 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​

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: Package structure.

Creatio adds or updates auxiliary files of the assembly package in the following cases:

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

View auxiliary files of the assembly package in the table below.

Auxiliary file

Description

SomePackage.csproj

The project file that contains the assembly package to compile.

Directory.Build.targets

The file that excludes the assembly package from the main configuration compilation.

Assembly package dependencies​

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 the current package, Creatio adds a link to an external assembly to an assembly package automatically.

  • If you need to use an external assembly from another package:

    1. Add a link to an external assembly from the current assembly package in multiple ways:

      • using the existing 3rd Party References section (recommended)

        1. Open the SomePackage.csproj file of the assembly package.
        2. Reference the required external assembly using the section of external libraries (<ItemGroup Label="3rd Party References"></ItemGroup>).

        View an example that links to:

        • Quartz.dll library located in the core
        • third-party library located in a simple package from the ..\Terrasoft.Configuration\Lib directory
        • CrtBaseConsts.dll library located in an assembly package from the ..\Terrasoft.Configuration\Lib directory
        Example that links to external assemblies
        <ItemGroup Label="3rd Party References">
            <!-- Example that adds a library from the core. -->
            <Reference Include="Quartz">
                <HintPath>$(CoreLibPath)\Quartz.dll</HintPath>
                <Private>false</Private>
            </Reference>
            <!-- Example that adds a library from a simple package. -->
            <Reference Include="ClassLibrary2">
                <HintPath>$(ConfLibPath)/ClassLibrary2.SomePackage.dll</HintPath>
                <SpecificVersion>False</SpecificVersion>
                <Private>False</Private>
            </Reference>
            <!-- Example that adds a library from an assembly package. -->
            <Reference Include="IntegrationApi">
                <HintPath>$(RelativePkgFolderPath)/CrtBaseConsts/Autogenerated/Lib/IntegrationApi.CrtBaseConsts.dll</HintPath>
                <SpecificVersion>False</SpecificVersion>
                <Private>False</Private>
            </Reference>
        </ItemGroup>
      • using custom section

        Learn more: Understanding the project file (official Microsoft documentation).

    2. Ensure the required external assembly is available for all dependent packages. To do this, set the IsPublic column value for the required external assembly in the SysPackageReferenceAssembly database table to true directly in the database or using data binding. Learn more: Bind data to the package.

      In dependent packages, references to public libraries are generated in the section of standalone package external assembly references (<ItemGroup Label="Standalone package external assembly references"></ItemGroup>) automatically.

note

We do not recommend adding a link to an external assembly from another package to the current package using other assembly package sections since all other sections are generated automatically and manual changes are overridden after compilation.

If you compile the package using Creatio IDE, the TargetFramework of the project will match the TargetFramework of the core. If you compile the package using 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.

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 at the development stage and includes the runtime assembly.
  • Creatio restarts the website, 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: 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: Configure object events.
  • The C# code of the package does not support usage 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. Open the Configuration section. Instructions: Open the Configuration section.

  2. Create a package. To do this, click in the package workspace. This opens the Package window.

  3. Fill out the package properties. The Compile into a separate assembly checkbox that marks a package as assembly package is selected out of the box.

  4. Save the changes.

  5. Set up the package dependencies. Instructions: Set up the package dependencies.

  6. Implement custom functionality.

  7. Compile the assembly package in Creatio .NET Framework. Read more >>>

  8. Transfer the assembly package to a .NET environment.

  9. Compile the transferred assembly package. Read more >>>

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

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. Add an assembly package. Read more >>>

  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 a single configuration element, click → Move to another package in the menu of the package from which to move the configuration elements.

  5. Compile the configuration. Instructions: Compile the configuration.

  6. Update the dependencies of inheritor packages. To do this, 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​

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

Compile an assembly package for both Creatio .NET Framework and .NET. 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. Read more >>>

  2. Install an assembly package into a Creatio instance that uses a different framework. For example, install the assembly package into Creatio .NET 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: Transfer the package.

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

  4. Export the compiled assembly package similarly to a simple package. Instructions: Transfer the package.

    As a result, 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 for Creatio .NET Framework.
    • ..\Terrasoft.WebApp\Terrasoft.Configuration\Pkg[Package name]\Files\Bin\netstandard[Package name].dll for Creatio .NET.
    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 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. 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, go to the Creatio IDE's toolbar → drop-down list of the Compile button → click the Compile all button.

To compile the assembly package:

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

  2. Publish the schema. 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.

  • 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 for Creatio .NET Framework.
    • ..\Terrasoft.WebApp\Terrasoft.Configuration\Pkg[Package name]\Files\Bin\netstandard[Package name].dll for Creatio .NET.

Compile an assembly package (command line)​

Important

Compile an assembly package for Creatio .NET Framework and .NET 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 using the command line in multiple ways:

  • Run the commands below at the command line interface (command prompt).
  • Create and execute *.cmd or *.bat files that include the commands below.
Commands that compile an assembly package for Creatio .NET Framework and .NET
set csprojPath = C: \Creatio\ Terrasoft.WebApp\ Terrasoft.Configuration\ Pkg\ SomePackage\ Files\ SomePackage.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

Where SomePackage is the assembly package name.

As a result, Creatio will:

  • compile the assembly packages for .NET Framework and .NET.

  • 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 for Creatio .NET Framework.
    • ..\Terrasoft.WebApp\Terrasoft.Configuration\Pkg[Package name]\Files\Bin\netstandard[Package name].dll for Creatio .NET.

Deliver the binary files of the compiled assembly package together with the assembly package to other environments or publish them on Creatio Marketplace to ensure the functionality operates as intended.

Delete an assembly package​

To delete an assembly package, click → Delete in the menu of the package from which to move the configuration elements. Learn more about deleting a simple package: Manage packages.

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

See also​

OData basics

Configure object events

Packages overview

Environment overview

Creatio IDE overview

Delivery using the Configuration section

Convert a package

Resources​

Understanding the project file (official Microsoft documentation)