Link Management in EPiServer CMS 5 R1 Under the Hood

Background Story

Content in EPiServer 4 is stored as HTML in the database, similar to what you see in the editor with some server-side tweaks to correct formatting. To visualize the concept we will look at a simple HTML sample that you may find stored in EPiServer 4:

If you installed EPiServer in a virtual directory named EPiServerSample, you would get this HTML:

There are some built-in limitations in this approach caused by static HTML being stored in a database pointing to live or dynamic content that may be subject to change. EPiServer 4 has support to fix HTML on export/import by automatically rewriting the link path, but not if you rename a file or a template, or even move a site from one virtual directory to another.

Links in EPiServer CMS 5

Introduction

You can rename files and templates without affecting the links; you can even move an EPiServer site from a virtual directory to a root site without breaking a single link. The reason is a clever way of saving semi-static content in the database.

Content

Links in EPiServer CMS 5 are not stored in the HTML at all, instead we store references called Permanent Links that later on will be resolved to a link.

The same HTML as in Fig 1 or Fig 2 in EPiServer CMS 5:

And when accessed through a property these references are resolved to the actual link so when you view the content you will find the same HTML you are used to in EPiServer:

And again, when you save the content the property will parse the HTML and store Permanent Links instead. The permanent URLs actually work as normal links if you paste them into a browser for debugging purposes.

Built-in Properties

The built-in properties such as PropertyImageUrl all support permanent links by inheriting from PropertUrlReference. Be aware though that the basic ProperyString/PropertyLongString doesn’t support permanent links because it may contain other formats than HTML. Be sure to use the PropertyXhtmlString for all HTML content to make use of permanent links.

Web Services and RawPage/RawProperty

The EPiServer.Core.RawPage/RawProperty classes used primarily by Web services and mirroring/export/import only exposes the permanent links, if you need to use any other links you have to handle the conversion between the Page object to the RawPage object yourself or add post-processing.

Page Soft-links

Page soft-links are actually links in HTML indexed together with search engine indexing, these are not affected by the internal Permanent Links and will store the actual links. The soft-links API is accessible from EPiServer.DataAbstraction.SoftLink.

Reference

API

The interface EPiServer.Core.Transfer.IReferenceMap on your PropertyData object tells EPiServer that we need to handle Permanent Links.

The Permanent Link Store handles all conversion between permanent links and dynamic links. This API can be accessed using the EPiServer.Web.PerformanentLinkUtility.

EPiServer.Web.PermanentLinkMapStore and EPiServer.Web.PermanentLinkMap are underlying components in the PermanentLink architecture and under normal circumstances you do not need to access them directly.

Page Links

Permanent links to pages consists of the GUID associated with a page, also available as the property PageGUID.

Definition:

~/link/PAGEGUID.extension?EXTRAINFO

File Links

Permanent links to files are handled similar to pages but with one significant difference. Because files are stored on disk it’s up the each Virtual Path Provider (for further reference on Virtual Path Providers in EPiServer, please see Developers Guide/Virtual Path Providers in the EPiServer SDK) to associate a GUID with a file. The default provider for files in EPiServer uses a technology where helper files and folders are created and after which it stores this metadata when linking to a file. This means that you should never rename files and folders using Windows Explorer (but you may upload new files).

Definition:

~/link/FILEGUID.extension

Comments