Preparing for the upgrade to Episerver 10
Episerver's Update 134 release includes Episerver CMS 10, which in turn comes with quite a few breaking changes. Luckily, some of these breaking changes can be addressed before applying the actual Episerver 10 update.
Migrate your Episerver site to UTC
Episerver 10 is the first version to require dates to be stored as UTC in the database.
Saving DateTime properties as UTC is preferable for nearly all web applications, even those that do not involve users in multiple time zones. Not relying on a single time zone, which in turn must be in sync with the hosting environment, is a good way of avoiding a whole host of potential problems.
You can migrate existing Episerver 9 websites to UTC straight away, even if you're not ready to upgrade to Episerver 10 just yet.
Migrating Episerver to UTC through Visual Studio
There are multiple scenarios when migrating to UTC, all of which are described here, but in this case we'll look at a common scenario where we migrate through Visual Studio and the website is running in the same time zone as the computer running Visual Studio.
Our website is running in Azure, which by default is running UTC. However, since we have set the WEBSITE_TIME_ZONE app setting to W. Europe Standard Time, our Azure web app is in fact running in that specific time zone:
A quick way to figure out which time zone Windows is in, is to run the systeminfo command and pipe it to easily locate the time zone information:
In our case, we see that our local OS is in fact in the same time zone as the website, so we don't have to specify any time zone arguments when migrating.
To start the migration, we open the Package Manager Console and run Convert‑EPiDatabaseToUtc:
You'll notice you get no feedback (unless something went wrong):
The migration was completed in under a minute for our website, but for larger websites the process can be quite lengthy (half an hour or more).
The migration script can be executed against a running site (although a site restart is required afterwards), but it might affect performance and times will be off during the migration.
Verify it works as expected
To see this in action, let's create a new page in Episerver:
Looking at the time stamps for our new page, we see it says 5:47 PM:
Looking at the clock in Windows, we see this matches our local time, although displayed in a 24-hour format:
However, as we are in a time zone which is UTC+1, the actual times stored in the database should be one hour off. This can easily be verified in the tblWorkContent table (1720 is the ID of the page we just created):
Another option is to execute the stored procedure GetDateTimeKind, which returns 2 if the UTC migration script has been applied:
Migrating a production environment to UTC
I won't get into details about how you should make sure you have a database backup before proceeding, but make sure you do.
The cmdlet we used through the Package Manager Console is available as a PowerShell module which ships with the EPiServer.Framework NuGet package.
First, you need to use Import-Module in PowerShell to load the module from the tools folder of the NuGet package. If you run it with the -Verbose argument (optional) you can see what is actually imported:
Next, simply execute ConvertEPiDatabaseToUtc and enter the database connection string when prompted:
Although you have the same options as with the cmdlet, if you run this PowerShell command on a production web server you won't have to worry about different time zones.
Upgrade NuGet packages to Episerver 10
Once you have applied the UTC migration script, you may proceed to upgrade the NuGet packages to Episerver 10:
Depending on which add-ons or third-party packages your site relies on, you might encounter packages that do not yet support Episerver 10. In our case, one such example was the PowerSlice add-on, which at the time of writing was not available for Episerver 10.
Since that particular add-on wasn't critical for our website, we simply removed it (commenting out any code referencing it) and then proceeded with the package upgrades.
Rebuild your project
Once all NuGet packages are upgraded, we rebuild our project and work out the compilation errors we encounter.
Internal namespaces
Depending on your site implementation, you might notice that several classes have moved to internal namespaces.
One example from our site was a custom thumbnail generator which uses ImageResizer to produce thumbnails for the Episerver UI:
After the upgrade, we noticed the ThumbnailManager class no longer resided in the EPiServer.Core namespace, but rather a namespace called EPiServer.Core.Internal.
You can read more about the rationale behind these API changes in Henrik Nyström's post.
Obsolete classes
You'll probably notice that several classes have been marked as obsolete, luckily with quite helpful descriptions in most cases:
Dates are nullable
You will notice that dates are now nullable. In our case the following example from a Razor view failed:
We resolved it by simply adding the null-conditional operator introduced in C# 6:
Dot notation no longer supported in Dojo
If you have custom Dojo widgets, you'll need to ensure they're no longer using the old dot notation, and instead adhere to standard AMD syntax.
For example, we had a UI descriptor which replaced the native image selector with a custom one:
In order for it to start working, we had to modify the editor descriptor like so:
This also applies to module.config and Dojo JavaScript files. More information available in these release notes and Ben McKernan's blog post.
Additional considerations when upgrading to Episerver 10
This blog post is far from exhaustive when it comes to the (breaking) changes introduced by Episerver 10. Make sure to go through the official documentation, and ensure add-ons required by your site support Episerver 10 before proceeding with the upgrade.