In the nearly 5 years I have worked at Bizstream, I have upgraded many Kentico sites. During my earlier years, Kentico Web Apps were starting to take off, but Kentico Web Sites were still pretty common and widely used. At that time there was no need to convert a Kentico Web Site to a Web App. Now though, Kentico Web Sites are so archaic that upgrades feel incomplete unless converted into a Web App.
Kentico Web Site? Web App? What is the difference?
When it comes to Kentico, the primary difference between a Web Site and a Web App is that Web Apps are precompiled into one or more Dynamic-link libraries (DLLs), while Web Sites use Just In Time compilation (JIT), meaning code gets compiled at run time. Kentico Web Apps are overall faster to load since they are already compiled. Kentico Web Apps also do not need as many files to deploy since all .cs files are compiled into the DLLs. Kentico Web Sites, by contrast, need every file deployed.
For more information on JIT see visit Just-in-time Compilation
Note: When a C# code file is changed on a Kentico Web App, it is no longer enough to only deploy the modified C# code file. In order for the change to take effect, the DLL has to be recompiled and deployed.
Converting a Kentico Web Site to a Kentico Web App
There is more than one way to convert a Kentico Web Site to a Web App. The best way I found to do this I will outline below.
- Spin up a new website of the same Kentico Version, Hotfix, and .net Framework version. A.This step is to have an unmodified version of Kentico to a basis of which to compare the web site in which you are converting and find which code files are custom and which built-in Kentico files have been modified. B. If you do not already have Kentico installed on your computer, you can download it from the Kentico Client Portal. C. Hotfixes can be found here.
- Spin up a new Web App of the same Kentico Version, Hotfix, and .net Framework version.
This here will become the new core of the concerted Kentico site.
- Compare the code files of the Kentico site that is to be converted with the freshly spun up Kentico website made in Step 1. A tool like Winmerge would be really helpful for this part.
- Log which standard Kentico files have customaizations, and which standard Kentico directories have custom files. Keep track of these so you can later merge customizations into the Web App code, and add the custom files into the build.
- Make a backup of those logged files in a separate directory.
- Make a backup of the bin and Lib directory. Reason being that sometimes there are external assemblies on specific sites that are not part of a standard Kentico installation. Having a backup will help know what was missing in the case of errors related to missing assemblies.
- Make a backup of any custom directory that contains custom code. Meaning any directory that is not part of a standard Kentico installation and contains Custom Code. This will later be added back into the Kentico Web App.
- If applicable, make a backup of CMSVirtualFiles directory. Alternatively, you can store all virtual objects in the database. For more information see Kentico's documentation on editing object code externally and Kentico's documentation on deployment mode for virtual objects
- Delete the following files in the root directory A. GlobalAssemblyInfo.cs B. (SolutionName).sln
- In the CMS directory, delete all directories and files that are part of a standard Kentico installation. Including template directories such as DancingGoat, but do not delete the following A. Web.config B. FavIcon C. (Your Site’s Media Directories).
- From the newly spun up Kentico Web App, copy over the Web App version of the files and directories that were deleted in step 10. Copy everything from the Web App CMS Directory except the listed exclusions from step 10.
- Copy over the WebApp.sln file and GlobalAssemblyInfo.cs from the web app’s root directory into the converted site’s.
- Merge the customizations that were made in the standard Kentico files into the Web App.
- Add back the custom files that were in standard Kentico directories.
- Move all custom files and directories that were originally in App_Code to Old_App_Code. Web Apps don’t have an App_Code directory so custom code that was previously in App_Code now belongs in Old_App_Code.
- Add back the CMSVirtualFiles directory. If applicable, copy that directory from the backup made earlier.
- Open the solution in Visual Studio.
- Include all custom files in the build. When the solution is first loaded, only the files that were part of the original Kentico Web App installation will be part of the build. All custom files need to be added into the build.
- Convert CMSApp to Web Application. Select CMSApp in the Solution Explorer Window. Click the Project menu and choose “Convert to Web Application”. This adds all the necessary .designer files and changes “CodeFile” to “CodeBehind” in the layout files. Depending on the version of Kentico there might also be other projects to build as well such as CMSApp_App
- Build the App. Check for build errors. Various things can cause errors with this such as missing Assemblies, References, Nuget Packages, and possibly errors in code files that were not apparent in a web site. Since Kentico web sites were compiled in real-time, the site would only have errors when the problem code was being used. If there was code that was rarely or never used, it is possible some errors went unnoticed before. Build errors need to be resolved for a web app to work.
- Change references of CodeFile to CodeBehind in Web Part Layouts. While Visual Studio’s “Convert to Web Application” feature handles physical layout files, it does not handle the Web Part Layouts within Kentico. That will need to be done manually within Kentico. To edit Web Part Layouts, go to the Kentico Admin Interface -> Web Parts. Select the web part that has a custom layout and click the “Layouts” tab and edit that accordingly. Visit Kentico's documentation on using custom web part layouts for more information.
- Run site in browser and spot check. After a successful build, run the site in a browser and check parts of the site that made use of custom code. If everything was done right, there should be no problems, but it is always possible that something is missing still like a code file that didn’t make it in the build or a stylesheet. Check the browser’s console for errors that were not present before the app conversion.
I hope you found this guide to be helpful. While this process has worked with conversions we have performed, different websites have different needs so results may vary. This should be a good starting point though and don’t forget to test extensively.