How to Deploy Kentico Custom Modules

By Dustin Christians On July 03, 2019

How to Deploy Kentico Custom Modules
Recently, I created a Kentico custom module for a Kentico 11 web application and needed to deploy it to other Kentico sites. Sometimes, depending on the module, this can require too many steps to remember especially if the module isn’t updated very often. I also realized that our client would need to maintain the module and deploy it to their other sites in the future. So, I created some instructions for them to follow and figured others would benefit from this tutorial as well. Let’s get started!

Recommended Deployment Procedure within Kentico

  1. Best practices say to keep module files separate from the CMSApp and independently compilable as their own projects. I did this so the module could easily be reused in another project. The resulting project should be added as a reference to the CMSApp project. The content files (aspx, ascx, xml files) should only be included in the module project and NOT included in the CMSApp. The content files should be deployed/published separately from the CMSApp project but they should be deployed/published to the same location as the CMSApp on the server. Once deployed they will mix in with the CMSApp and function as if they were always included within the CMSApp.
  2. The Kentico Module is stage-able and can be synced to another site but it is recommended that it be exported as a package and imported into another site. Otherwise, the custom queries that exist as a part of the classes will not get synced to the next site. Follow these export/import steps initially and every time you make a change and need to redeploy a module:
    1. Go to the "Sites" application in the Kentico administration interface and click the "Export" button:
    2. Then click next on the "Export type" screen as we don't want to preselect anything:
    3. On the objects selection screen uncheck the "Export tasks" and "Export files" checkboxes:
    4. Then expand the development section, select "Modules" and check the custom module.  Also, make sure the “seal the selected modules” checkbox is unchecked:
    5. click next and then click the download link to get the .zip file:
    6. Then, go to the "Sites" app on the next site and click the "Import site or objects" button:
    7. Upload the .zip file you downloaded previously with the "Preselect all items” option selected and click next:
    8. Uncheck anything selected for all objects, as shown below:
    9. Click the next button and the import process will execute. You should now see the module, classes, and queries on the import site.

Things to Keep in Mind When Deploying Kentico Module Files

  1. If a module is developed within the CMSApp project then you only need to deploy the CMSApp because all files are included and compiled within the CMSApp.
  2. If a module is created as its own project, then the module files will only be included in that project. If this is the case, then this project needs to be deployed separately from the CMSApp project.
    1. If you are deploying using a Visual Studio publishing profile, then you need to publish to the same location as the CMSApp project. The content files (aspx, ascx, xml files) and folders will mix in with the CMSApp project. The compiled code (.cs files) will be referenced from the module project’s DLL that should’ve been added as a reference to the CMSApp project prior to deployment.
    2. If you are intending to deploy a module as an export package as discussed in the next section, you can include the module files along with the export. However, this is not recommended because for web applications the import places all physical files from the imported package into the ~/App_Data/CMSTemp/ImportExport/Files folder (or a different folder if your application has the CMSTemporaryFilesFolderPath web.config key set to a custom folder) and you will need to manually copy the contents of the folder into the CMS folder of your web application project. This occurs because the files will need to be included in the solution before they will work as a part of the project. If you plan on doing this you can read more about importing to web application projects in the Kentico 12 documentation here.

Something to Keep in Mind When Deploying Kentico Module Objects

Kentico modules can be staged and synced to other sites but there are some things to consider before using this option. If classes exist as a part of the module they will not be staged with the rest of the module. Therefore, the module must be exported as a package. Look at the classes tab within the module to determine if it has classes:


 

Things to Keep in Mind When Exporting Kentico Module Objects

Should a module be sealed on export and what does this mean?



If you are planning to continue making changes to an imported module then you should not seal the module when it is exported.
  1. Another thing to keep in mind when exporting modules is that the classes may include queries. If a class is not “customizable” and they include queries, these queries will be taken out of development mode on the site they are imported into. This means that you cannot delete the query on the import site but you can edit the query. Also, if you export the module again from the import site when the queries are in this state they will not be included in the next export.  If you have classes with queries involved, and you want to export the module again with everything in an editable state then the best solution is to set the classes to “Is Customizable”. This will ensure that everything gets exported properly from any site in the pipeline and remains editable. 
  2. You can determine if a class is customizable by looking at the classes tab of the module:
  3. You can set a class to customizable using this setting:
  4. If you find that the queries are already out of development mode (the trash can is grey instead of green) and you need to put them back into development mode the only way to put them back into development mode is to run this SQL update statement:

    UPDATE CMS_Query
    SET QueryIsCustom = 1
    WHERE QueryName IN ('CustomQueryOne', 'CustomQueryTwo',)
     
  5. If you find that the module is sealed, and you would like to unseal it you can accomplish this by running the following query (update the ResourceName value to the name of the module you need to unseal):

    UPDATE CMS_Resource
    SET ResourceIsInDevelopment = 1
    WHERE ResourceName = 'UserAssignment' 

How to Deploy Kentico Modules

In conclusion, I follow these steps when deploying modules:
  1. When developing modules I create a separate project in the solution to keep the files separate from the CMSApp project.
  2. If a module is created as its own project then this project needs to be deployed separately from the CMSApp project.
  3. If a module is developed within the CMSApp project then you only need to deploy the CMSApp because all files are included and compiled within the CMSApp.
  4. Kentico modules can be staged and synced to other sites. However, if classes exist as a part of the module they will not be staged with the rest of the module. Therefore, the module must be exported as a package.
  5. If you are planning to continue making changes to an imported module then you should not seal the module when it is exported.
  6. Set module classes to customizable if queries are included.
Here are some links to documentation that helped me along the way:
  1. Module development - Introduction by Martin Hejtmanek  
  2. Module development - Packaging by Martin Hejtmanek 
  3. Creating Installation packages for modules
  4. Creating Module Installation Packages by Eric Dugre
For the most part, the links above got me 95% of the way there.  This blog post is really about the other 5% that I wasn’t able to grasp from the documentation, an explanation of some of the “gotchas” I ran into along the way and a quick reference guide for deploying custom modules.  Let me know in the comments if you have any questions, comments, or additional advice for deploying modules.
 
 

Share This Post:

Twitter Pinterest Facebook Google+
Click here to read more Kentico posts
Start a Project with Us

About the author

Dustin has gone from satellite communications technician to computer engineer to web developer. He has always been excited about the prospects of technology; all that can be explored and discovered with it fascinates him. When Dustin is not developing software you can find him studying philosophy and preparing for another sailing or skiing adventure with his wife, Molly.

View other posts by Dustin

Subscribe to Updates

Stay up to date on what BizStream is doing and keep in the loop on the latest with Kentico.