--- title: Creating installation packages for modules --- > Agent instructions: > **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown. > > - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version. > - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt). The system allows you to transfer custom modules to other instances of Kentico using [NuGet packages](https://www.nuget.org/). 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](#reference---custom-module-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](https://docs.kentico.com/k10/custom-development/creating-custom-modules/creating-installation-packages-for-modules/installing-modules-from-installation-packages.md) 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](https://docs.kentico.com/k10/deploying-websites/exporting-and-importing-sites/exporting-objects.md) containing the data or an [SQL script](#preparing-additional-sql-scripts-for-the-installation) that creates the required data after the installation of the module. > **Info:** **Limitations** > > Modules transferred via installation packages _currently_ 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](https://docs.kentico.com/k10/deploying-websites/exporting-and-importing-sites/exporting-objects.md) and [import ](https://docs.kentico.com/k10/deploying-websites/exporting-and-importing-sites/importing-a-site-or-objects.md)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 (see the [Creating module installation packages](https://devnet.kentico.com/articles/creating-module-installation-packages) article to learn more). > - If you transfer a web part with a [custom layout](https://docs.kentico.com/k10/custom-development/developing-web-parts/using-custom-web-part-layouts.md) as part of the module, the layout does not work correctly when [Deployment mode](https://docs.kentico.com/k10/deploying-websites/deployment-mode-for-virtual-objects.md) 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. **To create an installation package for a custom module, you need to**: 1. [Create a separate project for the module in the Kentico solution](#creating-the-module-project) 2. Develop the module (see [Example - Creating a packageable module](https://docs.kentico.com/k10/custom-development/creating-custom-modules/creating-installation-packages-for-modules/example-creating-a-packageable-module.md) for an example) 3. [Make sure the installation package includes database objects related to the module](#including-database-objects-in-the-package) 4. Optional steps: - [Add additional libraries to the module installation package](#adding-additional-libraries-to-the-package) - [Configure the module's custom settings](#configuring-custom-module-settings) - [Prepare additional SQL scripts for the module installation](#preparing-additional-sql-scripts-for-the-installation) 5. [Create the module installation package](#creating-the-module-installation-package) ## Creating the module project > **Note:** We strongly recommend using _web application_ installations of Kentico when developing custom modules that you wish to deploy as installation packages. > > Module projects must always use the [web application format](http://msdn.microsoft.com/en-us/library/dd547590.aspx) – having the same project type for the main Kentico project makes it easier to reuse files. With _web site_ projects, you need to manually ensure that all module files are converted to the web application format. 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](#creating-the-project) 2. [Copy the project files to the Kentico solution](#copying-the-project-files-to-the-kentico-solution) 3. [Include the project in the Kentico solution](#including-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. If the project contains a _packages.config_ file (when using Visual Studio 2015), rename it to _packages..config_. 4. In the project's **Properties** folder, rename the _AssemblyInfo.cs_ file to _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 _.csproj_ file and make sure the content reflects the changes in the names of the _AssemblyInfo.cs_ and _packages.config_ files. ```xml ``` 3. Copy the _**.csproj**_ file and _**packages..config**_ file (if present) to the **CMS** folder of your Kentico web project. 4. Copy _**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 _.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 _**AssemblyInfo.cs**_ . 5. Add the **AssemblyDiscoverable** assembly attribute: ```csharp 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](https://docs.kentico.com/k10/custom-development/creating-custom-modules/creating-installation-packages-for-modules/installing-modules-from-installation-packages.md) on a different instance, all code is already compiled inside the module's DLL and other files are integrated into the main Kentico project. > **Info:** **Note**: If you ever need to rename a module during development, **Clean** your solution in Visual Studio **before** you rename the module project or manually delete the original DLL. Otherwise the module's old DLL may cause errors on your site. ## Including database objects in the package When [creating](#creating-the-module-installation-package) 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](https://docs.kentico.com/k10/developing-websites/defining-website-content-structure/page-types.md) 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](#conventions-for-database-objects) , you can also create objects of the following types that the system includes in the module's installation packages: - [Web parts](https://docs.kentico.com/k10/custom-development/developing-web-parts.md) - Web part categories - [Form controls](https://docs.kentico.com/k10/custom-development/developing-form-controls.md) > **Note:** **Note**: Module installation packages cannot transfer other types of database objects, such as for example [scheduled tasks](https://docs.kentico.com/k10/configuring-kentico/scheduling-tasks.md). You can create separate [export packages](https://docs.kentico.com/k10/deploying-websites/exporting-and-importing-sites/exporting-objects.md) for additional objects and deliver them together with your module's installation package. ## 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_ or _CMS\CMSDependencies_ folders 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](https://docs.kentico.com/k10/custom-development/creating-custom-modules/adding-custom-website-settings.md) 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//** - **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](https://docs.kentico.com/k10/custom-development/creating-custom-modules/creating-installation-packages-for-modules/installing-modules-from-installation-packages.md) or [uninstalling](https://docs.kentico.com/k10/custom-development/creating-custom-modules/creating-installation-packages-for-modules/uninstalling-modules.md) 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_) > **Info:** The system saves the values into the metadata of the module's installation packages. If not specified, the package contains the default values. 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](https://docs.kentico.com/k10/custom-development/creating-custom-modules/creating-installation-packages-for-modules/installing-modules-from-installation-packages.md) the module on other instances of Kentico. > **Note:** **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, if you create a module installation package on a 9.0.16 instance, users cannot install the package on Kentico 9.0.15 or older. We strongly recommend adding information about the minimum required Kentico version into the _**Module description**_ . > > 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. ## 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](https://docs.kentico.com/k10/custom-development/creating-custom-modules/creating-installation-packages-for-modules/installing-modules-from-installation-packages.md) 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. > **Note:** **Limitation**: The module update functionality does not automatically support _**removing**_ of database objects related to the module (classes, web parts, form controls etc.). If the newer version of the module installation package does not contain an object that exists in an older version, updating the module will NOT automatically remove the given object on the target instance. ### 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//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). > **Tip:** **Adjusting the update scripts based on the original module version** > > When running the scripts during the update of a module, the system supplies the original version number of the module via the **@FromVersion** SQL parameter. You can use the parameter to branch your module's update scripts and perform different operations according to the module version from which you are updating. ## 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](#file-system-conventions) - [Conventions for database objects](#conventions-for-database-objects) > **Info:** **Module code name** > > The naming conventions for folders, files and database objects are based on the **Module code name**, including any prefixes or namespaces. For example: _Acme.Forums_ > > Carefully consider the code name when creating custom modules. Choose a _**sufficiently unique**_ module code name to avoid collisions with the default Kentico modules or other custom modules. Do NOT start the code names of custom modules with the **cms.** prefix, which is reserved for Kentico modules. ### File system conventions > **Note:** **Important** > > Include all custom files related to your module into the module's web application project in Visual Studio, NOT the default Kentico web project (_CMSApp_). > > Both projects share the same folder on the file system, so you can include files located in the default Kentico folders (such as _\~/App\_Data/CMSModules_ or _\~/CMSWebParts_) without problems. When the module package is installed on a different instance, files from both projects are merged into the standard Kentico project. > > Including files in the module project ensures that: > > - Custom module files are clearly separated in your development solution from the default files. > - All required code is compiled into the module's DLL. Module installation packages transfer all code within the module DLL, without the original code files. Files with separate code behinds (web forms, user controls, web parts, form controls, handlers, etc.) are installed without the code behind and instead reference the appropriate class in the module DLL. | Module component | Convention | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Module library | The library containing the module's compiled code must be located in the _\~/bin_ folder of the Kentico project and have the same name as the module code name. For example, the _Acme.Forums_ module has the _Acme.Forums.dll_ library.
As long as the module's web application project in the Kentico solution matches the module name, the library is created automatically when you compile the project. | | 3rd party libraries | You can [manually include 3rd party libraries](#adding-additional-libraries-to-the-package) into the module's installation package using the administration interface. The libraries must be located in the _\~/bin_ folder of the Kentico project. | | Code files | All code files must be included in the module's web application project in Visual Studio. Examples of module code files are:
_Info_ and _InfoProvider_ files of the module's classes
The file containing the module's [initialization code](https://docs.kentico.com/k10/custom-development/creating-custom-modules/initializing-modules-to-run-custom-code.md)
[User interface extenders](https://docs.kentico.com/k10/custom-development/creating-custom-modules/creating-extenders-for-module-interface-pages.md)
We recommend organizing the code files inside a folder that matches the code name of the module, for example: _\~/Acme.Forums/_ | | Web forms and controls | Place web forms or user controls used by your module into the **_\~/CMSModules/__/_** folder. | | Web part files | Place the source files (user controls) of [web parts](https://docs.kentico.com/k10/custom-development/developing-web-parts.md) that are part of your module into the _**\~/CMSWebParts//**_ folder.
For example: _**\~/CMSWebParts/Acme.Forums/**_ | | Form control files | Place the source files (user controls) of [form controls](https://docs.kentico.com/k10/custom-development/developing-form-controls.md) that are part of your module into the _**\~/CMSFormControls//**_ folder.
For example: _**\~/CMSFormControls/Acme.Forums/**_ | | UniGrid definitions | Place the XML definitions for the module's [UniGrid](https://docs.kentico.com/k10/references/kentico-controls/ui-controls/unigrid.md) components (object listings) into the _**\~/App\_Data/CMSModules//UI/Grids/**_ folder.
The default recommended location includes further subfolders named after specific object types. For example: _\~/App\_Data/CMSModules/Acme.Forums/UI/Grids/_ _Acme\_Forums\_Forum/default.xml_ | | Resource strings | Place the module's [resource strings](https://docs.kentico.com/k10/multilingual-websites/setting-up-a-multilingual-user-interface/working-with-resource-strings.md) into _resource files (.resx)_ inside the _**\~/CMSResources//**_ folder. To add resource files for specific languages, create subfolders with names that match the required _culture code_.
For example, _\~/CMSResources/Acme.Forums/Common.resx_ for strings in the default culture, and _\~/CMSResources/Acme.Forums//Common.resx_ for the __ culture.
Note: If you plan to [publish](https://docs.kentico.com/k10/deploying-websites/publishing-projects-from-visual-studio.md) your development project, set the [Build Action](https://msdn.microsoft.com/en-us/library/0c6xyb66%28v=vs.100%29.aspx) property of resource files to **Content** to ensure that they are included. The Build Action of resx files is automatically set to _Content_ when installing module packages on other instances\*.\* | | JavaScript files | If your module uses JavaScript files, place them into the _**\~/CMSScripts/CMSModules//**_ folder.
For example: _\~/CMSScripts/CMSModules/Acme.Forums/TextBox.js_ | | CSS | If your module uses physical CSS files, place them into the _**\~/CMSModules//Content/**_ folder.
For example: _\~/CMSModules//Content/Forums.css_
To add links to module stylesheets on pages, call the following methods (in the code behind of pages or components such as form controls):
_ModuleCssRegistration.RegisterModuleStylesheets_ - adds links for all stylesheets of the specified module.
_ModuleCssRegistration.RegisterModuleStylesheet_ - adds a link for one particular module stylesheet.
The **ModuleCssRegistration** class is located in the _CMS.Base.Web.UI_ namespace. | | HTTP handlers | If your module uses HTTP handlers or other types of system pages, place them into the **_\~/CMSModules/__/CMSPages/_** folder.
For example: _\~/CMSModules/Acme.Forums/CMSPages/GetAttachmentHandler.ashx_ | ### Conventions for database objects | Object type | Convention | | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Web part](https://docs.kentico.com/k10/custom-development/developing-web-parts.md) | The code names of web parts must start with the _**.**_ prefix (including the dot character).
For example: _**Acme.Forums.ForumList**_
Module installation packages automatically include the parent categories of web parts that match the naming convention. | | Web part category | The code names of web part categories (**Category name** field) must start with the _**.**_ prefix (including the dot character).
For example: _**Acme.Forums.WebpartCategory**_
Including a web part category into the module installation package does NOT automatically include all web parts inside the given category. The web parts are only included if their code name matches the module naming convention.
You only need to use the module name convention for web part categories to ensure that the system deletes the categories and their entire content when the [module package is uninstalled](https://docs.kentico.com/k10/custom-development/creating-custom-modules/creating-installation-packages-for-modules/uninstalling-modules.md). | | [Form control](https://docs.kentico.com/k10/custom-development/developing-form-controls.md) | The code names of form controls must start with the _**.**_ prefix (including the dot character).
For example:  _**Acme.Forums.TextBox**_ | | [Page type](https://docs.kentico.com/k10/developing-websites/defining-website-content-structure/page-types.md) | Pages types do not use module naming conventions. To include a page type into the installation packages of a custom module:
Open the **Page types** application.
Edit the page type.
On the **General** tab, select the module in the **Include in module package** property (you can only choose custom modules that are still in development mode).
Click **Save**.
**Note**: After you include a page type into the installation packages of a module, you can no longer specify on which _Sites_ the page type is available. The page type automatically uses the site bindings of the given module, which you can edit in the _Modules_ application. |