Upgrade procedure

Use the following procedure to upgrade your current version of Sitefinity CMS to any other higher version. We recommend that you always upgrade to the latest version. 
However, you may want to upgrade to any other version. For example, you may want to upgrade from Sitefinity CMS 5.2 to 6.1.

IMPORTANT: If you project uses NuGet packages, you must not upgrade it to Sitefinity CMS 8.1 using the Project Manager. In this case, upgrade you project to Sitefinity CMS 8.0 using the procedure below and then upgrade from 8.0 to 8.1 using procedure Upgrade a project that uses NuGet packages.

To upgrade your 4.x and above project, perform the following:

1. Update Sitefinity CMS assemblies and the references to them
   1. Update your assemblies, files, and folder structure.
      Open the newly downloaded Sitefinity CMS Project Manager, select the project that you want to upgrade and click Actions » Upgrade button.
      • The upgrade automatically updates the assemblies in your project's bin folder.
      • The upgrade automatically adds new files and folders to your project.
      • The upgrade automatically merges settings from the new version’s web.config file to your existing web.config file.
        Verify that all your web.config settings are in place by comparing the web.config file from your backup.
        

        IMPORTANT: You can use automatic web.config merge if your current project is Sitefinity CMS version 5.4 and above and you want to upgrade to Sitefinity CMS 6.3 and above.
        If your current project is Sitefinity CMS version 4.0 and above, you can still use automatic web.config merge, but you must get the Sitefinity CMS Internal hotfix build 7.1.5201 or any later version.
        For all other cases, Sitefinity CMS Project Manager automatically updates the assemblies and adds new files and folders, but you must manually merge the web.config changes.

   2. Update the references to the assemblies 
      Compare the contents of the following folders:
      • The bin folder of the _EmptyProject of your current Sitefinity CMS version.
      • The bin folder of the _EmptyProject of the Sitefinity CMS version that you want to upgrade to.
        
      • You need to compare differences in the .dll files only – which .dll files are removed and which are added to the bin folder of the version that you want to upgrade to. You can use any comparison tool, such as WinMerge.
      • Open your project in Visual studio, remove references to the removed .dll files and add references to the added .dll files.

        If your project is part of a larger solution where you have custom projects that reference Sitefinity CMS assemblies, check the references to those assemblies in your project and make sure that they are referencing the newer assemblies.

      • NOTE: The Sitefinity CMS Project Manager does not remove any .dll files - it only adds the new ones. Thus, if you have referenced the old .dll files anywhere in your solution, the upgrade will not break your customizations. If you want to remove the .dll files, you must do this this manually after making sure the .dll files are not used anywhere in your project.
        

      • NOTE: If you do not use Sitefinity CMS Project Manager application to upgrade your project, you must replace the assemblies manually, you must manually merge the web.config files, and add all the new files and folders from a new Empty Project. For each version, Sitefinity CMS Project Manager automatically creates the _EmptyProject folder once you create a new project. You can use DiffMerge or any other software that allows you to differentiate and merge the web.config changes, new files and folder structure.

2. Run the upgraded project and verify it
   1. Build your solution and restart your Sitefinity CMS website.

      IMPORTANT: You must not manually change the Sitefinity CMS version numbers stored in your configuration files. This is handled automatically by the upgrade process that starts with the first run of the website.

   2. Run the project and check it for errors.
      Check for errors the UpgradeTrace.log and Error.log files, located in the ~\App_Data\Sitefinity\Logs folder. If needed, contact the Sitefinity CMS support team with the attached UpgradeTrace.log and Error.log files and specify the versions that you upgrade from and to.
      

      NOTE: The first run of the upgraded website can be time-consuming, because Sitefinity CMS automatically performs incremental database upgrades from the database schemes used in the previous version to the one used in the new version. Information about the Sitefinity CMS version is stored both in the database and in the configuration files. At any time, the configuration files must match your database scheme.

      IMPORTANT: Sitefinity CMS 7.3 comes with granular permissions for dynamic content items. The upgrade of the permissions is done asynchronously - after you have upgraded and ran your website, the permissions upgrade starts. During this time, you may notice that Sitefinity CMS uses CPU resources. If the permissions upgrade is successful, you will see PASSED : Upgrading dynamic content permissions message in the UpgradeTrace.log file.

3. Deploy your upgraded project
   Depending on the type of upgrade you want to make, perform one of the following:
   • Replace your live website with the upgraded one.
     If you want to replace your production website and database with the locally upgraded files, package your upgraded website and its database and deploy them on your production environment. For more information, see Deployment.
   • Upload the upgraded project without the database.
     Restart the website. This triggers the upgrade process of your production database.
     For more information, see Upgrade projects in Continuous delivery.
     If your project is deployed on Windows Azure, see Upgrade projects running on Windows Azure.