Installing modules from installation packages

✖
Copy to clipboard

You can install custom modules developed on other instances of Kentico using module installation packages.

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

After you install a custom module to another instance of Kentico, the module becomes sealed. On that instance you cannot:

  • Further customize the module
  • Uninstall the module
  • Create new installation packages for the module

Kentico version requirements of module packages

Module packages can be successfully installed only on Kentico instances that have the same version as the source instance, including minor hotfix versions. For example, you cannot install module packages created on a 8.2.16 instance on Kentico 8.2.15 or older. Module authors should include information about the minimum required Kentico version in the description of each module package.

Module packages from older versions can be installed on newer versions, but may cause problems or errors depending on the differences in the data structure and API of the two versions.

To install a custom module from an installation package, you need to:

  1. Add the module installation package to the Kentico solution
  2. Import database objects from the module installation package to the Kentico database

Installing modules on web farms

If you are installing a custom module on a site running in a web farm environment:

  1. Install the module package into the Kentico project for each web farm server
  2. Perform the import of the module’s database objects only on ONE of the web farm servers (into the web farm’s shared database)

Adding the module installation package to the Kentico solution

To add the files contained in the module installation package to the Kentico solution, you need to set up a custom NuGet feed. The feed must include the module installation package. See Hosting Your Own NuGet Feeds on NuGet.Docs for more details.

Adding the package to web application solutions

  1. Open the Kentico solution file in Visual Studio (using the WebApp.sln file).
  2. Make sure the module installation package is accessible on your NuGet feed.
  3. Open the NuGet packages management window of the solution’s CMSApp project.
    • Right-click the project in the Solution Explorer and select Manage NuGet Packages.
  4. Select the appropriate installation package.
  5. Install the package.
  6. Build the Kentico solution.

Adding the package to web site solutions

  1. Open the Kentico solution file in Visual Studio (using the WebSite.sln file).
  2. Make sure the module installation package is accessible on your NuGet feed.
  3. Open the NuGet packages management window of the solution’s CMS web site project.
    • Right-click the project in the Solution Explorer and select Manage NuGet Packages.
  4. Select the appropriate installation package.
  5. Install the package.

The files contained in the module installation package are now available in the CMSApp (web application) or CMS (web site) project in the Kentico solution. To finish the installation of the module, you need to import the module’s data into the Kentico database.

Importing database objects from the module installation package

Notes:

  • Kentico cannot automatically import certain types of database components, for example indexes and views. If the imported module requires such components, you need to run before.sql and/or after.sql SQL scripts as part of the installation.
    • If available, you can find the script files in the project’s ~/App_Data/CMSModules/<module code name>/Install/ folder after installing the package to the Kentico solution.
  • If you customized the path of the export/import folders for your installation of Kentico (using the CMSSiteUtilsFolderPath web.config key), you need to move the module installation package ZIP file from the default ~/CMSSiteUtils/Import/ folder to your custom folder, i.e. ~/<custom path>/Import/.

To finish the installation of the module:

  1. (Optional) Run the before.sql script against your Kentico database.
  2. Open the Modules application in the Kentico administration interface.
  3. Click Import module.
  4. Select the <module code name>_<version>.zip file.
  5. Click Next.
  6. Click Finish.
  7. (Optional) Run the after.sql script against your Kentico database.

The system installs the module and automatically assigns it to all available sites. You can access the module in the system’s administration interface.

The module is fully functional, but sealed. This means you cannot:

  • Further customize the module.
  • Delete the module or its core components (classes, settings, etc.).
  • Create installation packages for the installed module (you can only do that on the Kentico instance where the module was originally developed).