Creating installation packages for modules

The system allows you to transfer custom modules to other instances of Kentico using NuGet packages.

When creating modules that you wish to deploy as installation packages, you need to take additional steps during the development process. The module must be represented by a separate web application project inside the Kentico solution. Based on conventions , the installation package automatically includes files from specific folders and database objects related to the module.

The module project only exists on the Kentico instance that you use to develop the module. When you install the module on a different instance, all code (including code behinds of web forms and controls) is compiled inside the module DLL, and other files are integrated into the main Kentico project. Installation of modules is supported for both web application and web site type projects.

Module packages do not include any data stored in module classes. If you wish to provide default data along with your module, you can prepare additional export packages containing the data or an SQL script that creates the required data after the installation of the module.

To create an installation package for a custom module, you need to:

1. Create a separate project for the module in the Kentico solution
2. Develop the module (see Example - Creating a packageable module for an example)
3. Make sure the installation package includes database objects related to the module
4. Optional steps:
   • Add additional libraries to the module installation package
   • Configure the module’s custom settings
   • Prepare additional SQL scripts for the module installation
5. Create the module installation package

Limitations

Modules transferred via installation packages have the following limitations:

• To install or uninstall module packages, you need to open the target project in Visual Studio – the operations cannot be performed on certain types of deployed and running websites (for example on Microsoft Azure).

• You cannot use installation packages to transfer modules for development on other instances – the module always becomes sealed and uncustomizable after installation, and all code is compiled into a DLL. If you wish to develop the module on multiple instances, use export and import features instead.

• You cannot define dependencies between multiple module packages.

• Modules installed from packages cannot be directly downgraded to older versions. You can however uninstall a module and then install a package with an older version.

• You may encounter problems when using components (user controls etc.) from the main Kentico project inside the module’s project. This may make it difficult to develop custom web forms, user controls or web parts within packageable modules.

• If you transfer a web part with a custom layout as part of the module, the layout does not work correctly when Deployment mode is enabled.

• You cannot create installation packages for:

  • The default Kentico modules.
  • The default Custom module, which is intended for non-transferable customizations.
  • Modules installed from other installation packages.

Creating the module project

Before you can develop a module that supports the creation of installation packages, you need to prepare a web application project and include this project in the Kentico solution.

The following steps are necessary to maintain the proper folder structure within the Kentico solution:

1. Create the project
2. Copy the project files to the Kentico solution
3. Include the project in the Kentico solution

Creating the project

1. Open Visual Studio and create a new web application project.
   • Important: The project name must match the module’s code name.
   • Select the ASP.NET Web Application project template (Empty).
2. Delete the project’s Web.config file.
3. Rename the packages.config file to packages.<project name>.config.
4. In the project’s Properties folder, rename the AssemblyInfo.cs file to <project name>AssemblyInfo.cs.
5. Save the project.

Copying the project files to the Kentico solution

1. Open the project’s folder on your file system.

2. Edit the <project name>.csproj file and make sure the content reflects the changes in the names of the AssemblyInfo.cs and packages.config files.

   Copy

   
   
   
    <ItemGroup>
        <Content Include="packages.{project name}.config" />
    </ItemGroup>
    <ItemGroup>
        <Compile Include="Properties\{project name}AssemblyInfo.cs" />
    </ItemGroup>
   
   
    

3. Copy the <project name>.csproj file and packages.<project name>.config file (if present) to the CMS folder of your Kentico web project.

4. Copy <project name>AssemblyInfo.cs from the project’s Properties directory to the CMS\Properties folder of your Kentico web project.

Including the project in the Kentico solution

1. Open your Kentico solution in Visual Studio (using the WebApp.sln file).

2. Add your custom module project to the Kentico solution:

   1. In the Solution Explorer, right-click the solution.
   2. Click Add -> Existing Project…
   3. Select the <project name>.csproj file in the project’s CMS folder.

3. Add the required references to your custom module project:

   1. Right-click the project and select Add -> Reference.
   2. Open the Browse tab of the Reference manager dialog, click Browse and navigate to the Lib folder of your Kentico web project.
   3. Add a reference to the CMS.Core.dll library (and any others that you require for custom code).

4. Expand the Properties folder of the module project and edit <project name>AssemblyInfo.cs .

5. Add the AssemblyDiscoverable assembly attribute:

   Copy

   
   
   
   using CMS;
   
   [assembly:AssemblyDiscoverable]
   
   
   

6. Save the solution and all files.

The Kentico solution now contains a web application project representing your custom module. You can start developing the module. After you compile the module code into an assembly (i.e. build the project), the system automatically includes the resulting DLL when you create an installation package for the module.

The additional project only exists on the Kentico instance that you use to develop the module. When you install the module on a different instance, all code is already compiled inside the module’s DLL and other files are integrated into the main Kentico project.

Including database objects in the package

When creating module installation packages, the system automatically includes the following database objects that are directly related to the given module:

• Classes
• Permissions
• UI elements
• Setting categories and groups, including all contained setting keys

You can configure page types to be included in the installation packages of a specific custom module. Edit the page type in the Page types application and choose a module via the Include in module package selector.

By following naming conventions, you can also create objects of the following types that the system includes in the module’s installation packages:

• Web parts
• Web part categories
• Form controls

Adding additional libraries to the package

The system cannot automatically identify all dynamic link libraries (DLLs) required by your custom module. If your module uses third-party or custom libraries, you need to assign these libraries to the module before creating the installation package.

1. Open the Modules application and Edit () your custom module.

2. Switch to the Additional libraries tab.

3. Assign any number of libraries from the project’s bin folder:

   1. Click Add library.
   2. Select the library that you wish to include in the module’s installation package.
   3. Click Select.

When you create the module installation package, the package also contains the selected libraries.

Note: Do NOT assign DLLs that are part of the default Kentico project as additional libraries of module packages. This includes any DLL files in the CMS\bin folder of unmodified Kentico projects. Adding these libraries may cause the system to work incorrectly after installing or uninstalling the custom module package.

Configuring custom module settings

If you have defined custom settings for the module, we recommend configuring the default values of the settings before you create the installation package. Open the Settings application and set the desired (global) values for the module’s settings.

The setting values configured on the development instance are used by default when the module is installed on other instances of Kentico.

Preparing additional SQL scripts for the installation

Installation packages cannot automatically transfer certain types of database components, such as indexes and views. If you wish to deliver such components with the module, you need to manually prepare SQL scripts that create (and remove) the required database objects.

Add the script files into the following folders in the development project (create the folders if necessary):

• ~/App_Data/CMSModules/<module code name>/

  • Install – scripts run before or after the import of the module’s database objects (do not run when updating the module from an older version)
  • Update – scripts run before or after the import of database objects when updating the module from an older version
  • Uninstall – scripts run before or after the removal of the module’s database objects

In all cases, the script files must be named either before.sql or after.sql. In the uninstallation scripts, you typically need to remove objects that you created in the opposing installation scripts (for example Uninstall/before.sql to reverse Install/after.sql ).

The system automatically includes the script files into the module’s installation packages. When installing or uninstalling the module, the appropriate before.sql and after.sql scripts are executed against the target database.

Creating the module installation package

Once your custom module is fully developed, you can create the installation package in the Kentico administration interface:

1. Open the Modules application and Edit () your custom module.

2. On the General tab, fill in the module’s metadata:

   • Module description (Default value: No description provided)

   • Module version (Default value: 1.0.0)

   • Module author (Default value: Unknown)

     Tip: Developers can perform more advanced modifications of the module package metadata (i.e. the .nuspec XML manifest). Assign a custom handler to the system’s ModulePackagingEvents.BuildNuSpecManifest global event.

3. Click Save.

4. Click Create installation package.

   • The system opens a dialog showing the package’s metadata, and the files and objects included in the package.

5. Click Create.

The system creates the module installation package in the project’s export folder (CMS\CMSSiteUtils\Export by default). You can use the package to install the module on other instances of Kentico.

Preparing update packages for modules

If you make further changes to a module after creating an installation package, you can prepare a new version of the package at any time. Use the following procedure:

1. Add or update the files and database objects for the module.
2. Set a higher Module version number when editing the module on the General tab in the Modules application.
3. Create the installation package.

When installing the newer version of the package on an instance that already contains an older version of the module, the system adds any new files or database objects and updates existing ones. If the instance does not contain the module at all, the standard installation occurs.

Adding update SQL scripts

If you wish to perform additional database operations during the module update (for example add, update or remove database indexes and views), you need to manually prepare SQL scripts. You can use the update SQL scripts as a workaround for removing module-related objects from the database.

Add the script files into the ~/App_Data/CMSModules/<module code name>/Update folder in the development project (create the folder if necessary). The script files must be named either before.sql or after.sql. The system runs the scripts before or after the import of the module’s database objects (only when updating from an older module version to a newer one).

Reference - Custom module conventions

To ensure that the installation packages created for your custom modules contain the required files and database objects, you need to follow naming and location conventions, or directly assign objects to modules in the administration interface.

• File system conventions
• Conventions for database objects

File system conventions

Conventions for database objects