Best practices for Upgrade

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

During the upgrade process, the NuGet packages 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. 
• Check whether the target Sitefinity version is compatible with the .NET version running on your machine, and install any new version if required.
  
• 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 or Visual Studio, if the running worker process has locked some of the log files and prevents you from moving/deleting the old logs
• Use the NuGet package 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 NuGet package 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 machine running the upgrade procedure. If there are any processes with status FAILED, revert to backup and run the upgrade procedure once more.