Upgrading Kentico manually

✖
Copy to clipboard

Note: We strongly recommend using the automatic upgrade described in Upgrading Kentico 7 to 8.

If you cannot directly access the environment hosting your Kentico instance, you can perform the upgrade from version 7.0 to 8.0 manually.

Before you start the manual upgrade, install the upgrade and go through the required Steps before the upgrade.

Step 1 - Backup

Back up your Kentico web project files and database. We recommend that you:

  1. Make a copy of the Kentico project.
  2. Upgrade the project locally.
  3. Deploy the project to the production environment once the upgrade is complete.

Important: If you do not create a backup, your project may get corrupted without a way to reverse the changes.

Step 2 - Site shutdown

Your site must be offline during the upgrade process. Copy App_offline.htm (available in the upgrade installation folder) into the root of your web project or use another approach to shut down your site.

Step 3 - Database upgrade

  1. Launch Microsoft SQL Server Management Studio.
  2. Connect to the Kentico database that you wish to upgrade.
  3. Open the upgrade_8_0.sql script from the SQL directory in the upgrade installation folder.
  4. Run the script against your Kentico database.

If you encounter any errors, please send them to Kentico support (include the error log in the message).

Important

Kentico uses database objects with the dbo schema. If your database uses a different or no schema, you need to modify the schema occurrences in the script accordingly.

Please check whether the upgrade script is running against the correct database. Many upgrade problems are caused by launching the SQL script on a non-Kentico database.

Step 4 - Creating the upgrade file structure

Launch the Kentico Upgrade Utility from the command line with the /deploy parameter. Set the parameter’s value according to the .NET version and project that to which you wish to upgrade:

  • net40site - web site using .NET version 4.0
  • net40app - web application using .NET version 4.0
  • net45site - web site using .NET version 4.5
  • net45app - web application using .NET version 4.5

If your Kentico 7 project uses .NET 3.5, enter one of the .NET 4.0 values.

You can also add the optional /path parameter, which sets the target location for the upgrade file structure. This way you won’t have to provide the path in the first step of the update process.

The /path parameter value can be supplied in two different formats – relative, which represents a folder in the location from which the utility is executed; or absolute, which can be any path to a local disk.

Example: Upgrade.exe /deploy=net40site /path=Deploy
Launches the upgrade utility, which creates a folder named Deploy in the upgrade installation directory, and copies all files and folders necessary for upgrading to a .NET 4.0 web site project.

If you have removed some of the default modules from your Kentico 7 installation, you can use the following process to remove the given modules from the upgrade files:

  1. Open the CMS folder in the upgrade files.
  2. Rename web.config.integrated to web.config.
  3. Download the Kentico 8 Installer.
  4. Run Kentico_8_0.exe.
  5. Read and accept the License Terms and Conditions and click Custom installation.
  6. Select Install only program files and click Install.
  7. Navigate to the Kentico setup files (C:\Program Files\Kentico\8.0 by default).
  8. Run Bin\KenticoInstaller.exe.
  9. Click Modify.
  10. Click Select another and choose the folder containing the upgrade files.
  11. Remove the required modules and click Apply Changes.

In the CMS folder of the upgrade files, add the original extension back to the name of the web.config file (web.config.integrated).

Step 5 - Project file upgrade

  1. Copy all customized and custom files from your Kentico 7 project to a backup directory.
  2. Create a folder named CMS inside the web project.
  3. Move all folders and files inside the web project into the CMS sub-folder.
  4. Open upgrade.xml in the upgrade installation directory and delete all of the listed files from your web project (you can prepare a batch file to automate the process).
  5. Copy the content of the upgrade file folder (created in step 4) into the root of your web project folder. Overwrite all files.

If you have customized any of the default files or have added custom files to the project, you need to compare your backup project with the upgraded project, and manually transfer the customizations. Because of changes in the Kentico 8 project structure and administration interface, your customizations may not work correctly without signification updates.

If your solution contained custom projects, open the new Kentico solution in Visual Studio and add the projects. You also need to manually update the required reference for both the custom and Kentico projects.

If your project is a web application, rebuild the Kentico solution in Visual Studio. You may need to go through the Steps after the upgrade to successfully rebuild the solution.

Step 6 - Web.config upgrade

The upgrade files contain two versions of the web.config, one for each application pool managed pipeline mode. You can tell them apart by their extension (.classic and .integrated). Choose the one that matches the application pool that your application uses.

Copy the connection string and replace the old web.config with the new one.

If your web.config contains any custom configuration, you need to manually transfer the changes to the new web.config.

Step 7 - Updating IIS

  1. Run Internet Information Services (IIS) Manager.
  2. Select your Kentico IIS application.
  3. Click Basic Settings and remap the Physical path to the CMS subfolder.
  4. If your application originally used .NET 3.5, edit your Application Pool and update the .NET Framework version to v4.0.30319.

Step 8 - Finishing and starting the site

To bring your site back on-line, remove or rename the App_Offline.htm file from the CMS folder after finishing the upgrade procedure.

Continue with the Steps after the upgrade.