Links

Optimizely CMS stores internal links in a permanent format. Renaming files, templates, or host names does not affect links, ensuring content references remain valid throughout the lifecycle of a site.

Content

Permanent link references ensure links remain valid even when content moves or URLs change.

CMS stores permanent link references instead of HTML links. Accessing a reference through a property resolves it to an HTML link in the content. Saving the content parses the HTML and stores a permanent link.

📘

Note

Paste a permanent URL into a web browser for debugging.

CMS preserves additional URL segments and query parameters during permanent link conversion. This includes segments after the content-specifying part of the URL. Link to a specific controller action with parameters or content routed by a partial router. A registered route must match the URL.

Built-in properties

Built-in property types handle permanent link storage and resolution automatically.

The Url type (corresponding to PropertyUrl and PropertyImageUrl), XHtmlString (corresponding to PropertyXhtmlString), and LinkItemCollection (corresponding to PropertyLinkItemCollection) support permanent links. The basic string type (corresponding to PropertyString or PropertyLongString) does not support permanent links because it may contain formats other than HTML. Use XhtmlString for HTML content to enable permanent links.

Track link integrity

Link integrity tracking identifies which content items reference each other, preventing broken links.

Saving a content instance triggers CMS to parse properties (PropertyUrl, PropertyXhtmlString, PropertyLinkItemCollection, and PropertyContentArea) for links to other content or files. CMS stores these references in a table that tracks which items link to each other.

Export and import

The permanent link format ensures content references survive export and import operations.

The export package stores links in permanent format when transferring content. Links within the package are preserved during import. For custom properties not based on the built-in link types, handle the conversion during export or import.

API references

The permanent link API provides programmatic access to link resolution and mapping.

Implement the EPiServer.Core.Transfer.IReferenceMap interface on a PropertyData object to signal that the property handles permanent links. The PermanentLinkMapper converts between permanent links and dynamic links. The EPiServer.Web.PermanentLinkUtility class provides the primary API access point. The EPiServer.Web.IPermanentLinkMapper and EPiServer.Web.PermanentLinkMap classes are underlying components in the permanent link architecture and do not typically require direct access.

Content links references

Content link GUIDs provide stable identifiers that persist across environments and deployments.

Permanent links to content consist of the GUID associated with content, also available as the IContent.ContentGuid property.

Definition – ~/link/ContentGUID.extension?EXTRAINFO.