Upgrading your site and add-ons to EPiServer CMS 8

As a few already have noticed, we have released pre-release packages of EPiServer CMS 8 in our Nuget feed. Given that EPiServer started to use a continous release process about a year ago and is now following semantic versioning, I want to explain a bit more what this actually means. First of all, if you have not already done so, I recommend reading Per Ivanssons article about the continous release process. A major version, according to semantic versioning, means "MAJOR version when you make incompatible API changes". Given that EPiServer has done weekly releases for around a year now, this means that there are not that many changes in EPiServer CMS 8 compared to earlier major versions (and even compared to EPiServer CMS 7.5). There are a few breaking changes but most of these will have no or little impact on most sites. There will be more blog posts and articles about what is new and what has changed in EPiServer CMS 8, but for this blog I'll focus on how a site with add-ons can be upgraded.

Setting up a site for upgrade testing

As we are focusing on how the add-on upgrade process works, I'll start by installing a new site with the Visual Studio extension. I'm seleting an Alloy MVC site without search to keep it simple. To mimic a site that's been upgraded to a recent version of EPiServer CMS 7.X, I will start with upgrading to the latest packages for EPiServer CMS 7, so I'm upgrading the packages to the latest stable versions which currently is EPiServer CMS 7.x since the 8.x packages are still pre-release. After I've updated the packages I compile the solution and run the "update-epidatabase" command in the package manager console to run the database upgrade scripts. Now the site is up and running with the latest EPiServer 7.x packages.

Installing add-ons

Since we are focusing on how the add-on process works in this blog, I'll install a few add-ons. As I hope all of you are aware of, we did some quite large improvements regarding how add-ons can be managed in the end of last year (http://world.episerver.com/articles/Items/2-important-improvements-for-managing-addons-in-episerver/). The biggest change was that we introduced support to install and manage add-ons as regular Nuget packages using Visual Studio. To enable this, we converted all add-ons to standard Nuget format. Depending on how you have installed your add-ons, there are two upgrade paths for your add-ons to EPiServer CMS. In this scenario, we'll test both by installing both some add-ons through the UI as well as some through Visual Studio and the EPiServer Nuget feed. I install the Tiny MCE spellchecker and Google Analytics add-ons through the UI and the EPiServer Social and EPiServer Language Manager add-on through Visual Studio. When I start the site I can see the diffrent add-ons and when I look into the modules/_protected folder of my web site I see the following:

Note: We do not recommend that you mix add-ons installed from Visual Studio with add-ons installed through the UI. You can control how add-ons should be managed through configuration that is described in the SDK.

Doing the upgrade

Now we are ready to do the actual upgrade. Given that the EPiServer CMS 8 packages are currently still pre-release, we switch Visual Studio to include pre-release packages and upgrade all packages from the EPiServer Nuget feed.

As with the previous update, I have to compile and run the "update-epidatabase" command in the Package Manager Console. Now lets start the site and see what happens:

It seems like there has been a breaking change that affects at least one of the add-ons. Actually, this is a kind of special case related to pre-release packages. Social Reach was installed as a Nuget package and if we look at the package, it says that it support up to, but not including EPiServer.CMS.Core 8. A pre-release package is actually treated as a very high version of the previous major version and that's why we were able to upgrade the core packages even though we had add-ons installed that does not support EPiServer CMS 8.

Upgrading the add-ons installed as Nuget packages

Normally, if the add-ons had had newer versions in the EPiServer Nuget feed, these would have been updated when we did the update all. Currently this is not the case. However, there is a new Nuget feed that is actually used by the EPiServer add-on UI in EPiServer CMS 8 that already hold some EPiServer CMS 8 compatible versions of some of the add-ons. The main purpose of this feed is to have a dedicated feed for certified add-ons that the EPiServer UI can use. This also means that the default format of certified add-ons will be the regular Nuget format (the old format is still valid for some time forward if you have custom addons). All packages should also be available in the regular EPiServer Nuget feed at the time of release, but for now, lets add this feed to Visual Studio to be able to upgrade some of the packages (https://nugetaddons.episerver.com/feed/addons.svc/).

Now we can update the add-ons that we installed previously from this feed. As usuall, I recompile after adding the packages and then I start the site again. Woohoo, the site is up and running again:

Now we have the following situation:

• The core packages for the site is on EPiServer CMS 8.
• We have two add-ons that have been installed through Visual Studio and upgraded to versions that support EPiServer CMS 8.
• We have two add-ons that were installed with EPiServer CMS 7.5+ that seems to still be working after the upgrade.

But what if we installed Social Reach, or another add-on that are affected by a breaking change and needs to be upgraded, manually? Since these are not part of the Nuget dependency chain in Visual Studio they will not prevent an upgrade but instead, the site will crash after upgrade. There are two ways forward here.

Managing add-ons as Nuget packages

Our understanding is that most developers wants to control the add-ons installed on a site as Nuget packages. This has several advantages, for instance:

• It makes the add-ons included in the dependency management for Nuget packages so that you see when there are updated package in Visual Studio as well as preventing upgrades of packages that the add-ons are not compatible with.
• You easilly manage all your environments, including development, test, staging and production the same way as with the rest of the site functionality.

Since we know that there are a lot of sites out there where add-ons have been installed through the UI (though they are still probably managed as resources in your source control), we wanted to provide a real easy way to replace existing manually installed add-ons with their Nuget equivivalents. The solution for this is a new powershell command that you can run in the Package Manager Console named "convert-epiaddons". Lets run this on our web site and see what happens:

It seems that the two add-ons that were manually installed were converted to Nuget add-ons. If we check the modules/_protected folder we can now see that the two add-ons are included in the project with the new format. If you compare with what was previously installed you can see that there are less files included compared to the previous manually installed version of the add-on. The reason for this is that add-ons delivered as Nuget packages normally have most of the add-on files placed inside a zip file (if you want to read more about this I recommend Henrik Nyströms blog post). Another thing to be aware of is that any configuration file inside the add-ons, for instance containing settings for the add-ons, are left intact and untouched so you don't have to redefine the settings.

Managing add-ons as UI add-ons

So, what happens if you want to upgrade a site without having to convert the add-ons to Nuget dependencies? This is still possible and we have done some improvements to conver this scenario as well. Let's install another site with the Social Reach add-on installed through the UI and upgrade it to the latest pre-release and then start the site to see what happens:

Even though the site still crashes, we get a detailed error message along with a description on how to disable the add-ons that's failing. We follow this and replace the existing scanAssembly section (I noticed that there is an attribute, forceBinFolderScan="true", that's not part of the error message but from what I understand, we can ignore this). We start the site again and now it works. Under the updates section of the add-ons UI we can now see that there is an update for Social Reach so we update it and then revert the configuration changes back so that the Social Reach add-on should be loaded once again. Now the site is working again and the Social Reach module is loaded.

Summary

• If you already have the add-ons installed as Nuget packages or if you run the "convert-epiaddons" command to convert manually installed add-ons, the upgrade should be like a walk in the park.
• The "convert-epiaddons" task will only convert add-ons that are manually installed and available in the add-ons Nuget feed. Other add-ons will be ignored.
• If you have add-ons in EPiServer CMS 7.x that are already installed as Nuget package, you can just upgrade them as regular Nuget packages at the same time as the EPiServer CMS core packages. Most verified add-ons will be available in the regular EPiServer Nuget feed at the time we release EPiServer CMS 8.
• It's possible to upgrade and maintain add-ons that are installed as UI add-ons, though it requires a few more steps (unless you only have add-ons that are not affected by breaking changes. In that case, nothing additional is required).
• Notice that I did not have to change a single line of code for the Alloy MVC project after I upgraded to EPiServer CMS 8! Depending on what API:s you are using for your web site, that might not be the case but in general, none or very few changes will be required for most upgrades.
• Some blog posts are already out there about new functionality in EPiServer CMS 8, like improved allowed types and typed tabs/groups. More blog posts and articles will come and of course, we will also post release information including a summary of new/changed functionality and breaking changes.

Some interesting details that I learned while testing some upgrades

• Installing an add-on as a Nuget package in Visual Studio adds a reference to the assemblies in the package folder. You need to compile to copy the assembly to the bin folder of the site.
• This means that only assemblies installed through add-ons in the UI ends up in the modulesbin folder while add-ons installed as Nuget packages get their assemblies in the bin folder.
• I noticed a special case when upgrading the Live Monitor and Content Collaboration add-ons. The assemblies for these add-ons was not copied to the bin folder. When investigating this some more I saw that running the Clean Solution command in Visual Studio removed all assemblies except of the previously installed assemblies for these add-ons. After some more investigation I discovered that the cause of this was that these assemblies was compiled with .NET 4.5.1 while my current project was configured to run 4.5. Changing the target framework and recompiling solved this. This seems to be a Visual Studio issue/feature that's not just related to add-ons but Nuget packages in general. (If you want to see this for yourself, try changing target framework without recompiling and then run Clean Solution. The assemblies are still in the bin folder until you recompile them...)