Sitecore Version Upgrade Whitepaper V1.0
Sitecore Version Upgrade Whitepaper V1.0
Sitecore Version Upgrade Whitepaper V1.0
Contents
Disclaimer: .........................................................................................................................................3
Introduction: ......................................................................................................................................4
The Basic Sitecore Solution: .........................................................................................................4
The Expert Sitecore Solution: .......................................................................................................4
What is Sitecore Version Upgrade? ......................................................................................................5
Why upgrade our current Sitecore Solution to a later version? ..............................................................6
How to approach a Sitecore Version Upgrade? .....................................................................................6
Basic Sitecore Solution: ...................................................................................................................6
Verify that the version we selected as Target Version is not mentioned only as a feature
release or to be used as only an intermediate version: ................................................................ 10
Check if there are any Known Issues for our selected version: .............................................. 10
Check if we need to upgrade the .NET Framework for our solution: ...................................... 18
Check if for our target version, we need to upgrade the OS on our Development boxes as well
as our Live Servers:.................................................................................................................... 19
Check if the target version requires us to upgrade our SQL Server: ....................................... 19
Check for compatibility of the Sitecore Marketplace modules installed in our solution with the
required Target version: ............................................................................................................ 20
Check our custom code which uses some DLLs from Sitecore instance NewtonSoft,
HTMLAgilityPack, etc ................................................................................................................. 21
Expert Sitecore Solution: ............................................................................................................... 21
How to Upgrade our Current Sitecore Solution? ................................................................................. 21
Sitecore Version Upgrade for a Basic Solution:................................................................................ 21
Content Authoring Server: ......................................................................................................... 21
Content Delivery Server:............................................................................................................ 23
Sitecore Version Upgrade for an Expert Solution: ........................................................................ 24
Content Authoring Server: ......................................................................................................... 24
Content Delivery Server:............................................................................................................ 26
Frequently Asked Questions .............................................................................................................. 26
Sitecore Endeavor
1|P age
If you are upgrading your Sitecore solution, do keep at least one of your older versions up and
running..................................................................................................................................... 30
Sometimes, if you get an error related to the Database Schema, dont worry, just proceed to
your Target Version. To confirm, ask Sitecore Support. ................................................................ 31
Do you have some Jumbled JSON seen on your Browser page in Page Editor Mode? ............. 31
Shrink Databases and Rebuild the Indexes from the Management Studio to have a faster
operation.................................................................................................................................. 31
We run into some issue after upgrade Google it out or raise with Sitecore Support ............ 32
Create an Upgrade team (IT Infrastructure Team, Developers & QA) to discuss various
scenarios from their perspectives. .............................................................................................. 32
Perform Bug Bash for every environment and make sure every Bug is resolved and then we
move to the environment ahead. ............................................................................................... 32
Document the Approach and Full Steps of Upgrade and discuss with the Upgrade Team ....... 32
References: .................................................................................................................................. 32
Tools that can be useful: ............................................................................................................... 33
Sitecore Endeavor
2|P age
Disclaimer:
My dear Sitecore Family,
This document is an effort of sharing the experience and learning that I gained while working on a Version
Upgrades for a number of Sitecore Solutions.
There are always a number of questions that any/every developer has in his/her mind before going ahead
with an upgrade for their Sitecore Solution. This document tries to get you through a number of questions
which our managers would ask us and we probably wont have it at the first go. It includes a number of
frequently asked questions regarding the Sitecore Version Upgrade.
A number of diagrams/figures included in the document are made by me to explain things in a simple
way. The document may even include a few screenshots from some links on Sitecore Developer Network
Release notes, Upgrade Steps and a number of blogs, to explain things in detail and make things easy to
understand.
This document is for the Sitecore community to understand the various things included in upgrading a
Sitecore solution as well as getting thorough with the small and big details of the same.
The information included in this document is solely to understand things more about the Sitecore Upgrade
process and I sincerely regret if any information here is wrong. At the same time, it would be great if you
could let me know if you find an error in it. A kind request to all those who are more experienced or have
had some different experience, to please share their knowledge about the topic. I would include it in this
document to make it a concise and a precise document for every one of us the ones upgrading their
solution for the first time as well as for the ones who have been doing it.
Sincerely,
Varun Shringarpure
Sitecore Endeavor
3|P age
Introduction:
Sitecore Version upgrade, is a process which involves a set of steps performed on our Sitecore Solution,
to upgrade it to the version of Sitecore later than what we currently have.
We need to categorize the Sitecore Version Upgrade, into two main sections based on some tools that we
use for our Sitecore Solutions:
A. The Expert Sitecore Solution a Solution using an Item Synchronization tool like TDS, Unicorn
or Sitecore Development Toolkit.
B. The Basic Sitecore Solution a solution without any Item Synchronization tool.
Before continuing further, lets get some basic details of the above two.
Sitecore Endeavor
4|P age
Sitecore Endeavor
5|P age
Both the approaches look quite simple in the first look but as we go deeper into the core of its
understanding, it gets equally critical for us as well as our clients who owns that Sitecore solution.
6|P age
Sitecore Endeavor
7|P age
4) Now we can see Release Notes for those particular Main versions and go to the Release History
Section which is the Change Log that Sitecore provides for each version, specifying the main
highlights of the version, new features and functionalities, the main improvements, bug and
security fixes. Below are a few screenshots which might help us to reach there.
Sitecore Endeavor
8|P age
5)
6)
7)
8)
9)
This section, generally proves to be the main decider whether we want to go ahead with that
version as our target version or not and I think the credit goes to Sitecore for writing it so well!
At the top, will be the last released version say 7.5 for Sitecore CMS 7. In a normal scenario, we
would directly select the latest Sitecore Version available, select it as a Target Version and decide
to upgrade to it.
But, say for some reason (which is kind of very rare) we need to upgrade to a Sitecore Version
only till the point where our new Feature or Bug Fix requirement gets solved. In that case, move
bottom-up in the Sitecore Change Log. Select any particular version from the left menu, and start
reading its main features, newly added functionalities, code improvements, bug fixes, security
updates, etc.
While coming from top to bottom in these steps, we will definitely identify whether the version
we selected is the one we wanted. But still, its good to question ourselves once again does this
version suffice the main purpose of upgrade?
If no, then repeat the steps with a version later than that above in the list on left menu.
If yes, then that becomes our Target Version.
Sitecore Endeavor
9|P age
Verify that the version we selected as Target Version is not mentioned only as a feature
release or to be used as only an intermediate version:
There are a number of times, when Sitecore mentions a particular version not to be selected as a target
version and a higher version of Sitecore to be selected as a Target version. Consider this case of Sitecore
6.4.0 Initial Release:
Lets make sure, we havent selected any version which Sitecore has already mentioned not to use as a
Target version.
Check if there are any Known Issues for our selected version:
This is very rare, as Sitecore thoroughly tests every version of Sitecore before releasing it. But quite
possible, that a version of Sitecore may have some issue. In the Release Notes section, below the Release
History, is a link to all the Known issues for that version of Sitecore. Ill take a case of Sitecore CMS 6 for
this case.
Clicking it, takes us to the page where all the known issues are mentioned, as below.
Sitecore Endeavor
10 |
Page
Drilling down further, the description of each issue and its solution is available in a page on Sitecore
Knowledge Base.
Say details of 2.1 Content changes of media items may not be reflected in browser immediately are
available at https://kb.sitecore.net/articles/218124
Sitecore Endeavor
11 |
Page
Sitecore Endeavor
12 |
Page
It leads us to a page where download links for particular main versions as well as the minor versions of
Sitecore may be available.
Alternatively, we can also go to the download link of a particular version from the main links of Sitecore
CMS & DMS too as seen below:
Sitecore Endeavor
13 |
Page
Just below the release notes, a section says Download CMS+DMS, click there and it will take you to the
same downloads page as seen above.
Moving down further, lets say, Ill click on Sitecore 7.2 Link, then it will take me to the main downloads
page for that particular version of Sitecore.
Sitecore Endeavor
14 |
Page
On the left, well be able to see the download links for various other Sitecore 7 versions released by
Sitecore.
Sitecore Endeavor
15 |
Page
As we can see, the first sub-section specifies the pre-requisites of this version.
Sitecore Endeavor
16 |
Page
Sitecore Endeavor
17 |
Page
Also, I found a nice website Sitecore Update helper developed by Alexander Doroshenko though not
updated, can be very helpful to us identifying the number of iterations that we might require http://sitecoreupdate.somee.com/Default.aspx
Sitecore Endeavor
18 |
Page
Check if for our target version, we need to upgrade the OS on our Development boxes as
well as our Live Servers:
Sitecore manages this at the same location it manages the above Sitecore CMS Compatibility Table. A
screenshot of the related section of it is as follows:
19 |
Page
Check for compatibility of the Sitecore Marketplace modules installed in our solution with
the required Target version:
Sitecore manages a list of modules and its compatibility table is managed by them in Sitecore Knowledge
Base here: Sitecore Modules Compatibility Table. If the modules of our concern is here, we can easily
identify and note that down. In case the module you have installed, is not in this list, not to worry!
Generally, with every Sitecore marketplace module, its requirements section specifies the various versions
of Sitecore on which it might run.
As in the above example, what this means is, this particular module is tried and tested well by the
developer till Sitecore 6.5 doesnt specifically mean it wont run on Sitecore 6.6 or above, but it ideally
means it might not. But for us to be on a safer side, we need to make a list of all the modules and identify
from its Requirements which might not work with our Target Sitecore solution. Best would be to try that
particular module on a plain Sitecore solution of our target version.
Considering the worst case, we are able to identify that a particular Sitecore module is no more working
or throwing errors in our log file for being incompatible its nothing to worry about, as many of the
Sitecore Enthusiasts put up the code for the module on GitHub. So either we might ask the developer of
the module to update the code for the version of Sitecore we want or we ourselves update it and push
the changed code to GitHub for others to use. In case the module we use is just as a package on the
marketplace and its code isnt available, we can ask its developer to help us out as well as raise the same
with SDN Forum or Sitecore Support I guess. In parallel to that, we can decompile the code of that module
in a reflector or any such decompiler, create a class library with the required changes in the code of the
module, change the code references at required places and make it working.
Sitecore Endeavor
20 |
Page
Check our custom code which uses some DLLs from Sitecore instance NewtonSoft,
HTMLAgilityPack, etc
Sometimes, due to some specific requirement, we might have made some tool or functionality using some
DLL which is present in the Sitecore solution like say NewtonSoft or HTMLAgilityPack. This is because with
some of the new versions, Sitecore has upgraded these DLLs, and quite possible, that might affect our tool
or functionality. So to be better prepared, lets make a list of various functionalities in our custom code
that uses them as we might need to update them as per the new DLL added.
21 |
Page
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
so if Sitecore recommends it, as it might have some bug fixes/updates which are of our help
moving forward.)
Upload the Sitecore Update package.
Analyze the Package.
Download Analysis Log and Analysis Report and store it somewhere.
Install the Package.
Download Installation Log and Installation Report and store it somewhere.
Execute the Post-Install (After Install) SQL Script to update the DB Schema (if any).
Make the necessary Config changes (refer to these two questions in Frequently Asked
Questions, for more details Configuration Question 1 & Configuration Question 2
Clear Browser Cache
Once the Sitecore instance is up, go to Sitecore Desktop and Rebuild Search Indexes
Follow steps 3 through 15 till we reach the required Target Version of Sitecore.
Deploy our Custom code changes DLLs, files, etc.
Sitecore Endeavor
22 |
Page
Next is identify the list of item/s that we need to publish from the Installation Logs/Report.
23 |
Page
24 |
Page
Sitecore Endeavor
25 |
Page
What should I do if I have multiple CM/Content Authoring Servers? Do I need to execute the
Sitecore Update Wizard on all those Content Authoring instances?
We have almost got to a conclusion as to what does a Sitecore Version Upgrade include:
Now whenever we Upgrade the Sitecore Version of one of the multiple Sitecore Content Authoring
instances we follow all the above 4 steps.
About the Pre and Post SQL Scripts they are for updating the Database Schema as we have multiple
CM/Content Authoring servers their Core and Master DB would be same. So we dont need to execute
them again. Next, about the Sitecore Update package - the item changes are already done in the Database
so ideally your Database is upgraded.
So what remains in upgrading the rest of our CM/Content Authoring instances are Config Files and our
Custom Code files and DLLs. As our multiple instances would have the same configuration except a few
say the instance name the upgrade Config changes would be identical, so, we dont need to make those
changes to configs of each of the instance. Instead, make the changes to one, and copy the same files to
other instances with the required changes as per our environment. (We would ideally be managing this
in our repository)
Thus, if we have multiple Sitecore Content Authoring servers, and we want to upgrade our Sitecore
Version:
We need to execute all the Sitecore Upgrade Steps on one instance
Deploy the config & Code changes on all of the servers.
Sitecore Endeavor
26 |
Page
What if I have a Dedicated Publishing Instance along with my Content Authoring Server?
A Dedicated Publishing Instance, can be said as a Content Authoring Server specifically for publishing
our item changes.
So in this case too, we should follow the steps mentioned above .
Execute the SQL Scripts Pre and/or Post Scripts (if any).
Publish the items changed by Sitecore during upgrade.
Push all our Custom code as well as Sitecore files and configs as a deployment package onto our
CD Servers.
I am confused seeing so many links for the changes required to be done in my config file. How
should we perform the config changes?
Sitecore manages the config changes for upgrades very nicely and easy to understand and do. Lets take
an example to understand this better.
Say we are currently moving from Sitecore 6.4.0 Initial Release to Sitecore 6.5 Initial Release. So we would
be referring to the Upgrade Instructions for Sitecore 6.5 Initial Release. The link for that is as follows:
http://sdn.sitecore.net/Products/Sitecore%20V5/Sitecore%20CMS%206/Update/6_5_0_rev_110602.as
px
The Config file update section in that is as follows:
Sitecore Endeavor
27 |
Page
As we can see above there is a different link for each config entry and the ones that we need to choose is
based on from what version we moved to this version. In our case, we will need to go through all the links
and apply all the changes mentioned there.
But say for example, if we were upgrading to Sitecore 6.5 Initial Release from 6.4.1 Initial Release, then
we had to apply the changes suggested in the first two links only, and we could do away with th e latter
two. And to verify that, we can open any one link of the latter two and check for a random config entry
it would be present in our current config also.
Doing the Configuration changes for version upgrades is a tough task, is there an easier way to
do that?
We can divide the Sitecore solutions in yet another two types:
1. Loosely-coupled Sitecore Solution: A Sitecore solution, where we add a new configuration file
for our case instead of changing the Sitecore Configuration files.
2. Tightly-coupled Sitecore Solution: Changing the Sitecore Configuration files (say Web.config, or
Commands.Config etc)
When configuring a Sitecore Solution, its always a best practice create own configuration file for the
required settings, instead of updating the Sitecore Configuration files. Say, creating a SiteDefinition.config
for a new site that is added, instead of adding a site tag in the web.config and creating a custom index
configuration and definition file, instead of changing the current DefaultConfiguration file or index files.
Benefit of a loosely-coupled solution from Sitecore Version Upgrade perspective:
We can directly replace the current configuration file with that in the Target Version
If in case we have missed doing so in our current solution, not to worry, we can do so in upcoming Sitecore
projects.
Also, for now, we can work a little smart and avoid doing config changes for each and every environment
manually. How?
Steps:
Create Visual Studio Publish Profiles for various environments.
Sitecore Endeavor
28 |
Page
Install SlowCheetah XML Transforms and create the Transforms for all the config files No need
to do it manually, there is a nice Marketplace module available by Chris Le es Sitecore Upgrade
Automation. Use it and make the required changes.
Apply the config changes that are needed as per the Sitecore Upgrade links.
Once we build our solution all the changes would be available for the files of rest of the
environments too.
We have an Expert Solution but not all items are synced. The Templates, System and Layouts are
fully synced but Content and Media Library on Live Content Authoring Server has many items
then in my Repository. What can we do?
Generally, thats the approach that most of us follow for all of our projects. For a development team, what
is most important is Templates, Sublayouts and System (if we have written some rules etc.). As far as
Content and Media Library is concerned, we just put the main items (say homepage item of site, settings
item of a site, etc) and a few items to unit test our test cases. Otherwise, the complete site specific content
i.e. Content and Media Library is on our Live Content Authoring Server.
So we have a few options that we can do:
1. Upgrade the Sitecore Solution the basic way:
Apply all the required upgrades from our current version till the target version just as if we have a basic
Sitecore Solution. This is the safest way of making sure that our required content and data is consistent
and we dont lose absolutely anything. But the disadvantage is the time taken yes, this would take a
longer time.
2. Bring all our items from Live Content Authoring to our Local environment before taking up
Upgrade:
Package all Content and Media Library items and bring it to our Local Environment or
Backup the Live Database and restore it in our Local environment.
Get it serialized using some Item synchronization tool TDS, Unicorn, Sitecore
Development Toolkit and commit it to our repository
Next, follow the steps for Sitecore Version Upgrade of an Expert Solution.
For the second case, we can even use the Sitecore Instance Comparer tool - Meerkat Compare Sitecore
instances over HTTP. This will give us the Update package with all the item changes and we can install this
update package in our local, synchronize the items and follow the Expert Solution upgrade steps.
While installing the Update package, my Sitecore instance suddenly crashed and I could not
download my Installation Log and Report. Can I get it from somewhere?
Yes, we can get it.
Sitecore stores all the files while upgrading at a location: website/temp/__UpgradeHistory Folder. All the
upgrades that we perform on our solution, it creates a specific directory in this folder and dumps all the
files. So from here, we can get the Log or Report files.
Sitecore Endeavor
29 |
Page
We somehow happened to find it while installing the Upgrade Package in our local environment. Without
going into much details of it, I would like to share an article written by Kiran Patil, which explains it fully
http://sitecorebasics.wordpress.com/2012/02/26/browser-timeout-error-while-doing-sitecore-versionupgrade/
By default, these two settings are set to 5 minutes, and they are not present in the Web.Config file. But,
we can add them, in case we want to override them, and set it to something greater than that.
Lets understand why this is required. Sitecore Version Upgrade consists of two main things the
Database Upgrade Scripts and Installing the Upgrade Package.
Applying the Upgrade scripts is never a problem, because we are directly working on the Database with
Database Management System (i.e. say SQL Management Studio in case of SQL Database).
But, while installing the upgrade package, it is a continuous database activity from Application to the
Database. And the time required to install the upgrade package, could be relatively dependent to our
database size or change of some critical items and hence take long time to complete for us it took some
Hours!
We tried without changing this setting and the Sitecore instance gave us SQL Timeout while executing the
package, but after changing these settings, it worked fine for us. Some details about what these settings
would do they define how long the .Net Code will wait, before it declares that the SQL query has timed
out. These settings, would allow some heavy queries to be executed successfully instead of been claimed
as time out.
To override these settings, please add the following in the <settings> section in Web.Config File:
<setting name=DefaultSQLTimeout value=00:30:00/>
<setting name=DataProviderTimeout value=00:30:00/>
If you are upgrading your Sitecore solution, do keep at least one of your older versions up
and running.
We as a team, had marked this point as Highly Important. We absolutely must have at least one old version
running either in our Development Environment or somewhere, so that at any point of time we can
directly compare after upgrading our Sitecore Solution to the target version. This is not just useful for our
QA Team to test for it, but even for our own unit testing.
Sitecore Endeavor
30 |
Page
Sometimes, if you get an error related to the Database Schema, dont worry, just proceed
to your Target Version. To confirm, ask Sitecore Support.
It happened so in our case, while we were upgrading once. We contacted Sitecore Support, and we got a
great response from them. For more details on it please refer to the following article:
http://varunvns.wordpress.com/2012/06/12/error-while-applying-upgrade-invalid-column-namesequence/. In our local development box, we can take a risk of moving ahead with our next intermediate
version or the target version. But it is good to consult Sitecore Support, with what we faced, just to
confirm it.
Do you have some Jumbled JSON seen on your Browser page in Page Editor Mode?
Please check this article my John West for the solution: http://www.sitecore.net/Community/TechnicalBlogs/John-West-Sitecore-Blog/Posts/2011/06/Sitecore-Page-Editor-Renders-Jumbled-JSON-asContent.aspx
Shrink Databases and Rebuild the Indexes from the Management Studio to have a faster
operation.
This was particularly very helpful for our case. We had Master Database as big as 25GB in our local
environment and in our Live Environment, the Master DB was 150GB+. Also, we had found that our
Databases were running with full recovery mode.
Due to this, the LDF file grew high as big as 7GB. Our DBA suggested, to shrink the Database LDF files
and rebuild the Indexes and then start with the Upgrade process. In our local, we had took statistics and
found that there was a difference of around 25 minutes. And hence we decided to go ahead with that.
Why Shrink & Rebuild your Databases Indexes? Shrink so that you dont have a heavy LDF files, and
all/most of your data is in MDF & Rebuild Index so that the indexes are in perfect order and the database
transactions for upgrade process would be performed faster.
Sitecore Endeavor
31 |
Page
Always Analyze and then Install the upgrade package, and make sure you save all these Log Files. If in case
we run into issues, these files could be very handy say to read and identify or to provide to Sitecore
Support if the criticality of the condition be.
We run into some issue after upgrade Google it out or raise with Sitecore Support
The Sitecore community is strong and many share some really great information on their blogs or raise
issues on Forum or with Sitecore Support. So in case we run into some random & weird issue, first thing
would be to search on the web. Most of the time, if someone else encountered it, it could be on the SDN
Forum and someone might have provided its solution, or we might get a link to the Sitecore Knowledge
Base or some Blog of a Sitecore Enthusiast. In case we dont find anything, its quite critical fir us and cant
wait for it to get solved, we should consult Sitecore Support. Otherwise, we can raise on SDN Forum too.
Create an Upgrade team (IT Infrastructure Team, Developers & QA) to discuss various
scenarios from their perspectives.
Each team member have their own perspective, and their own domain of working. So discussing things
with them on multiple intervals during upgrade is quite vital.
Perform Bug Bash for every environment and make sure every Bug is resolved and then
we move to the environment ahead.
Bug Bash is a very necessary step, as every user Developer, Content Author, Administrator, QA, and
Subeditor has his/her own perspective of working and checking things. So after upgrading our
environment, once our unit testing is over, we must perform Bug Bash, mention the bugs found at a
central location say Google Doc solve them, deploy the fixes on that environment, unit test them again
and only then move to the next environment.
Document the Approach and Full Steps of Upgrade and discuss with the Upgrade Team
It is a must that we document things the approach as well as the steps of upgrade, what needs to be
done when and how. Next, we must discuss these steps with the Upgrade Team members and get it
verified update the document as necessary. Keep on updating this document on regular intervals so that
we have a complete set of learnings till we reach the Live Environment. For the live environment, divide
the Upgrade tasks upgrading the Main Content Authoring Server, other Content Authoring Servers or
Publishing Instance, the Content Delivery Servers and their sub-tasks in sub teams of the main Upgrade
Team, to work it out in parallel to spend most time testing instead of upgrading.
References:
http://varunvns.wordpress.com/2012/06/06/basics-of-sitecore-version-upgrade/
http://varunvns.wordpress.com/2012/06/18/some-findings-while-sitecore-version-upgrade/
http://varunvns.wordpress.com/2012/06/12/error-while-applying-upgrade-invalid-columnname-sequence/
http://www.nonlinearcreations.com/Digital/how-we-think/articles/2014/05/Sitecore-UpgradeTips.aspx
Sitecore Endeavor
32 |
Page
Sitecore Endeavor
33 |
Page