In this tutorial, you will learn about some important considerations that you need to make when working with Episerver content references. If you find yourself needing to store a reference to an Episerver item within a third-party service or database you might be tempted to simply store the Id part of a content reference. Only storing the Id is not optimal and in this tutorial, you will learn why and how you should store references🔥🔥🔥

The Episerver Content Primary Key

Episerver defines a custom type called a ContenReference to uniquely identify content within the CMS. A ContenReference is composed of three main properties:

  • Id: This maps to a date abase ID

  • WorkID: Also known and the VersionID. This is used to identify a particular page revision. The default value is the latest version.

  • ProviderName: Where the content is stored. The default is the Episerver database

These three properties combined are used uniquely identify a piece of content. If you want more information about this process, I would recommend reading, Why Does Episerver Need A Content Reference?.

If you need to store a reference to an Episerver item, you might be tempted to write some code like this:

This code will work in the short term, however, in the future if someone introduced a second content provider this code might break. If someone introduced a second provider, it might be possible two bits of content could have the same Id. The chances of this happening are minimal, however, if you used this code a very subtle bug could be introduced into your platform at a later date. If a second external content provider was added later on and two bits of content existed both with an identifier of 4, you wouldn't be able to guarantee which one the API would return. It is very simple to ensure this type of situation doesn't occur. When saving a reference to an item, store the complete content reference. The easiest way to do this is to use Json.Net to serialise the content reference into a string before you save the data. Let us look at how to do this:

Json.Net Serialise

Below shows the code required to serialise a content reference and store that value as a string:

To retrieve the reference, you can deserialize it using this code:

This code will ensure no potential reference issues occur 💥

Store The Content Reference as a GUID

If you do not want to use JSON.NET, there is an alternative approach that you can use to store a content reference. You can also use the IdentityMappingService. The IdentityMappingService is an Episerver API that was introduced to support external integrations, like a content provider serving up content from a third-party data source.

The IdentityMappingService creates a mapping between a bit of content and a Uri. The output of this mapping is a unique GUID that you can use to identify content regardless of the data source. You can then store this GUID in your external data source. You can use IdentityMappingService like this:

This second approach takes more coding effort compared to simply using JSON.NET, however, it results in fewer data needing to be stored. There are a few downsides to this approach. The first is that you won't be able to manually eyeball what an item is referencing. As the data will be a GUID, you will always have to use the IdentityMappingService before you can figure out what it references. Second, IdentityMappingService is slightly less efficient as the code uses multiple look-ups. You have to look up the Id and translate it to a content reference AND then you have to use the content reference to look up the content in the CMS. If your data is used very infrequently, you may not care about this marginal performance impact.

In most situations, I recommend using the JSON.NET option. Serialising objects is quick and easy. You could just as easily use the IdentityMappingService to ensure that your code is future proof. The main takeaway is just don't store the Id on its own 😕. Happy Coding 🤘