Experience Sitecore !

More than 300 articles about the best DXP by Martin Miles

Updating Sitecore 9 with Helix to 9.0 update 1 (rev. 171219)

19 January 2018martin(0)

I am currently developing a greenfield Helix-based solution on Sitecore 9. That is a challenging but thrilling path, resulting in nicely setup working platform with "one-click install + one click deploy" process, perfectly suitable for continuous integration. 

However, as soon as 9.0 update 1 has been released, I started anticipating upgrading my solution to that revision, but for a week or so we've been missing NuGet packages for the latest version. Since January 18-th they have been released so finally it became possible to update the solution. Below there are few things I have done to make it work.

Phase 1. Choosing an update approach to take. 

There are few options:

  • *.update file with actual version
  • upgrade zip archive with only changes + pdf guidance on how to update
  • SIF archive with CMS, xConnect and corresponding configuration *.json files

For sanity purposes, I prefer to fully uninstall the previous version and reinstall the updated afterwards, rather than overwrite things. Thanks to a flexibility of Helix, now developer should not worry about losing an existing state, as soon as everything is checked into a version control system - gulp script will pick the latest changes and do that job for us. That's why approach number 3 becomes a choice. 

As I am keeping web folder under source control (just clean install of each version in order to easily restore that state) it makes sense to move .git folder outside from web folder before we go with uninstall, as it obviously will remove entire web folder. After as we remove the previous version, and newer version settles there, one can return .git folder back and immediately benefit from seeing the difference between two versions. I will cover that below during stage 2. So, to uninstall, open PowerShell and do:

.\uninstall-xp0.ps1

Once complete, got to the next phase.

Phase 2. Preparing and installing new version

First of all, download Sitecore 9.0 Update 1 XPSingle from SDN download page. Since we're doing that for our development environment, make sure you get OnPrem edition, rather than Cloud.

Obviously, to install newer version one need to update Sitecore Install Framework that supports particular version. Luckily, Sitecore Installer knows everything it should regarding how to install the version. PowerShell (with admin rights):

Update-Module SitecoreInstallFramework

If for some reason it breaks with execution policy exception, modify current user appropriate permissions:

Set-ExecutionPolicy Unrestricted -Scope CurrentUser -Force

Copy Sitecore packages for both CMS and Xconnet into build/assets folder, along with previous version packages. In my case, these files:

Sitecore 9.0.1 rev. 171219 (OnPrem)_single.scwdp.zip and Sitecore 9.0.1 rev. 171219 (OnPrem)_xp0xconnect.scwdp.zip

and also replace *.json scripts from XP0 Configuration files 9.0.1 rev. 171219.zip

Then, quite important, update version details at settings.ps1 script:

$SitecoreVersion = "9.0.1 rev. 171219"
$InstallerVersion = "1.1.0"
Finally, run the installer:
install-xp0.ps1
and wait till it finishes. Warning: do not open Sitecore after it installs.

Phase 3. Saving clean state of web folder with new version
Previously, I have described an approach of restoring a newly installed and previously never run Sitecore from a dedicated git branch, called SitecoreFiles_CM. During this exercise given approach saved me plenty of efforts, as I had to restore initial state of web folder at least 20 -25 times, if not more. That's why, even before I first run Sitecore and it generates plenty of artefacts (logs, caches, etc.) - I do one another commit with a new version of webs folder on top of existing clean install of 9.0 (initial). As a bonus, I get a wonderful tool for identifying changes between clean install of both versions, including config changes, file structure, built-in apps and similar.

Phase 4. Update the solution
Open Visual Studio, but do not deploy as you need to update your solution with all the latest package version. A goal of that phase its to make sure that any of DLLs being published to webroot by gulp script will match existing version of their counterparty within /bin folder of webroot. Sitecore comes with 337 DLLs from the box, and one would probably need to write a decent automation tool to do matching. Again, thanks to SitecoreFiles_CM approach for simplifying my life, as git commit immediately shows all the DLLs that differ from those checked in as a part of 9.0.1 clean install commit. 
As the first step, I went and changed all Sitecore.*.NoReference libraries for each project so they all correspond to 171219 revision. Keep in mind, that some of Sitecore NuGet libraries are versioned differently and do not have revision number in their name.
Changing references in such a large solution taking much efforts, attention and time. That's why I recommend you to do quite often commits while updating your solution, as you'll likely to restore one or few times during that process. Finishing with Sitecore.* references is a good time to check the code.
Then, I went updating Glass Mapper, Unicorn, Unit tests, code generation libraries and the rest of third-party packages. Below there is a list the version I used that are compatible and function:
Autofixture 3.51.0
BuildWebCompiler 1.11.375
EnterpriseLibrary.* 6.0.1304
FluentAssertions 4.19.4
GlassMapper 4.5.0.4
HtmlAgilityPack 1.4.9.5
Kamsar.WebConsole 2.0.0
Lucene.Net 3.0.3
MicroCHAP 1.2.2.2
Moq 4.8.1
Mvp.Xml 2.3.0
netDumbster 2.0.0.1
Newtonsoft.Json 9.0.1
NSubstitute 3.1.0
Rainbow.* 2.0.0
SharpZipLib 0.86.0
Sitecore.FakeDb.* 1.7.2
Unicorn.* 4.0.3
xunit 2.3.1
Lastly, it is a good time to update System.* and Microsoft.* assemblies. 

One thing to mention is that you still need to keep several assemblies at non-final versions and do not update it to the latest, as they will break dependencies. These are listed below along with correct versions: 
Microsoft.Extensions.DependencyInjection 1.0.0 
System.Reflection 4.1.0
Newtonsoft.Json 9.0.1
HtmlAgilityPack 1.4.9.5
System.Net.Http 4.0.0
Castle.Core 3.3.3
It took inadequate time to troubleshoot some of those mentioned above, thanks to git in both solution and web folder it became easier to try-test-restore the state.

Finally, it all looks great. Everything works perfect, including generation works, unit tests, Glass Mapper, Unicorn etc.  And few bonuses, of course.

Bonus 1: as soon as I merge this feature branch with updated solution into develop branch of our GitFlow repository, other developers will get the update semi-automatically - with next re-install after refreshing /build/assets folder.

Bonus 2: just nearly forgot to mention: as the reward for an update efforts, I have got an EXM module as part of the platform, yes - now since 9.0 update 1 it comes out of the box!