The upgrade tool only upgrades the product platform and not the solution. Templates, images, page types or script files (which are stored in the “/UI”, “/App_Code” and “/Site” folder) are part of the solution and will therefore not be updated. Since there is likely breaking changes between product versions, you will also have to ugrade the customizations made to other parts of the solution.
1. Read the documentation
What is new? >>>
Breaking changes >>>
Release notes >>>
API documentation >>>
1. Make the solution compilable - read about breaking changes and other news
After the product platform has been upgraded, you need to make your entire solution compile. In many cases it will not, because of customizations made (templates, page types, add-ons, plug-ins etc) that might not be compatible with the latest Litium Studio version. This is due to breaking changes between product versions.
Before you try to compile your solution you need to update the target .NET framework version on each project/website to point to ".NET Framework 4.5.2". You need do that on the property page of each project, see the following exampel how the page can look.

2. Check the file data
Check that all rows in the database that should have a reference to a file, has a storage path for that file. If the path is missing for some row the file is not moved from the old file location. Use the sql-script in FileStorageCheckAfterUpgrade.sql at the bottom of this page.
3. Application pool
If the application pool of your website was running with classical mode before the upgrade change it to integrated mode.
4. Change paths
- The Templates folder (including sub folders) is moved to the Site/CMS/ so you have to replace the path with the new one in the templates. Ex: replace ~/Templates/ with ~/Site/CMS/Templates/ and ../Templates/ with ../Site/CMS/Templates/.
- Content of the Modules folder (including sub folders) is moved to LitiumStudio folder so you have to replace the path with the new one in the templates. Ex: replace ~/Modules with ~/LitiumStudio and ../Modules with ../LitiumStudio.
- Content of Pages folder and one of its sub folders Pages/WebUserControls are moved to LitiumStudio/Foundation so you have to replace the path with the new one in the templates. Ex: replace ~/Pages/filename.xxx with ~/LitiumStudio/Foundation/filename.xxx, ../Pages/filename.xxx with ../LitiumStudio/Foundation/ filename.xxx, ~/Pages/WebUserControls with ~/LitiumStudi/Foundation/WebUserControls and ../Pages/WebUserControls with ../LitiumStudio/Foundation/WebUserControls.
- Other subfolders of Pages are moved to LitiumStudio so you have to replace the path with the new one in the templates. Ex: replace ~/Pages/Images with ~/LitiumStudio/Images and ../Pages/Images with ../LitiumStudio/Images.
- Newsletter templates are moved from Modules/Circular/Templates to Site/Newsletter/Templates. Login to back office and edit the templates of the Newsletter module via settings of the Newsletter module. Replace the occurrence of Modules/Circular/Templates with Site/Newsletter/Templates.
5. Changes in name spaces
• Circular.Web has been changed to Litium.Studio.UI.Newsletter.
• CMS.Web has been changed to Litium.Studio.UI.CMS.
• CMS.Templates has been changed to Litium.Studio.UI.CMS.Templates.
• Common.Web has been changed to Litium.Studio.UI.Common.
• Common.WebServices has been changed to Litium.Studio.UI.Common.WebServices.
• ECommerce.Web has been changed to Litium.Studio.UI.ECommerce.
• Foundation has been changed to Litium.Studio.UI.Foundation.
• MediaArchive.Web has been changed to Litium.Studio.UI.MediArchive.
• ProductCatalog.Web has been changed to Litium.Studio.UI.ProductCatalog.
• ProductCatalog.WebServices has been changed to Litium.Studio.UI.ProductCatalog.WebServices.
• Relations.Web has been changed to Litium.Studio.UI.Relations.
6. Remove unused files
Remove the files in the /Site/Cms/EditPages if they are not used in the solution.
7. Delete or replace files
Upgrade tool replace some template files in Site/CMS/Templates if the file is the standard one from the release package of the Litium Studio version 4.4.3. If you did not upgrade your templates based on the new framework Site/CMS/Templates/Framework/Base.master from upgrade package of the Litium Studio version 4.7 replace the changed files with the ones from the backup of your solution. If you do not use the file in your solution remove it (with the code behind file) permanently.
8. Style sheet handling
If you did upgrade your templates based on the new framework Site/CMS/Templates/Framework/Base.master, use UI/Css/base.ashx to include style sheets.
9. Configuration values
In Litium Studio 4.4.3 ConfigurationManager and some constants were used to get the configuration values. These constants are deprecated in Litium Studio 4.7 and configuration values can be now reached via Configuration classes or other appropriate class.
• Use Solution.InstanceDataSettings.ConnectionString instead of ConfigurationManager.ConnectionStrings[WebConfigConstants.CONNECTION_STRING].
• Use FoundationContext.SMTPServer or Litium.Foundation,Configuration.GeneralConfig.Instance.SMTPServer instead of ConfigurationManager.AppSettings[WebConfigConstants.SMTP_SERVER].
• Use Litium.Foundation,Configuration.GeneralConfig.Instance for general configuration values.
• Use Litium.Studio.Configuration.StudioConfig.Instance.ModuleName for module specific configuration values.
10. Litium.Plus.dll
In old versions of Litium.Plus “<div>” tags were used to list items. In the latest version “<ul><li>..</li></ul>” tags are used for this purpose. Style sheet used for the Litium.Plus web controls has to be updated so that they can handle also “<ul><li>” tags.
11. Upgrade add-ons (skip this step if no add-ons are used in the solution)
Add-ons are products but still considered part of the solution. If an add-on has been customized in the solution it should be upgraded in the project. But there is also the possibility to download complete upgraded add-ons, for example the most common payment providers.
12. Web.config file
12.1 Solution specific registrations and extension/add-on registrations are not moved
If you have solution specific registrations or extension/add-on registrations in the web.config file, those rows are not moved to the new web.config file. You have to move them manually.
12.2 Check the moved configuration values
Check that the following configuration values (“XXXX”) are correctly moved to the new web.config file by comparing with your old web.config file from your solution back up.
• <systemUser enabled="true"/>
• <add name="FoundationConnectionString" connectionString="Pooling=true;User Id=XXXX;Password=XXXX;Database=XXXX;Server=XXXX" providerName="System.Data.SqlClient"/>
• <filesDirectory value="XXXX"/>
• <smtpServer value="XXXX"/>
• <appender name="LitiumStudioFileLog" type="log4net.Appender.RollingFileAppender">
<file value="XXXX"/>
Check all other values that are differing from the standard web.config of the Litium Studio 4.4.3.
12.3 All the payment providers except direct pay are disabled by commenting out them in <plugins> section.
Enable the payment providers that are used in your solution by removing the comment out “<!-- -->” tags.
12.4 Custom setting pages.
If there is a custom settings page in your solution that is registered in the <appSettings> section as follows:
<add key="ControlPanelPages" value="../Modules/XXXX/XXXX.aspx,../Pages/images/icons_modules/XXXX.png,XXXX;....”
you have to register it in the new web.config as below:
<litium>
<foundation>
<general>
<controlPanelPages>
<systemSettings>
<controlPanelPage page="~/Site/XXXX/XXXX.aspx" icon="~/Site/XXXX/Images/XXXX.png" systemStringKey="XXXX" permission="All"/>
In order not to lose those settings files during future upgrades (since the Upgrade tool will override the LitiumStudio folder in future upgrades), the upgrade tool moves the custom setting pages from Modules/XXXX to Site/XXXX but not the image files. You have to move the image files to Site/XXXX/Images manually and do the required path changes in your settings files.
13. Search result
Percentage for search results can differ from the Litium Studio version 4.4.3 after the upgrade since the search in Litium Studio version 4.7 includes some extra properties of the pages.
14. ProductCatalogGroup page type
ProductCatalogGroup pages were used to publish the product groups and products on the public web site in Litium Studio version 4.4.3. The ProductGroupID property of the pages was used to set the product group from which the listing of product groups and products will start. Since the product groups could not be marked as published/unpublished in the Product Catalog module, product groups of a product catalog (root product group in version 4.7) were published by using different ProductCatalogGroup pages. It was not possible to publish the root product group (product catalog in version 4.4.3) using only one ProductCatalogGroup page if all the sub groups will not be published on the public web site.
In version 4.7, it is possible to mark product groups as published/unpublished in the Product Catalog module. As a result it is possible to publish a root product group (old product catalog) using only one page. A new page type is introduced in version 4.7 for this purpose: ProductCatalogPage. Use only one instance of this page type to publish a root product group (old product catalog) on a web site. Upgrade tool converts all the product catalogs to the root product groups of the assortment Migrated.
Upgrade tool converts also all the ProductCatalogGroup pages to ProductCatalogPage pages (pages with a globe icon). If root product group (old product catalog) is published by only one ProductCatalogPage page (no other ProductCataologPage page that publishes some sub groups of the root folder) then check if the Include sub groups checkbox is checked at the Product group menu of the page.
If several ProductCatalogPage pages are used to publish sub groups of a root product group (old product catalog) many of those pages will be unpublished because of the url restrictions that are introduced in version 4.7.

Our recommendation in that case (several ProductCatalogPage pages are used to publish sub groups of a root product group) is to convert all those pages to Redirect pages in order to preserve url-history of all the products and product groups that are published on the public web site and to be able to return a permanent redirect code 301 for the product group (only for the product group that is registered in the ProductGroupID property of the page) that is published via those pages. We assume that only one root product group (old product catalog) is published per web site.
14.1 Install the page type Redirect if it is not already installed in your solution.
Add a settings property of type Product group id with name ProductGroup to the page type Redirect. The property has to be shown in edit mode.

14.2 Change the following code in the Page_Load method of your Redirect1.aspx.cs
// Get the redirect url property of the page
StringShortProperty redirectURLProperty = null;
try
{
edirectURLProperty = CurrentSettings["RedirectURL"] as StringShortProperty;
if (redirectURLProperty != null && redirectURLProperty.ValueCount > 0 && redirectURLProperty.GetValue() != null && redirectURLProperty.GetValue() != "")
redirectURL = redirectURLProperty.GetValue().Trim();
else
redirectURL = UrlConstants.PAGE_DEFAULT;
}
catch
{
redirectURL = UrlConstants.PAGE_DEFAULT;
with this code:
// Get the redirect url property of the page
StringShortProperty redirectURLProperty = null;
try
{
edirectURLProperty = CurrentSettings["RedirectURL"] as StringShortProperty;
if (redirectURLProperty != null && redirectURLProperty.ValueCount > 0 && redirectURLProperty.GetValue() != null && redirectURLProperty.GetValue() != "")
redirectURL = redirectURLProperty.GetValue().Trim();
else
redirectURL = UrlConstants.PAGE_DEFAULT;
}
catch
{
redirectURL = UrlConstants.PAGE_DEFAULT;
}
with the code below
// Try to get the product group
ProductGroupIDProperty productGroupID = CurrentContent["ProductGroup"] as ProductGroupIDProperty;
if (productGroupID == null)
productGroupID = CurrentSettings["ProductGroup"] as ProductGroupIDProperty;
if (productGroupID != null && productGroupID.ValueCount > 0)
{
ProductGroup productGroup = null;
try
{
productGroup = ProductGroup.GetProductGroup(productGroupID.GetValue(), FoundationContext.Token);
}
catch { }
if (productGroup != null)
redirectURL = productGroup.GetUrl(CurrentState.WebSiteID, CurrentState.IsInAdministrationMode);
}
// Get the redirect url property of the page
StringShortProperty redirectURLProperty = null;
try
{
redirectURLProperty = CurrentSettings["RedirectURL"] as StringShortProperty;
if (string.IsNullOrEmpty(redirectURL))
{
if (redirectURLProperty != null && redirectURLProperty.ValueCount > 0 && redirectURLProperty.GetValue() != null && redirectURLProperty.GetValue() != "")
redirectURL = redirectURLProperty.GetValue().Trim();
else
redirectURL = UrlConstants.PAGE_DEFAULT;
}
}
catch
{
redirectURL = UrlConstants.PAGE_DEFAULT;
}
14.3 Run script to convert pages
Run the sql-script ConvertProductCatalogPagesToRedirectPages.sql (found at the bottom of this page) to convert all the ProductCatalogPage pages to Redirect pages. Set the name of the website to which the ProductCatalogPage pages belong in the sql-script before you run it: replace “XXXX” with the website name in SELECT @WebSiteName = 'XXXX'. Finally, publish those pages that became unpublished after the upgrade.

14.4 Create a new Product Catalog Page
Create a new ProductCatalogPage page at the same web site, select the root product group (old product catalog page) as the product group and check the Include sub groups checkbox at the Product group menu of the page.

14.5 Repeat steps 3-4 for each web site that have several ProductCatalogPage pages publishing sub groups of a root group (old product catalog).
14.6 Finally install Workaround for old product catalog urls published via several pages.
15. Rebuild the search indices
The last step in upgrading the solution is to rebuild all search indices. Log into the Litium Studio back office and open the Control Panel/System settings/Search indices. Click the Rebuild All button.
16. Make sure the solution compiles!
Make sure your solution compiles without errors. Your upgrade is now complete.