Experiences from migrating to EPiServer 4.61 and ASP.NET 2.0!

This article is targeted to upgrading a pre 4.60 EPiServer installation on ASP.NET 1.1 to 4.6X on ASP.NET 2.0.  I will assume you have a VS 2005 installation with support for Visual Studio 2005 Web Application Projects. The project used for discussing our experiences is a Multilanguage project that did not use the Multilanguage Runtime library explicitly and therefore did not require any code changes to support the new Globalization.  

As the upgrading process is a multiple step process where you will upgrade several products to newer versions (EPiServer, Visual studio, ASP.NET) it is important to keep note of what versions you are working with. I have also been particularly careful with taking backups between at least every step on the way, so in case of a failure, I only needed to go back 1 step instead of redoing the whole process.

EPiServer 4.6X and ASP.NET Framework

As clearly stated in the release papers for 4.61 there are two versions available, one for the .net 1.1 framework and one for the 2.0 framework. The differences are support for webparts through the EPiServer.WebParts.dll and the actual templates (aspx pages) that are included. The code behind and episerver.dll are still using 1.1 classes but tested against the 2.0 version.

For the purpose of this article I will distinguish between:

• versions of EPiServer,
• versions of your Visual studio project (2003 or 2005)
• versions of your site (web site or web application) 
• versions of the ASP.NET framework (1.1 or 2.0)
• versions of the EPiServer templates
     1. templates based on ASP.NET 1.1, used by EPiServer 4.51 and 4.60
     2. templates based on ASP.NET 2.0, used by EPiServer 4.60 and 4.61 

Upgrading EPiServer to 4.6X

This part is well documented at EPiServer.com and is a fairly common upgrade that is fully supported by the EPiServer manager. Scripts and extra documentation are available from Support when converting Multilanguage pages (Multilanguage site in 4.51) to the new globalization. Just follow the instructions. After this you can test run your 4.61 site. See also issue one under the section “Problems”!

For the rest of this article I assume the standard EPiServer upgrade was successful, and that you are now running EPiServer 4.61 on ASP.NET 1.1 with 1.1 templates in Visual Studio 2003.

Migrating a Visual studio 2003 project to Visual studio 2005

This part is not documented by EPiServer. There is however documentation available from Microsoft http://msdn.microsoft.com/vstudio/default.aspx?pull=/library/en-us/dnvs05/html/WAP.asp#wapp_topic12.

This is a major change so make sure to backup your project and database before continuing. I also choose to do the migration outside of our source control due to performance issues and to avoid problems when the upgrade wizard changes files.

After upgrading the templates (next step) I reconnected our source control and checked in all changes. The Microsoft link above describes seven steps for migrating to Visual studio 2005, and I followed these… exactly!  Before you do the actual conversion please have a look at AutoEventWireup handling in VS 2005 (next paragraph). These steps include the conversion from the “web site project format” to the “web application project format”. Do not forget to change/check the ASP.NET version of your website in the IIS Manager after you are done.

You are now running EPiServer 4.61 on ASP.NET 2.0 with 1.1 templates in Visual Studio 2005 and you are using the “Web Application Projects” Project format

Event Wire up changes with migration to WAP

It is important to note that the migration to WAP changed the AutoEventWireup setting from “false” to “true” on all Pages and UserControls. It also removed all explicit event hooks in the InitializeComponent method. Note that this only applies to “Page” event handlers. I only discovered this after migrating and was not really happy with the decision being taken for me. You might want to decide up front if you wish to adapt the “magic” eventwireup way (AutoEventWireup=”true”) or the manual way (AutoEventWireup=”false”, just like you did in VS 2003). There are many arguments for and against each approach (performance, compile time checking, error prone etc) and it depends on how you where doing event handling previously. If you decide to have AutoEventWireup=”false” you will have to partly reverse the conversion process (copy back your manual event hooks). You would also want to change your default page template to set AutoEventWireup=”false”.

Upgrading your custom templates to ASP.NET 2.0 Templates

This part is not extensively documented by EPiServer. They do supply templates for both the 1.1 and 2.0 framework. But since most of us heavily customize these templates it is not an option to replace them with their 2.0 versions. The approach taken here is to compare the supplied 1.1 templates with the 2.0 versions. The differences between these indicate the changes required for upgrading our 1.1 based custom templates to ASP.NET 2.0. Initially this seems to be a fairly large task to accomplish but a closer review revealed that the only change required is to change EPiServer Region/Content support to ASP.NET master Pages Concept. Since these two are fairly similar the conversion only requires changes in Template files (*.aspx). An example illustrates this:

4.51 Template

<%@ Page language="c#" Codebehind="ChangedPages.aspx.cs" AutoEventWireup="false" Inherits="development.Templates.ChangedPages" %>

...

<development:DefaultFramework ID="defaultframework" runat="server">

            <EPiServer:Content Region="addRegion" runat="server">

              ...        

            </EPiServer:Content>

</development:DefaultFramework>

<development:DefaultFramework ID="otherframework" runat="server">

              ...        

</development:DefaultFramework>

---

4.60 Template

<%@ Page language="c#" Inherits="EPiServerSample.Templates.ChangedPages" MasterPageFile="~/templates/MasterPages/MasterPage.master" Codebehind="ChangedPages.aspx.cs" %>

...

<asp:Content ContentPlaceHolderID="AddRegion" runat="server">

...

</asp:Content>

---

Thus the required changes for aspx templates are

1. Add the masterPagefile attribute,
2. Remove the <development:DefaultFramework ID="defaultframework"> but leave everything between the tags,
3. Remove all non default frameworks from your template and remove everything between these tags,
4. Change ““EPiServer:Content Region” to “asp:Content ContentPlaceHolderID”.
   Of course we need to change our defaultframework.ascx to become a master page. Here too the changes are usually small.

The required changes for ascx framework pages are:

1. Change file type to *.master and add required directives <%@ Master …  ( I also choose to change class name and namespace),
2. Change  “EPiServer:Region” to “asp:ContentPlaceHolder”- If you are careful with retaining the original ID’s on both EPiServer:Region and EPiServer:content tags no additional changes are required.

You are now running EPiServer 4.61 on ASP.NET 2.0 with 2.0 templates in Visual Studio 2005 and you are using the “Web Application Projects” Project format.

Supporting Multiple Master Pages

Support for changing the master page (you will need this if you have previously been using EPiServers DynamicContentFrameworkSelector) is supported by the Page.MasterPageFile Property in the System.Web.UI namespace (I included a code snippet demonstrating a CustomTemplate class). Making all your templates inherit from this class instead of EPiServer.TemplatePage will give you the ability to switch master class based on the dynamic property “isWidePage”. You can easily adapt this to more advanced scenarios for dynamic MasterPage selection.

public class CustomTemplatePage:TemplatePage

{

void Page_PreInit(Object sender, EventArgs e)

        {

            string _selectFramework =null;

            PageReference pageLink = PageReference.Parse(HttpContext.Current.Request.QueryString["id"]);

            if (pageLink == PageReference.EmptyReference)

                    pageLink = PageReference.Parse(HttpContext.Current.Request.QueryString["parent"]);

            PageData page = Global.EPDataFactory.GetPage(pageLink, EPiServer.Security.AccessControlList.NoAccess);

           

     //Check property and set framework

            if (page.Property.Exists("isWidePage") && !page.Property["isWidePage"].IsNull)

                    _selectFramework = "MasterPages/WideMasterPage.master";

            if (_selectFramework != null) this.MasterPageFile = _selectFramework;
        }
}

Problems

After upgrading, our SQL server database started consuming 100% CPU time which could be traced to be originating from to the EPiServer scheduler.  After contact with the support I was recommended to clear the tblScheduledItemLog table since the scheduler tries to minimize the total entries to 100. Deleting our > 100.000 entries manually resolved this.

After upgrading and enabling Globalization support and setting the default language to Swedish we discovered that all pages where published in a language called “Default” with language code “EN”. This was easily solved by editing the language properties of “Manage Web Site Languages”. We did however end up with 2 languages with language code SV (2 different MasterLanguageBranches in the new Globalization terminology). One was used by pages that originally where not Multilingual in 4.51 and one used by Multilingual pages in 4.51 that where published in “SV”. After some discussion with support I received a Beta version for a conversion tool to change the language for a whole part of the content tree.

 

Comments