Just deployed the latest and greatest in Sitecore for my company. The guy on the left knows what I am talking about.

With the multiple languages and the complexity level of my company’s site, this was not a simple process of just running a couple of SQL update scripts and modifying some lines in the web.config. This upgrade took at couple of weeks and there were a lot of lessons learned along the way. Hopefully, my lessons will save you some time if you are going the same route.

By the way, shout out to @alexshyba once again, for pointing me to the right places and saving me hours upon hours of time.

Break Tag Embedding

Even though Sitecore documented this as a resolved bug, I still experienced this issue. If there are new lines in a rich text or multi-line field, HTML break tags (<br>) get inserted. While it’s usually hard to notice this, we keep XML schema in multi-line text fields, so any extraneous characters and the schema is broken.

The good news is, I caught this earlier and documented a fix for it here:

Sitecore Query Performance

If v6.1 was forgiving with overly broad queries, v6.5 won’t be. It’s not out of spite or to teach you a lesson. I believe there was some security code added to the internal Sitecore query mechanism. There was a huge performance difference for me between the two versions – we are talking seconds, not milliseconds.

If you are on the same boat, you have 3 choices:

  1. Optimize your queries
  2. Consider using Fast Query instead of the traditional Sitecore Query mechanism (read my findings on it below before you do)
  3. If 1 and/or 2 do not work, I’d look into using Lucene search.

Fast Query

It doesn’t take long to sell Fast Query over the traditional Sitecore Query. When I was writing a product recommender type app that generated results based on submissions, I was sold immediately by Fast Query. The caveat with it, of course, is that, in addition to returning unordered list results, it also doesn’t guarantee to return them in the context language. This means that if you are on a US site and you do a Fast Query, you may get some items from other languages (if they are defined).

I’m not sure if it was luck or otherwise, but on v6.1, I’ve never encountered that. Results were always from the same language. When upgraded to v6.5, every other query had mixed results.

There are a couple of different ways to achieve this with the Sitecore API in C#, but you basically want to check for 2 conditions –

  1. Make sure the Sitecore Item’s Versions.Count property is greater than 0.
  2. On the Sitecore Item’s Language.FirstOrDefault() language, do a Database.GetItem() passing in the Item ID and the context language.

If you check StackOverflow, there is actually a pretty good code block that does both steps here:

Multi-Server Publishing & EventQueue

The staging module ends up being history in v6.3 and up, which is great news if you have ever had to set it up for more than 1 server – a lot of tedious configuration and painful investigation of logs if something went wrong. In v6.3 and up, all you have to do is set EnableEventQueues property to “true” in your web.config, and it publishes your items and clears the cache correctly whether you have 1 or n balanced web servers.

Web.config Consolidation

My original web.config was huge in size and had a lot of country and environment specific values. For example, my UK domain on staging was different from my UK domain on production. Both had to be specified in the <sites> section of the web.config. In addition to it being a pain to manage it from a size perspective, there was also the risk of it being overwritten by someone who didn’t know any better.

For Sitecore configuration, your App_Config directory includes an /Includes directory. What a catchy name, right? In here, you can extract your Sitecore configuration from the web.config and then just dump it here. Just make sure your file has a .config extension for it to get picked up. The IntoTheCore blog has a really good post on how to do this here: .

There is a neat way of seeing exactly what gets cooked up at runtime, as far as your Sitecore configuration goes. Try opening up http://[yoursite]/sitecore/admin/showconfig.aspx to get an XML dump of your Sitecore configuration.

Please note that a) this only includes your Sitecore configuration, as opposed to <system.web> or other non-Sitecore related configuration data, and b) you can’t include non-Sitecore configuration in the /Includes folder. You can extract modules from the web.config if they have an configSource or a similar property – which is what allows your DB strings to live in ConnectionStrings.config as opposed to the web.config file.

Testing/Deployment Strategy

So, you recompiled your code with the new version of Sitecore.Kernel.dll and your site renders. Great. I wouldn’t flip the switch so fast. Keep in mind that for us, the majority of the duration for this upgrade went to testing and fixing issues.

What I recommend is having a QA team or at least a second set of eyes perform the regression tests side-by-side – run a box with v6.5 and have them compare it to your production environment (which is running v6.1 or something older than v6.4).

I had my load-balanced web servers, so to simplify deployment, I just created new blank databases for v6.5, published the entire site to them, and changed my connection string. That way, the v6.1 DBs and configuration was still intact on production.

When the testing was completed, all I had to do was clone the webroot on the CD to all its load-balanced brethren and that was it – zero downtime. Because…

A little planning saves a lot of fan cleaning.

Additional Lessons

– In a perfect world, we’d be able to freeze the environment – both code and content – and be done with this in 1-2 weeks tops. But, because we don’t live in a perfect world, there were changes that were constantly happening. For managing the code, we created 2 branches – v6.1 code branch with the assemblies currently on production, in case we needed to fix live bugs, and a v6.5 code branch in case we needed new code development to start that couldn’t wait for us to go live with 6.5. Branching definitely worked out for us at the end.

– If your database is anything like ours – very big and multilingual, sometimes it’s better to start with a clean v6.5 install and port things over slowly, but confidently. I tried an in-place upgrade about a year go. That was only going up 2 versions, from v6.1 to v6.3. That blew up in my face because of web.config typos. It’s definitely easier to start clean and go from there.


I truly hope these lessons will help you in your upgrade ventures by preparing you for the “gotchas” that could stand in your way. At the end of the day, it’s definitely worth it knowing that a) you are not obsolete anymore and running the latest and greatest (for the time being), b) you open yourself up to a full library of shared source modules and new features that weren’t available in the older versions. My favorite one – Sitecore Azure. By the way, I blogged about that experience as well, in a series titled “To The Cloud” here: