Best practices: Upgrade

This articles provides a list with best practices for upgrading Sitefinity.

During the upgrade process, Sitefinity CMS Project Manager or NuGet replace the assembly files in your /bin folder with the ones corresponding to the newer Sitefinity CMS version. After assemblies are modified, Sitefinity’s upgrade scripts execute for the first time once you start your application. As a result, the upgrade scripts upgrade the database.

The best practices provide directions for simplifying and validation the upgrade process. We recommend that you perform the steps outlined in the Upgrading Sitefinity CMS - Best Practices whitepaper.

Below is a summary of some of the steps described in the whitepaper. For a full list of the recommended steps and detailed guidance, please refer to the linked whitepaper document above.

• Plan sufficient time for the upgrade. Your project size, level of customization, automation and so on might affect the needed time to upgrade. 
• Review the release notes of all major versions between your current version and the target version. 
  • If you are using any 3rd party libraries in your project code, check the release notes whether their version has not been updated in the target Sitefinity CMS version. If so, check the 3rd party library updated version for breaking changes.
• Review the API changes and Database changes between your current Sitefinity version and the version you are targeting for the upgrade. 
• Make backups of the project files and corresponding database(s).
• Restore locally a copy of your website project (and corresponding database(s)), that will be upgraded,  and change all connection strings and make them point to the local copy of the database(s). 
• Ensure the pre-upgraded project builds and runs successfully on the local machine.
• Empty the Sitefinity logs folder (~/App_Data/Sitefinity/Logs). You might need to stop the site from IIS/ Visual Studio/Sitefinity Project Manager, if the running worker process has locked some of the log files and prevents you from moving/deleting the old logs
• Use Sitefinity Project Manager or NuGet to replace the Sitefinity compiled logic. Replacing your current Sitefinity compiled logic with the new version means that your site will start using the new version when it runs.
• Modify the web.config following the Upgrade instructions in the Sitefinity documentation.
• After the Project Manager or NuGet finishes the upgrade procedure, it generates an UpgradeTrace.log file in your App_Data/Sitefinity/Logs folder.
  We recommend that you examine this file and make sure all processes are executed successfully. In some cases, some processes may fail due to various reasons. Failure may be a result of processes in the Project Manager and the machine running the upgrade procedure. If there are any processes with status FAILED, revert to backup and run the upgrade procedure once more. 
• Since the Project Manager upgrades only Sitefinity’s assemblies, all external projects and assemblies that use Sitefinity’s .dll files are not updated. Therefore, it is a good practice to adjust the references or add bindingRedirtects for any custom implementation that might be referencing a different version of Telerik assemblies than the one that you are upgrading to. We recommend to reference these assemblies from Sitefinity CMS project's bin folder. As a result, when you upgrade a Sitefinity CMS project through the Project Manager, the assemblies are automatically replaced with the new ones and all projects referencing their Telerik assemblies from the bin folder, will reference the new assemblies.
• If you have not customized your web.config file, you can safely replace it with the newer version, taken from the empty project. This newer file contains all new functionality. As of Sitefinity CMS 5.4, the Project Manager enables you to automatically update the web.config file when upgrading a project.