Introduction
In this blog post, I cover some hidden magic of Kentico Xperience, specifically an internal method that silently operates in the background whenever a hotfix is implemented. While developers may not directly witness this process, it executes significant changes that can have a profound impact on the functionality of Kentico Xperience. Understanding and correctly executing this hotfix procedure is crucial to avoid potential problems that could arise within the system.
In this post, I will explore the detailed workings of Kentico Xperience's hotfix methodology. By the end of this article, you will have a thorough grasp of the inner workings of Kentico Xperience's hotfix methodology, allowing you to confidently apply hotfixes with ease and avoid any potential errors, ensuring a smooth and trouble-free experience.
Understanding the Hotfix Procedure
The Kentico Xperience hotfix procedure involves several steps to ensure a successful implementation. First, you need to download and install the Kentico hotfix utility, which serves as a tool to facilitate the process. Once installed, you can launch the utility and follow the provided wizard, which guides you through the necessary steps. This includes executing the required database SQL scripts and updating the Kentico Xperience files, particularly the CMS files. Afterward, you need to open the live site application (MVC) in Visual Studio, where you will update the NuGet packages to the target hotfix version. To complete the procedure, you rebuild the solution and start the application to apply the hotfix effectively. By following these steps, you can ensure a smooth and error-free experience during the Kentico Xperience hotfix process.
Potential Challenges and Solutions during the Hotfix Procedure
During the execution of the hotfix procedure in Kentico Xperience, various issues can arise that are immediately visible and require attention before proceeding to the next step. For instance, when executing the SQL script, it is possible for it to fail and provide instant feedback about the error encountered. Such errors need to be addressed and resolved before proceeding further.
Similarly, when updating the NuGet packages and building the solution, compilation errors can occur, necessitating their resolution. Another potential area where errors can occur is when updating the administration interface through the hotfix wizard. In some cases, certain files may require manual comparison and updating, especially if they have been intentionally modified.
Each of these steps collectively forms the foundation of the hotfix procedure, and it is crucial to perform them correctly. Once these steps are completed accurately, the next phase involves launching the CMS and the live site (MVC) application.
Testing and Validating the Hotfix
To ensure a smooth production rollout, it is advisable to execute the SQL script on multiple database copies, preferably with representative data. This allows for thorough testing and helps identify any potential issues that may arise from variations in data between different environments. By closely mimicking the production environment, we can proactively address discrepancies and prevent complications during the hotfix deployment process.
The Hidden Operations of Kentico Xperience Hotfixes
Upon launching the hotfixed application, it is important to note that background tasks might still be in progress. Although not immediately visible during the loading process, these tasks can be traced in the event log, indicating the execution of additional operations specific to a particular hotfix version.
A deeper analysis of the source code reveals the background execution to update class form definitions. These updates involve modifying or expanding table structures with new database fields. An example is the introduction of the DocumentUnpublishedRedirectUrl field, which was added in refresh 8, also known as hotfix version 13.0.94. These updates are performed through the internal Kentico Xperience API, ensuring consistent synchronization of the database across all relevant locations.
Exploring the Importance of Class Form Definitions Updates
The process of updating class form definitions in Kentico Xperience involves an additional level of complexity. It relies on a temporary table named [Temp_FormDefinition], which is populated with corresponding changes by the hotfix SQL script (see screenshot below). This step is particularly relevant for refreshes that introduce new functionalities to Kentico Xperience.
The [Temp_FormDefinition] table contains an XML value that stores the class form definition. When Kentico Xperience detects the execution of a hotfix, it reads and processes this temporary table in the background. At the end of the process, the table is cleaned up and removed. Simultaneously, a Kentico Xperience setting is updated to store the hotfix version.
Kentico Xperience utilizes two settings for this purpose: CMSHotfixVersion and CMSHotfixDataVersion. When the Kentico Xperience application starts, it compares the values of these settings. If they differ, the method responsible for reading the temporary table and processing the class form definitions is triggered. This ensures that any necessary updates are applied seamlessly during the startup process.
Pitfalls of the Temporary Table in Kentico Xperience
It is crucial to highlight the potential pitfalls that can occur if the temporary table, [Temp_FormDefinition], is empty but has not been fully processed. Incorrect execution can result in error messages, as previously illustrated by the example of the new DocumentUnpublishedRedirectUrl field. For instance:
Caused exception:
Invalid column name 'DocumentUnpublishedRedirectUrl'.
, StackTrace: at CMS.DataEngine.AbstractDataConnection.HandleError(String queryText, Exception ex)
In a recent project, we encountered this exact issue. We had automated the hotfix rollout process, which included the automatic execution of the SQL script. However, for unknown reasons, the temporary table was either not updated or not updated completely. Despite the absence of any hotfix-related notifications in the event log, we found that the two settings, CMSHotfixVersion and CMSHotfixDataVersion, were still identical. As a result, we observed abnormal behavior and encountered error messages due to the failure to update the source table structures.
This showed us once again the crucial importance of maintaining the correct sequence and order of operations during the hotfix procedure to avoid such issues.
Conclusion
In conclusion, this blog post has shed light on the under the hood background tasks that are crucial for a successful hotfix procedure in Kentico Xperience. While the more visible tasks are important, it is equally vital to recognize and ensure correct execution of these background tasks. Neglecting them can lead to unexpected issues and complications within the applications.
Hope this helps. Happy developing!
Top comments (0)