Installing modules from installation packages

Development model: MVC Portal Engine
✖
Copy to clipboard

Module installation packages allow you to install custom modules developed on other instances of Kentico. You can also use newer versions of installation packages to update a previously installed module.

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
  • 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 9.0.16 instance on Kentico 9.0.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 or update a custom module from an installation package, you need to:

  1. Add the module installation package to the Kentico solution
  2. Open the website in a browser, which triggers an automatic import of the database objects from the module installation package

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.

Installing modules on web farms

If you are installing a custom module on an application running in a web farm environment, you need to install the module package into the Kentico project for each web farm server.

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 in 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 Package source and installation package.
  5. Install or upgrade 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 Package source and installation package.
  5. Install or upgrade 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.

Importing database objects from the module installation package

To finish the module installation or update, open your Kentico application in a browser. During the processing of the first request after you added the module, the system automatically imports database objects from the module installation package, and assigns the module to all available sites.

Tip: You can add multiple custom modules to the Kentico solution, and then perform the import of the database objects using a single request.

You can verify that the module was installed successfully in the Event log application – confirm that the log contains an event with the MODULEINSTALLED or MODULEUPDATED code (ModuleInstaller as the source) and no related errors. View the event details () for information about the modules that were installed.

Note: Module installation packages may provide before.sql and/or after.sql SQL scripts that create certain types of database components, such as for example indexes and views. The system automatically runs these scripts before and after the import of the module’s database objects. If necessary, you can find the script files in the project’s ~/App_Data/CMSModules/<module code name>/ directory under the Install or Update subfolders.

After the installation, 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.
  • Manually delete the module or its core components (classes, settings, etc.). You can remove the module by uninstalling the package.
  • Create installation packages for the installed module (you can only do that on the Kentico instance where the module was originally developed).

Recovering installed modules after a database rollback

If you roll back your database to a state before the installation of a custom module, the automatic database installation will not run again for the module. The module’s files remain in the solution, but the corresponding objects are missing in the database.

To recover the module in such scenarios, you need to:

  1. Uninstall the module’s NuGet package from the solution (see Uninstalling module).
  2. Open the application in a browser and allow it to process at least one request.
  3. Repeat the full installation of the module (install the module package in Visual Studio and then open the application in a browser).

The problem only occurs if you do not roll back your code base along with the database.