UPGRADING UMBRACO
The Umbraco Installation Wizard can manage patch upgrades (e.g., 4.5.1 to 4.5.2) and single major version upgrades (e.g., 4.0 to 4.5) gracefully and is the recommended approach for upgrading an installation. With all upgrades, knowing whether your installation contains any modified source or files from the original distribution is important. If so, take care to make backup copies of these files. In addition, if your installation contains a customized web.config file, or other configuration file, creating a backup of your configuration files for later use is essential.
Performing a Patch Upgrade
Typically, a patch upgrade contains no new functionality and requires no changes to configuration files. Reading the notes associated with a new Umbraco release prior to installing or upgrading an installation is good practice because any changes to configuration files will be documented in the notes.
The process to complete a patch upgrade is generally as follows:
- Extract the patch release from the archive.
- Copy new or altered files to your installation.
- Run the Umbraco Upgrade Wizard (see Figure 1-21).
You can always find the latest release of Umbraco at the Umbraco home on CodePlex at http://umbraco.codeplex.com/releases.
Unless specified in the release notes, you will only copy the following directories to your installation:
After the files are copied, open a browser and navigate to your Umbraco instance. The Umbraco Upgrade Wizard launches and guides you through the process to complete the site upgrade.
In addition, you must remove any cache files located in the /app_data/TEMP/ folder, such as those generated by the client dependency loader, the Examine Search indexer, and the Umbraco document cache.
Unless explicitly stated in the release notes, a patch release doesn't include database changes. In this case, the upgrade wizard simply updates the current version number in web.config. Instead of running the wizard, you can simply change this version number before copying the files to prevent the wizard from running. To do so, simply change the value of the <umbracoConfigurationStatus> key under <appSettings> in web.config to the current version number. For instance:
<add key=“umbracoConfigurationStatus” value=“4.5.2” />
Verify permissions! If you skip the Upgrade Wizard, make sure to verify that you have correct file permissions for directories because the file copy process can reset them. See step 3 of the “Installing Umbraco Manually” for reference.
Performing a Version Upgrade
When upgrading between single major versions, identifying all third-party components and Umbraco version-specific features is important. Breaking changes are noted in the major version's release notes and in Umbraco-provided installation and upgrade guides. Aside from verifying that third -party components are compatible with the version to which you are upgrading, creating a backup of all modified files, dependent assemblies, ASP.NET user controls, and all configuration files is essential.
The process to complete a version upgrade is generally:
- Gather information about changes to configuration files.
- Identify third-party components and related files.
- Extract the version release from the archive.
- Copy new or altered files to your installation.
- Apply changes to configuration files.
- Run the Umbraco Upgrade Wizard.
After the files are copied and the configuration files are updated, open a browser and navigate to your Umbraco instance. The Umbraco Upgrade Wizard launches and guides you through the process to complete the site upgrade.
Updating your installation's configuration files to properly contain both a new version's required settings and your specific settings is tricky at best. Most users have the most success by using a file difference and merge tool to create new configuration files based on the new file and adding the settings from the older version where no conflict exists.
Some settings will need to be determined based on your specific requirements and the specific version being used for the upgrade—for example, XML schema changes from version 4.0 to version 4.5 and Umbraco user password format—set in web.config—from version 4.5.0 to version 4.5.1.