Supported, upgrade-safe customization of Kentico 8 solution

Bryan Drenner asked on July 15, 2014 23:29

I'm considering various customizations of the Kentico 8 solution. However I'm wary of complicating future upgrades, so I want to play within the bounds of Kentico's intentions. Which of the following customizations will be supported by future upgrades, and which will cause future upgrades to require lots of complex, manual labor?

  • renaming the solution file
  • adding new projects to the solution
  • creating new projects in folders outside (sibling to) the "Lib" and "CMS" folders
  • adding additional library assemblies to the "Lib" folder (and corresponding solution folder)
  • installing libraries via NuGet
  • moving or renaming the "Lib" or "CMS" folders
  • renaming the Kentico project (csproj) files
  • changing the Kentico projects' RootNamespace and AssembyName properties
  • reorganizing Kentico's projects in solution folders (virtual Solution Explorer folders in the SLN file)

Recent Answers

Brenden Kehren answered on July 16, 2014 19:56 (last edited on July 16, 2014 19:56)

I haven't had many issues with what you're talking about although I haven't changed the RootNameSpace and Assembly names or reorganized the projects in solution folders. What I've come across is the KIM having problems with recognizing <location> nodes in the web.config file. I think you'd come across any problems once you tried to perform a hotfix upgrade. If you have the ability to make the changes and test the KIM process, I think that will be your best answer and test. If I remember right the KIM looks at the solution file and web.config to get what it needs. So as long as your site registration in the KIM is correct, (knocking on wood) things should work.

0 votesVote for this answer Mark as a Correct answer

Bryan Drenner answered on July 16, 2014 21:01

Thank you, Brenden. I'll experiment with a hotfix to see how it handles various changes.

Here's more explanation, in case anyone has additional insight:

Our (The New 42nd Street's) solution contains projects that represent several related, deployable products, including the Kentico web app, a web service, and a couple other apps. The solution also contains projects for shared dependencies, such as a domain layer and helper libraries. In the Solution Explorer, it is arranged like this:

  • New42
    • Domain
    • Helpers
    • KenticoSite (a solution folder, and a directory in the file structure)
      • App (the deployable Kentico web application project)
      • Support (a project much like "AppCode")
    • AnotherKenticoWebApp (another solution folder / corresponding directory)
      • App
      • Support
    • SomeConsoleApp
    • SomeWebService
    • SomeOtherWebApp

Namespaces and assembly names intuitively follow the solution arrangement: New42.Domain, New42.KenticoSite.App, New42.SomeWebService, etc.

Past versions of Kentico had opinions about the single CMS web application project. Unlike past versions, Kentico 8 seems to have opinions about the broader solution. For example, Kentico 8 expects there to be three projects (CMSApp, CMSApp_AppCode, CMSApp_MVC) in a "CMS" directory, but at the root of the solution in the Solution Explorer. Now I worry that our preferred solution structure (directory hierarchy, solution folders, namespacing, etc.) will violate Kentico's expectations, such that automatic hotfixes and upgrades will fail.

The worst case scenario would be to have a solution for each Kentico web app and then one for everything else. I'd like to avoid that complexity if possible.

0 votesVote for this answer Mark as a Correct answer

Ales Kalina answered on July 22, 2014 15:50

Hi, Bryan, to make a long story short, it's safe to add new projects to the solution (regardless of their location) and reorganize solution folders. Besides, it's reasonably safe to add assemblies to the Lib folder and install NuGet packages. By reasonably safe I mean that under certain circumstances you might get into troubles due to assembly dependencies.

Let's suppose you want to add an assembly that references Newtonsoft.Json 6.0.1. As Kentico solution already references older version of Newtonsoft.Json, the application would fail to start because of unresolved reference to Newtonsoft.Json 6.0.1. You might replace the older version of Newtonsoft.Json in the Lib folder with a new one and add binding redirection to the configuration file, but the application might still fail to run because of incompatibilities between different versions of Newtonsoft.Json. It's quite dangerous because the application might run without problems for a long period of time. But as a user action invokes a specific piece of incompatible Kentico code, it will suddenly crash.

In a nutshell, it is safe to add libraries to the Lib folder as long as you avoid conflict with existing libraries. Other customizations you mentioned are not safe, because hotfix and upgrade utilities contain hardcoded names of many solution and project files. Their application might leave the solution in an inconsistent state and basically anything might then go wrong.

However, as you provided more information, it deserves further explanation. The Lib folder is essential as it contains all Kentico libraries and their dependencies. Kentico projects reference assemblies in this folder and its content is copied to the Bin folder in a post-build action. That's one reason why it is important to keep the folder structure intact.

Looking at the structure of your solution, I think you can achieve it even with Kentico 8. The KenticoSite\App and AnotherKenticoWebApp\App folders would correspond to the Kentico 8 installation folder (with CMS and Lib subfolders). You do not need to work with the Kentico solution file, just include CMSApp and CMSApp_AppCode projects in your master solution and organize them according to your needs. It's even possible to change the Root namespace and Assembly name of the Kentico projects, but you need to be aware of possible consequences. When you apply a hotfix, CMSApp.dll and CMSAppAppCode.dll files will be copied to the Bin folder. You must delete those files every time you apply a hotfix, otherwise you would be asking for trouble. Using this approach you can achieve both the required solution structure and ability to apply hotfix or upgrade.

0 votesVote for this answer Mark as a Correct answer

   Please, sign in to be able to submit a new answer.