HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityDoc feedbackLog In
GitHubNuGetDev CommunityDoc feedback

In Optimizely Content Management System (CMS), internal links are stored in an internal permanent format meaning you can rename files and templates, change host names without affecting the links.

### Content

CMS does not store links in HTML, but instead stores permanent link references. When you access a reference through a property, CMS resolves the reference to an actual link so you see an HTML link in the content. When you save the content, the property parses the HTML and stores a permanent link.


You can paste a permanent URL into a web browser for debugging.

CMS preserves additional URL segments and query parameters (after the content-specifying part of the URL) when it converts a permanent link. So, you can link to a specific action on a controller (potentially with parameters) or something routed by a partial router. A registered route must match the URL.

### Built-in properties

Many of the built-in types such as `Url` (corresponding to `PropertyUrl` and `PropertyImageUrl` properties), `XHtmlString` (corresponding to `PropertyXhtmlString`) and `LinkItemCollection` (corresponding to `PropertyLinkItemCollection`) support permanent links. However, the basic **string** (corresponding to `ProperyString`/`PropertyLongString`) does not support permanent links because it may contain formats other than HTML. Use the XhtmlString for all HTML content to make use of permanent links.

### Link integrity tracking

When you save a content instance, CMS parses the properties (such as `PropertyUrl`, `PropertyXhtmlString`, `PropertyLinkItemCollection`, and `PropertyContentArea`) for links to other content instances or files, and stores the references in a reference table to track the items that link to each other.

### Export and Import

The export package contains links in a permanent link format when you are transferring content. It makes sure links within the package are preserved during import. If you need to use any other links than the built-in ones (for example, if you have a custom property not based on any of the ones listed in the previous section), you have to handle the conversion during export/import yourself.

### API references

The `EPiServer.Core.Transfer.IReferenceMap` interface on your `PropertyData` object tells CMS that you need to handle permanent links. The `PermanentLinkMapper` handles conversion between permanent links and dynamic links. Access the API using the `EPiServer.Web.PermanentLinkUtility` class. The `EPiServer.Web.IPermanentLinkMapper` and `EPiServer.Web.PermanentLinkMap` classes are underlying components in the `PermanentLink` architecture, and you typically do not need to access them directly.

### Content links references

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