Hotfixes enable you to fix problems and apply updates to your installation of Kentico Xperience. You can download hotfix packages and view the list of fixed bugs on the Kentico DevNet portal.
If you have the source code version of Xperience, please see Hotfix Instructions - Xperience 13 Source Code.
Always back up your project files and database before applying a hotfix.
Xperience 13 Refresh releases
Kentico Xperience 13 Refreshes are product updates released in the form of hotfixes. Follow the standard hotfix instructions described on this page to apply Refreshes to your project.
|Refresh 1||13.0.16 or newer|
|Refresh 2||13.0.31 or newer|
|Refresh 3||13.0.43 or newer||Release notes|
|Refresh 4||13.0.52 or newer||Release notes|
Table of Contents
Installing the hotfix
- Download the installer for the required hotfix version from the Kentico DevNet portal.
- Run the Hotfix_<version>.exe file.
- Go through the hotfix installation procedure.
By default, the installer places the hotfix into the C:\Program Files\Kentico\<version>\Hotfix<version> folder.
You can only apply the hotfix to complete Xperience administration projects that use the standard folder structure (the solution file, GlobalAssemblyInfo.cs, the CMS and Lib sub-folders). For example, the hotfix cannot be applied to administration deployments of the CMS folder.
Applying the hotfix
Use the following general process to apply the hotfix (we do not recommend attempting to directly hotfix your live production site):
- Set up a local instance of your site (including the web project files and database).
- You can either maintain a permanent local development instance, or get backups of your production site's web projects and database for each hotfix.
- Hotfix the local administration instance by running the Hotfix Utility. See: Hotfixing your local project
- Update the Xperience code within your live site application to the matching hotfix version. See: Hotfixing the live site application
- Test that the hotfixed local website works correctly.
- Redeploy the project files to your production environment (using your preferred publishing process).
- Apply the hotfix SQL script to your production database. See Hotfixing your production database
- To display all features in the Xperience administration correctly, clear the cache in your browser (and ensure the same for all other administration users).
Hotfixing Microsoft Azure applications
If your website is hosted on Microsoft Azure, the recommended hotfix process is the same as outlined above. First apply the hotfix to a local development instance, then redeploy to Azure and run the hotfix SQL script against your production database.
Hotfixing your local project
Note: For further information, see: Upgrading and hotfixing an instance
- Run Kentico Hotfix Utility (Hotfix.exe) from the location where you installed the hotfix (C:\Program Files\Kentico\<version>\Hotfix<version> folder by default).
- Select your administration project folder using the Browse button or type in the path to the project manually.
- Use the utility to back up your project files and/or database (or skip these steps if you already have backups).
- Select which components you want to update. Click Switch to advanced mode if you wish to change the settings.
- Kentico Xperience files – the files of your administration project
- Setup files – the Xperience Installer and other external utilities (which are separate from the web project)
SQL script – the database structure and data
We recommend updating all components. To successfully complete the hotfix, you need to update the files of your web project and apply the SQL script to the database.
- Choose a method of taking the project offline and back online.
- Click Next to start the hotfix procedure.
After the update finishes, click Next to view any problems that may have occurred and the instructions to solve them.
Errors that can commonly occur are conflicts with customized files. By default, the hotfix does not overwrite modified files (unless you enable the Overwrite all files option in advanced mode):
For each conflict with a customized file, the process creates the new version of the file with the .new extension. You need to manually transfer your customizations to the new files and then replace the original ones.
Customized files that would have otherwise been deleted remain in the file system, with an added .deleted extension.
- Open the Xperience solution in Visual Studio and Rebuild the solution.
Access the URL of your Xperience administration application in a browser (opening the live site is not sufficient).
- When handling the first request, the system performs certain tasks required to complete the hotfix. Processing of the first request may take longer than usual.
Preparing the hotfixed project files manually
If you do not wish to go through the user interface of the Hotfix Utility, you can create the hotfixed web project files manually using the command line. For example, this can be useful if you wish to integrate the hotfix into a more complex scripted procedure.
- Navigate to the location where you installed the hotfix (C:\Program Files\Kentico\<version>\Hotfix<version> folder by default).
- Run Hotfix.exe from the command line with the /deploy and /path parameters:
- Use the /path parameter to specify the location where the utility creates the update files. Use a relative path (folder in the location where the utility was executed) or absolute path (any location on a local disk).
Example: Hotfix.exe /deploy /path=Deploy
Creates a folder named Deploy in the directory from which the utility was executed, and copies all files and folders necessary for updating to the given hotfix version.
Copy the update files created by the Hotfix Utility into your Xperience web project's root folder (including the CMS and Lib folders, and GlobalAssemblyInfo.cs file). Overwrite the original files.
- Do NOT copy and overwrite the CMS\CMSApp.csproj file.
If you have previously modified some of the project files, do NOT overwrite these files. You need to compare the modified files with the new versions and make appropriate changes manually.
- Open DeletedFiles.xml in the update file directory and delete all of the listed files from your web project (you can prepare a batch file to automate the process).
- Open the Xperience solution in Visual Studio.
- Click Show all files at the top of the Solution Explorer.
- Locate and select all newly added files under the CMSApp project.
- Tip: Identify the new files by using a differencing or merging tool to compare your CMSApp.csproj file with the one from the update files.
- Right-click one of the selected new files and click Include in Project.
- Rebuild the solution.
Hotfixing the live site application
In addition to applying the hotfix to the Xperience administration application (see above), you also need to update the Xperience code used by your live site (MVC) application:
- Open your live site application in Visual Studio.
- Right-click your web project in the Solution Explorer and select Manage NuGet Packages.
- Update the Kentico.Xperience.AspNet.Mvc5 or Kentico.Xperience.AspNetCore.WebApp NuGet package to the version that matches the applied hotfix.
Hotfixing your production database
Update your production database as the last step in the hotfix process, after you test the hotfix locally. This ensures minimum downtime for your live site while avoiding loss of data.
The hotfix version of the database must match the version of the web project, so you need to perform the update together with the redeployment of the hotfixed project files.
Note: On websites that contain a very large amount of data (particularly pages), the database hotfix process can be very resource intensive. You may need to temporarily scale up the performance of your database server and/or increase the database connection timeout.
To update your production database, manually execute the hotfix database scripts (for example using SQL Management Studio). The script files are located in the SQL folder of your hotfix installation directory.
- If you do not use separated databases – run Hotfix_separated.sql first and then Hotfix_default.sql.
- If you use separated databases – run Hotfix_separated.sql on the separated database and Hotfix_default.sql on your main database.
- Note: The script files may be empty if the given hotfix does not require any SQL scripts for the related tables (skip the file in these cases).
Once the database update is complete, you need to access the URL of your Xperience administration application in a browser (opening the live site is not sufficient). When handling the first request, the system performs certain tasks required to complete the hotfix. Processing of the first request may take longer than usual.
After your administration application loads up, open the Event log application to validate that the hotfix procedure was completed successfully. Make sure the log contains Start and Finish events for the hotfix application, and check for any error events with the HotfixProcedure Source.
After applying the hotfix
All users who work with the Xperience administration should clear the cache in their browsers after applying the hotfix. Otherwise, some features in the administration interface may not be displayed correctly.
After applying the hotfix to a development instance that has continuous integration enabled, you need to run complete serialization for all objects to recreate the content of the CIRepository folder (use the Continuous integration application in the Xperience administration interface). Apply the hotfix separately for each instance in your development environment. After one developer commits the hotfixed changes to the source control, other developers CANNOT commit or load changes until they apply the hotfix to their own instance.
Updating setup files and external utilities
Hotfixes provide bug fixes for all files related to the Xperience installation, which includes the installer and other external utilities, such as Kentico Installation Manager and Kentico Service Manager.
To update these files and utilities, you need to apply the hotfix to the setup files:
- When running the hotfix utility, click Switch to advanced mode in the Change confirmation step.
- Select the Setup files checkbox.
- Click Next.
- In the Running applications step, stop any applications that are currently running from the setup files.
- Click Next and continue through the rest of the hotfix procedure.
The hotfix makes any required changes to the files in the directory where you installed your Xperience setup files.
Additional notes and workarounds
- (Added feature) Media libraries – The hotfix allows media libraries to use the direct file path in URLs when adding links to files in Xperience content (instead of permanent media file URLs). For example, direct file URLs may be desired for media files placed in external storage (such as Microsoft Azure Blob storage). The option can be configured when editing individual media libraries on the General tab. The URL format applies in the following scenarios:
- Adding media files using the Rich text widget in page builder content
- Adding media files using the editor for page fields based on the Rich text editor form control
Selecting media files in page fields based on the Media selection form control
Note: Files accessed through a direct path are not handled by the Xperience system – no permission or security restrictions are enforced and image resizing is not applied. Additionally, direct file links may become broken in certain deployment scenarios if your instances each use a different location or container for media files.
After applying hotfix 13.0.5, you may encounter an error when creating new media libraries.
To fix the problem, either apply hotfix 13.0.9 or newer, or alternatively re-sign macros using the System application in Macros -> Signatures.
- Filesystem handling for ASP.NET Core applications on Linux – The hotfix addresses a number of filesystem-related issues encountered when hosting ASP.NET Core live site applications in Linux environments. The issues were primarily caused by a dependency on Windows-like filesystem conventions, so mostly impacted features reliant on Input/Output operations. The following is a non-exhaustive list of affected features: media library operations (insert, modify, delete), smart search (running indexing tasks, index rebuilds), web farm synchronization, scheduler functionality run on the live site.
The hotfix additionally introduces a new approach for detecting absolute and relative paths on Unix-like filesystems. This applies only to ASP.NET Core applications hosted on Linux. Since both relative and absolute paths on Unix-like filesystems begin with a forward slash ('/'), Xperience cannot determine whether a path segment is absolute or relative. For example, this is important when determining the location of media library content, or in general whenever it is necessary to prepend relative path fragments with the physical path to the web application.
By default, the system uses the following process to detect the path type:
- The system receives a path fragment. For example: /media/mediagallery/image.jpg
- If the path is prefixed with the physical path to the web application (stored in the SystemContext.WebApplicationPhysicalPath property), the path is treated as absolute. If not, the system checks whether the first two folders in the path exist on the filesystem starting from the root (taking the first two folders produced the least false positives during extensive testing). For the example above, the system tests for the existence of: /media/mediagallery
- If the first two folders in the path do not exist, the path is treated as relative. If the first two folders exist, the path is treated as absolute.
You can override this behavior by adding the CMSUnixRootedPathPrefixes configuration key to the Core application. Adding the key disables the process described above. Instead, the key needs to contain a semicolon-delimited list of all path prefixes (e.g., /etc/, /var/, /mnt/share/) the system should treat as absolute. The list must be case-sensitive.appsettings.json
Only use the CMSUnixRootedPathPrefixes configuration key if your project contains non-standard filesystem mapping (e.g., for media library files), or if you encounter issues with the built-in path type detection mechanism. The default functionality covers all expected cases and filesystem configurations.
- Rich text editor – The hotfix updates the Rich text editor component for the page builder to use version 3.2.6 of the Froala WYSIWYG editor. The update resolves an issue where adding a new line caused the page to scroll down to the bottom of the rich text editor content (when the content was very long).
- Search – The Search fields tab in the page type editing interface was only available for page types that had the URL feature enabled. After applying the hotfix, the search configuration is displayed for all page types that have either custom fields or the URL feature. The change allows searching for page items that hold content, but do not need their own URL.
13.0.16 (Xperience 13 Refresh 1)
- For detailed information about the new features and changes in Xperience 13 Refresh 1, refer to the Release notes.
- Search – Applying the Refresh automatically converts all existing page search indexes to a new type that combines the original Pages crawler and Pages indexes. The data source for indexing (page HTML output and/or structured fields) can instead be configured separately for individual page types. See Defining local page indexes to learn more.
- You need to manually Rebuild all page indexes.
- We recommend validating the search configuration of your page types. Select an appropriate Data source for indexing and configure the new Index update trigger flag for individual fields to meet your exact search requirements (by default, the system automatically sets the Index update trigger flag to keep the same behavior of page indexes as before the Refresh).
- If you have customized the search settings for page fields via the SKU or Page class, you need to manually set the new Index update trigger flag for the fields of this class.
- A/B testing – Pages with a running A/B test displayed variants inconsistently to visitors who had not given consent to be tracked as contacts (did not accept cookies of the Visitor or All level). When visitors who are not tracked as contacts view an A/B tested page after applying the hotfix, the system assigns a page variant and stores it into the new CMSVarAB<A/B test name> cookie. This cookie is only used to keep content consistent and does not enable any tracking or logging of conversions.
13.0.31 (Xperience 13 Refresh 2)
- For detailed information about the new features and changes in Xperience 13 Refresh 2, refer to the Release notes.
Web farms – In hosting environments that dynamically adjust the number of instances (e.g., autoscaling in Azure App Services), deactivated web farm servers always remained in the system with the Not responding status for 24 hours. See Troubleshooting web farms. This could cause performance problems and heavy database load due to large numbers of unnecessary synchronization tasks generated after scaling down the number of servers. The hotfix adds the option to adjust the interval for which web farm servers stay in the Not responding status before being deleted. To change the default interval of 24 hours, set the new CMSWebFarmNotRespondingInterval configuration key to the required number of minutes, e.g., 60 for 1 hour.appsettings.json
<add key="CMSWebFarmNotRespondingInterval" value="60" />
- API – Dependency injection was not supported when developing page templates filters and form component filters. After applying the hotfix, the constructor of filter classes implementing IPageTemplateFilter or IFormComponentFilter can have parameters (e.g., instances of services registered in the project's DI container). When registering such filters into the corresponding filter collection, you must use the Add<FilterClassType> method, with the filter class as the generic type parameter.
- Unix/Linux – It was not possible to run Xperience-specific isolated integration tests (derived from the IsolatedIntegrationTests class) in Linux environments due to database connection issues. The hotfix introduces a new CMSTestIsolatedAltConnectionString configuration key that allows test projects to connect to databases running in Linux environments. See Creating isolated integration tests for details.
13.0.43 (Xperience 13 Refresh 3)
- For detailed information about the new features and changes in Xperience 13 Refresh 3, refer to the Release notes.
- Search – On sites running behind a proxy server or another service that masks the application's original domain (e.g., Azure Application Gateway), the smart search crawler used for page types with a HTML output search data source did not work correctly. JWT token validation failed, which resulted in logged errors and only content available for public users was indexed. The hotfix fixes the issue for ASP.NET Framework (MVC 5) sites. For ASP.NET Core sites, you instead need to set up Forwarded Headers Middleware for the project.
- Azure Search – It was not possible to change the domain name suffix of requests generated by the system for Azure search services (e.g., myazuresearchservice.search.windows.net). By default, the system assumes your Azure Search services are hosted on the search.windows.net domain (true for the majority of commercial subscriptions). Search requests for Azure indexes are generated using this suffix and the provided search service name.
However, certain Azure subscriptions or licenses host search services under a different domain. For example, Azure Government subscriptions use the search.azure.us domain. The hotfix introduces the new CMSAzureSearchDnsSuffix configuration key, which allows you to change the suffix used by the system when generating Azure search requests.appsettings.json
<!-- Configures the system to generate requests in format: myazureservice.search.azure.us --> <add key="CMSAzureSearchDnsSuffix" value="search.azure.us" />
13.0.52 (Xperience 13 Refresh 4)
- For detailed information about the new features and changes in Xperience 13 Refresh 4, refer to the Release notes.
For a full list of bugs covered by the hotfix, open the Hotfixes page on DevNet and click Fixed bugs for the appropriate version.