Kentico Xperience 13 documentation and ASP.NET Core

Most documentation about running Xperience applications under ASP.NET Core can be found in a dedicated section: Developing Xperience applications using ASP.NET Core. The rest of the documentation still applies, but some code samples and scenarios might need slight modifications for Core projects.

All major differences between the MVC 5 and Core platforms are summarized in Migrating to ASP.NET Core.

×

Hotfix Instructions - Xperience 13 Source Code

Hotfixes enable you to fix problems and apply updates to your Kentico Xperience instance. You can view the list of fixed bugs on the Kentico DevNet portal.

To obtain source code hotfixes, please use the Kentico Client Portal.

The instructions on this page apply only to the source code version of Xperience. For standard installations, please see Hotfix Instructions - Xperience 13.

Note

Always back up your project files and database before applying a hotfix.

Xperience 13 Refresh releases

Kentico Xperience 13 Refreshes are released in the form of hotfixes. Follow the standard hotfix instructions described on this page to apply Refreshes to your project.

ReleaseHotfixAdditional information
Refresh 113.0.16 or newer

Instructions and manual steps

Release notes

Table of Contents

Installing the hotfix

  1. Run the Hotfix_<version>_src.exe file.
  2. Go through the hotfix installation procedure.

By default, the installer places the hotfix into the C:\Program Files\Kentico\<version>\Hotfix<version> folder.

Applying the hotfix

To apply the hotfix to websites that use a local source code development instance, use the following general process:

  1. Hotfix the source code instance by running the Hotfix Utility. See: Hotfixing your source code project
  2. Update the Xperience code within your live site application to the matching hotfix version. See: Hotfixing the live site application
  3. Test that the hotfixed local website works correctly.
  4. Redeploy the project files to your production environment (using your preferred publishing process).
  5. Apply the hotfix SQL script to your production database. See: Hotfixing your production database

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 instance, then redeploy to Azure and run the hotfix SQL script against your production database.

Hotfixing your source code project

Note: For further information, see: Upgrading and hotfixing an instance

  1. Run Kentico Hotfix Utility (Hotfix.exe) from the location where you installed the hotfix (C:\Program Files\Kentico\<version>\Hotfix<version> folder by default).
  2. Select your project folder using the Browse button or type in the path to the project manually.
  3. Use the utility to back up your project files and/or database (or skip these steps if you already have backups).
  4. Select which components you want to update. Click Switch to advanced mode if you wish to change the settings.
    • Source files – all files in the source code, except for the administration web project in the CMS folder
    • Setup files – the Xperience installer and external utilities (which are separate from the web project)
    • SQL script – the database structure and data
    • Kentico Xperience files – the administration project files in the CMS folder

      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.

  5. Choose a method of taking the project offline and back online.
  6. Click Next to start the update procedure.
  7. 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.

  8. Open the solution in Visual Studio and Rebuild the solution.
  9. 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 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.

  1. Navigate to the location where you installed the hotfix (C:\Program Files\Kentico\<version>\Hotfix<version> folder by default).
  2. 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 a source code project to the given hotfix version.

  3. Copy the update files created by the Hotfix Utility into your Xperience project (overwrite the original files).

    • 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.

  4. 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).
  5. Open the solution in Visual Studio and perform the following steps:
    1. Click Show all files at the top of the Solution Explorer.
    2. Locate and select all newly added files.
    3. Right-click one of the selected new files and click Include in Project.
    4. Rebuild the solution.

Hotfixing the live site application

In addition to applying the hotfix to your Xperience source code project (see above), you also need to update the Xperience code used by your live site (MVC) application:

  1. Open your live site application in Visual Studio.
  2. Right-click your web project in the Solution Explorer and select Manage NuGet Packages.
  3. 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. Check for the presence of any error events with the HotfixProcedure Source.

After applying the hotfix

All users who work with the Xperience administration interface 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:

  1. When running the hotfix utility, click Switch to advanced mode in the Change confirmation step.
  2. Select the Setup files checkbox.
  3. Click Next.
  4. In the Running applications step, stop any applications that are currently running from the setup files.
  5. 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

13.0.5

  • (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 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.

      Important

      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.

13.0.10

  • 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:
    1. The system receives a path fragment. For example: /media/mediagallery/image.jpg
    2. 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
    3. 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
    {
    	"CMSUnixRootedPathPrefixes": "/etc/;/var/;/mnt/share/"
    }

    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.
  • Source code – To ensure that source code projects work and compile correctly after applying the refresh, you need to install the AngleSharp NuGet package into the Search project (right-click the project in the Solution Explorer and select Manage NuGet Packages). The package version must be 0.14.0 (or newer).
  • 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.
    • 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.

Fixed bugs

For a full list of bugs covered by the hotfix, open the Hotfixes page on DevNet and click Fixed bugs for the appropriate version.


Was this page helpful?