Preparing for EPiServer CMS 5 R1

Going from EPiServer 4.x to EPiServer 5 is not an upgrade. The API is not 100% backwards compatible, and you also have to move from .NET 1.x/2.x to 3.0, which will break a few things in your EPiServer application. This article focuses on how to prepare for EPiServer CMS 5 when developing an EPiServer 4.x project.

Contents

• Introduction
• Minimizing Migration Impact
• Upgrade to 4.62B
• Rewrite to use ASP.NET 2.0
• Verify 3rd Party Modules and Add-ins
• Breaking Changes

Minimizing Migration Impact

If you’re developing your project in EPiServer 4.x today and plan to migrate to EPiServer CMS 5 there are a few things you should think of while developing, and you can prepare today to minimize the impact of migration tomorrow.

Upgrade to 4.62B

There are plans to ship tools for helping you migrate data, but they will primarily be tested and verified against version 4.62B (or later). If your web site is using an older version of EPiServer you might have to fix some compilation errors during an upgrade to 4.62B - due to discontinued parts of the API (depending on how old your version is).

Also, if you are using the pre 4.6x version of the Globalization feature in EPiServer you need to migrate this to support the new MultiLanguage implementation.

Rewrite to Use ASP.NET 2.0

You should upgrade your ASP.NET project to use ASP.NET 2.0 (3.5), and rewrite your application to use Masterpages instead of the ContentFramework (part of EPiServer.) This also means you’ll have to upgrade your Visual Studio project to Visual Studio 2005 SP1.

See the TechNews article Experiences from migrating to EPiServer 4.61 and ASP.NET 2.0 for more information.

Verify 3rd Party Modules and Add-ins

Make sure any 3rd party modules and add-ins are merged, tested and verified to run on EPiServer CMS 5. Remember both free and commercial modules you might be using on your site.

Breaking Changes

ASP.NET 1.1

You need to upgrade to .NET 3.5 as EPiServer uses Windows Workflow Foundation which is part of version 3.5 of the framework.

SQL Server 7

If you’re running on SQL Server 7, you need to upgrade to SQL Server 2005 or newer.

Windows 2000

Windows 2000 Server will not be supported, which means you will have to upgrade to Windows 2003 Server (SP2 or newer) for hosting EPiServer CMS 5.

EPiServer 3

If you’re running in a mixed environment with EPiServer 3 and 4 on the same physical web site, the time has come to upgrade. The feature for updating and synchronizing data and settings between the sites has been discontinued in EPiServer CMS 5.

LDAP

With the new Membership and Role provider model for authentication and authorization the LDAP authentication module has been discontinued.

Custom Property Types

The new property system has had a major facelift, and the API is not backwards compatible. You will have to rewrite your custom property types. The new property system does not remove any of the existing features you use, but they have to be utilized in a different way in EPiServer CMS 5.

See Developer's Guide > Web Controls > Property Types in the SDK documentation.

SIDS

Security IDentifierS (SIDS), uniquely identifying users and groups have been replaced by the ASP.NET membership, role and personalization provider model. The configurable authentication chain has been replaced by the membership and role configuration sections in web.config.

• Wrap all access to user data manipulation in a few methods or classes that can easily be replaced when moving to EPiServer CMS 5.
• Page.User will give you information about the current user
• EPiServer.Security.UnifiedPrincipal is obsolete, and should not be used
• PageBase.CurrentUser is gone. Use Page.User

Examples:

Before:

Now:

Personalized Data

Due to the move to the provider model in ASP.NET 2.0 and later, the PersonalizedData feature in EPiServer has been replaced with the standard ASP.NET Personalization provider. EPiServer CMS 5 ships with a provider that can store the same metadata about users that EPiServer 4.x can. 

The PersonalizedData class is obsolete.

Forms

The old Forms support has been dropped, all forms need to be XForms. You will have to move all your pre-XForm forms over to XForms before moving towards EPiServer CMS 5. When you have upgraded to EPiServer 4.61 you can convert these forms using the forms conversion tool in Admin mode.

Security

Because of new caching/paging features GetChildren will not return a security filtered PageData collection (the controls will though). If you want it to be filtered you need to do this yourself:

Configuration

All EPiServer settings previously stored as appSettings are now moved into a separate config section. The EPiServer.Global.EPConfig static member is gone. The configuration settings are accessible through the new EPiServer.Configuration assembly:

Example:

See the How To - How To Read site Settings Programmatically, in the SDK Documentation. 

See also Configuration in EPiServer CMS 5 R1.

Moving the settings out of the appSettings section allows for better intellisense when editing web.config and also syntax checking in Visual Studio and strongly typed properties when working with this data from code.

The automagic conversion based on appSettings key prefixes is now gone.  This code:

does not work. The new way to do this is:

You will also have to convert the values instead of using the built-in auto conversion from 4.6x:

To minimize migration impact you should start using the ConfigurationManager today (requires ASP.NET 2.0).

PageData Cache

PageData objects are now stored as read-only objects in the cache. This means that when you do a GetPage(…) to load a page, it will be retrieved from the database (only the first access to the page), marked as read-only and added to the cache.

In EPiServer 4.x you could change a page after you had got hold of a PageData object and the altered data would be rendered. This could be done because each access to a page in the cache would actually make a copy of the page. In EPiServer CMS the cache consists of read-only objects to ensure performance, and you will not get a copy when you do GetPage(...). If you need to change the PageData after retrieving it from the cache you need to ask for a writeable clone.

See Also

• Read-Only PageData Cache in the SDK
• PageData.CreateWritableClone Method in the SDK

Comments