Wednesday, April 22, 2015

Troubleshooting Sitefinity Upgrades

If you have ever tried to upgrade from one release of Sitefinity to any later release, you probably already know that very few upgrades are seamless.

If your Sitefinity installation is a bit older and you want to upgrade to the latest release, then here are some troubleshooting steps to keep in mind while performing your upgrade.

As an example upgrade, I attempted to upgrade one of my Sitefinity v. 6.2 projects over to Sitefinity v. 8.0:

First of all, make sure you do the following before attempting to upgrade your project:

  1. Make a backup of your current database
  2. Make a backup of your entire site
  3. Specifically look over the configuration changes in the App_Data\Sitefinity\Configuration folder as well as any Web.config changes and customizations.
Then using Sitefinity Project Manager, go ahead and perform the upgrade.  If asked to perform the Web.config upgrade, go ahead and do so.

Now, in many cases, the Sitefinity upgrade will not work flawlessly and will require several manual merges.  The best starting point is to create a brand new Sitefinity v. 8.0 Sample Project and use that as a comparison point using a comparison and merging tool such as Beyond Compare or any other comparison and merge tool of your choice.

Nearly all of the .config files in the App_Data\Sitefinity\Configuration folder will change from release to release, but these files in particular will probably remain much the same:

  • DataConfig.config
  • PagesConfig.config
  • ProjectConfig.config
  • SecurityConfig.config

In my case, there were minor changes to even the DataConfig.config file and the SecurityConfig.config file.  In the SecurityConfig.config file, I had to retain the main security information and just add the section to support Dynamic Field permissions.

All other files will probably need to be merged manually through a comparison of the latest .config files with your current versions.

One of the major problem causing .config file in nearly every Sitefinity upgrade is the SystemConfig.config file.

If this file does not get upgraded correctly (which is roughly 99.99% of the time), then you are guaranteed to encounter problems with running your upgraded Sitefnity application.  This file actually determines all of the modules that will be available in your application as well as how the database is to be upgraded.  Therefore, if the upgrade fails, you may end up with a database in an inconsistent state with the release version of Sitefinity on your file system.

Well, fortunately, there is a relatively simple workaround for this problem to re-upgrade your database.

After you upgrade your project, you may end up with a SystemConfig.config file like the following:

<systemConfig xmlns:config="urn:telerik:sitefinity:configuration" xmlns:type="urn:telerik:sitefinity:configuration:type" config:version="8.0.5700.0" build="5700" previousBuild="4910">

Therefore, if your Sitefinity upgrade failed, then your database mismatches what your Sitefinity installation is expecting.  In order to rectify this, you can revert the version information of your SystemConfig.config file to force the upgrade once again like so:

<systemConfig xmlns:config="urn:telerik:sitefinity:configuration" xmlns:type="urn:telerik:sitefinity:configuration:type" config:version="6.2.4910.0" build="4910" previousBuild="3450">

The next time you run your application, it should attempt to upgrade the database as well as update the SystemConfig.config file to match the latest version of your Sitefinity installation.

In addition, you may have numerous modules in your SystemConfig.config file such as the following:

        <add startupType="Disabled" name="Multisite" />
        <add version="6.2.4910.0" name="Scheduling" />
        <add version="6.2.4910.0" name="Search" />
        <add startupType="Disabled" version="5.1.3450.0" name="News" />
        <add startupType="Disabled" version="5.1.3450.0" name="Blogs" />
        <add startupType="Disabled" version="5.1.3450.0" name="Events" />
        <add version="6.2.4910.0" name="Libraries" />
        <add startupType="Disabled" name="Forms" />
        <add version="6.2.4910.0" name="Lists" />
        <add startupType="Disabled" name="Analytics" />
        <add startupType="Disabled" version="5.1.3450.0" name="Newsletters" />
        <add version="6.2.4910.0" name="GenericContent" />
        <add version="6.2.4910.0" name="ControlTemplates" />
        <add startupType="Disabled" version="5.1.3450.0" name="Migration" />
        <add startupType="Disabled" name="Ecommerce" />
        <add startupType="Disabled" version="5.1.3450.0" name="ModuleBuilder" />
        <add startupType="Disabled" name="ResponsiveDesign" />
        <add startupType="Disabled" version="5.1.3450.0" name="Publishing" />
        <add startupType="Disabled" version="5.1.3450.0" name="Forums" />
        <add version="6.2.4910.0" name="Thunder" />
        <add startupType="Disabled" name="Personalization" />
        <add version="6.2.4910.0" name="SitefinityDAM" />
        <add startupType="Disabled" name="MobileAppBuilder" />
        <add startupType="Disabled" name="SharepointConnector" />
        <add startupType="Disabled" name="EverliveConnector" />
        <add startupType="Disabled" name="MarketoConnector" />
        <add startupType="Disabled" name="SalesForceConnector" />
        <add version="6.2.4910.0" name="Comments" />

These will all have to be updated to match the correct release versions for your Sitefinity installation:

        <add startupType="Disabled" name="Multisite" />
        <add version="8.0.5700.0" name="Scheduling" />
        <add version="8.0.5700.0" name="Search" />
        <add version="8.0.5700.0" name="News" />
        <add version="8.0.5700.0" name="Blogs" />
        <add version="8.0.5700.0" name="Events" />
        <add version="8.0.5700.0" name="Libraries" />
        <add startupType="Disabled" name="Forms" />
        <add version="8.0.5700.0" name="Lists" />
        <add startupType="Disabled" name="Analytics" />
        <add version="8.0.5700.0" name="Dashboard" />
        <add version="8.0.5700.0" name="Newsletters" />
        <add version="8.0.5700.0" name="GenericContent" />
        <add version="8.0.5700.0" name="ControlTemplates" />
        <add startupType="Disabled" name="Ecommerce" />
        <add version="8.0.5700.0" name="ModuleBuilder" />
        <add startupType="Disabled" name="ResponsiveDesign" />
        <add version="8.0.5700.0" name="Publishing" />
        <add version="8.0.5700.0" name="Forums" />
        <add version="8.0.5700.0" name="Thunder" />
        <add startupType="Disabled" name="Personalization" />
        <add version="8.0.5700.0" name="SitemapGenerator" />
        <add version="8.0.5700.0" name="SitefinityDAM" />
        <add startupType="Disabled" name="MobileAppBuilder" />
        <add startupType="Disabled" name="SharepointConnector" />
        <add version="8.0.5700.0" name="EverliveConnector" />
        <add startupType="Disabled" name="MarketoConnector" />
        <add startupType="Disabled" name="SalesForceConnector" />
        <add version="8.0.5700.0" name="DataIntelligenceConnector" />
        <add version="8.0.5700.0" name="Comments" />
        <add version="8.0.5700.0" name="RecycleBin" />
        <add startupType="OnApplicationStart" version="" name="Feather" />
        <add title="Audit Trail - Elasticsearch" description="Logs audit events to an Elasticsearch instance." moduleId="00000000-0000-0000-0000-000000000000" type="Telerik.Sitefinity.Audit.Elasticsearch.ElasticsearchAuditModule, Telerik.Sitefinity.Audit.Elasticsearch, Version=8.0.5700.0, Culture=neutral, PublicKeyToken=4d437ae15f42fd43" startupType="Disabled" name="ElasticsearchAudit" />

Next, you may have to merge your Web.config file to match any of the latest changes.

Finally, since your Visual Studio project references are no longer valid, you will probably have to merge your Visual Studio project changes with the latest project changes and re-compile your solution.

If you have done all of the above, you can now try re-running your application.  If all went well and your application runs without throwing exceptions, you have successfully upgraded your Sitefinity application to the latest release!

No comments:

Post a Comment