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

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.

Note

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

Table of Contents

Installing the hotfix

  1. Download the installer for the required hotfix version from the Kentico DevNet portal.
  2. Run the Hotfix_<version>.exe file.
  3. Go through the hotfix installation procedure.

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

Prerequisites

You can only apply the hotfix to complete Xperience 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):

  1. 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.
  2. Hotfix the local instance by running the Hotfix Utility. See: Hotfixing your local project
  3. Update the Xperience code within your live site application to the matching hotfix version. See: Hotfixing the live site application
  4. Test that the hotfixed local website works correctly.
  5. Redeploy the project files to your production environment (using your preferred publishing process).
  6. 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 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

  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.
    • Kentico Xperience files – the files of your web 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.

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

  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 to the given hotfix version.

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

  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 Xperience solution in Visual Studio.
  6. Click Show all files at the top of the Solution Explorer.
  7. 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.
  8. Right-click one of the selected new files and click Include in Project.
  9. 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:

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

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

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

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?