The Do's And Dont's When Storing A Reference To Episerver Content In An External Data Source

Sometimes, when we work with Episerver, we may need to store a reference to an Episerver content item in a third-party service or database. On a recent project, I came across a situation where a developer had chosen to just store the ID part of a content reference and he didn't understand the subtle bug that he had created. In today's guide, I'm going to cover why just storing the database Id is 'sub-optimal' and cover some alternative approaches.

How To Uniquely Identify Episerver Content

Episerver uses a thing called a content reference to uniquely identify content within your project. A content reference being made up of a database ID, a version ID (WorkID) and a provider name. It's these three things combined that can be used uniquely in a piece of content. If you want more information about this process then I would recommend reading, Why Does Episerver Need A Content Reference?. In the case I saw, we had a method to look up a piece of content like this:

// Get the ID from third-party database

private void Get(int id)
{
  var contentLoader = ServiceLocator.Current.GetInstance<IContentLoader>();
  var startpage = contentLoader.Get<IContent>(new ContentReference(id));
}

In most projects, this code will work, however, in the future if someone introduced a content provider, it might be possible two bits of content could have the same database Id. This could create subtle bugs later on in the project lifecycle. For example, if you introduce an external content provider and you have two bits of content with an identifier of 4, you can't guarantee what parts of your code could break! Instead, it's very simple to ensure this situation doesn't occur by storing a little bit more information in your third-party data source.

Json.Net Serialise

This is probably the quickest and dirtiest method. Instead of using the Id, serialise a content reference and store that as a string in the database, like so:

     var reference = new ContentReference();
     var result = JsonConvert.SerializeObject(reference);

When we want to retrieve the Episerver reference we can then deserialize it, like so:

// get result from db
JsonConvert.DeserializeObject<ContentReference>(result );

This is very simple and straight-forward and gets rid of any potential issues later down the line, however, this is not your only option.

Store The Content Reference as a GUID

The second way of storing a reference to the content reference is to 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 an IContent 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 unique identifying in your data source, like so:

            var myContent = new PageData();

            var guidToString = "websitedomain.com";
            var customIdentity = new Uri(guidToString);

            var identityMappingService = ServiceLocator.Current.GetInstance<IdentityMappingService>();
            var mappedIdentity = identityMappingService.MapContent(customIdentity, myContent);

            var referenceToStoreAsString= mappedIdentity.ContentGuid.ToString();

Then to get the link to the content we can get it out like this:

            var referneceToStore = new Guid(referenceToStoreAsString);
            var content = identityMappingService.Get(referneceToStore);

            var contentLoader = ServiceLocator.Current.GetInstance<IContentLoader>();
            var startpage = contentLoader.Get<IContent>(content.ContentLink);

Now, obviously this second approach takes a lot more code and overhead than the JSON serialise approach, but the end result will solve the initial issue and results in a single identifier that references an Episerver object. There are a few downsides to this approach, in your SQL table you won't manually be able to see what the reference points to, you have to use the IdentityMappingService in order to figure out what your data is referenced to. Also, this method is less efficient as it uses multiple look-ups, first it has to lookup the Id and translate it to the content reference AND then you have to use the content reference to look-up the content. If your data is used very infrequently, then you may not care about this but it is worth noting. Personally, in most situations I would use the JSON option as it's tried and trusted and simple to use. Out of all the approaches, I wouldn't recommend just storing the Id.

Conclusion

In today's tutorial, I hope I've provided enough information to show why simply storing the Episerver ID in a third party data source is a bad idea and that there are better approaches available. I would personally recommend serialising objects as it's quick and easy, but, you could just as easily use the IdentityMappingService to ensure that your code is future proof.