In today's tutorial, you will learn why you need to use a content reference class to access Episerver content in code. When you start using Episerver CMS, you will come across the content reference class very quickly. The content reference is comprised of three properties and it can be used to uniquely reference any content within the CMS. If you want to learn why Episerver needs to use these properties this is the guide for you 🔥🔥🔥
Content
In Episerver, we work with content. This content can be pages, blocks, reviews, comments, images, youtube videos... pretty much anything that you want. In order to build a universal API that works with all these different types of content, Episerver created the IContent interface. Any content that appears in the CMS must implement this interface.
The benefit of IContent is that it gives us, as developers, a lot of flexibility of what content we can work within inside of the CMS. Most companies will have their own bespoke services and systems, by providing a standard interface it allows for third-party data to be integrated and used within Episerver. This ability to use multiple data sources brings us to the first dilemma... how to design a solution that allows you to work with content that lives within another system outside of Episerver 🤔.
If you look in the content reference properties, you will see something called ProviderName. ProviderName is the thing that allows you to choose the data source of the content. On most standard Episerver CMS builds that you will work on, you will only work with Episerver content. In these situations, you do not need to explicitly add the provider name. The default value will use Episerver as the datasource. This is why you do not need to worry about this property on most projects, however, it is an important part of understanding the content reference.
Versioning
Content changes and websites are not static entities that you publish once and then it never changes. Some companies have dedicated content teams that are constantly tweaking and improving the site content. This provides us with a second challenge, how do you access previous versions of content? If you only have a single ID or code to reference content you would not be able to specify which version of the page you want to retrieve. This is why the ContentReference also contains WorkID. WorkID is the mechanism that you can tell Episerver which version you want to query. By default it will default to the latest version!
Performance
The purpose of WorkId and ProviderName are probably more obvious for any developer who has worked with Episerver for a while, but this third consideration may sound a little strange. When I first started using ContentReference to get content from Episerver, it feels like you might be writing more code than you need to get items out of it. Sometimes you might need to query the database or a config file to get the content reference ID you want to query. With a ContentReference defined you use 'IContentRepository` to get that content from the CMS (read this to learn more).
Episerver caches individual pages in memory. Episerver does not store the navigation hierarchy as one giat object in memory. Instead, it caches the results of the GetChildren<T>() command as a list of ContentReferences. By using the ContentReference object approach, Episerver can implement two kinds of backend caching. One cache that contains the content. The other cache contains the page hierarchy.
This allows Episerver to work very quickly. For navigation queries it can use the cached content references and for page queries it can use the content data cache. This has two benefits, first, if a content editor updates a page, only a small part of the cache need to be updated. As blocks can live in multiple content areas simultaneously if the block was updated it only needs to be updated in the data cache once and not updated in every content item. If Episerver held the whole hierarchy in cache somehow, the whole tree would need to be refreshed whenever a content item was changed.
You are now a content reference master. Happy coding 🤘
