In this tutorial, you will learn about the two main categories of content types within Umbraco v9, published content and normal content. When it comes to building a website within Umbraco v9, it is important to understand the difference between these two types. If you use the wrong type in the wrong situation, bad things can happen. In the worst-case scenario, you could launch your website and it could come to a grinding halt as soon as people start accessing it. Trust me as I have personally fallen into this trap 😕

If you want to learn more about content within Umbraco, learn the correct way to access content, and learn in which scenarios you should use the different APIs, read on 🔥🔥🔥

Published Content

Whenever a content editor creates and publishes a page within the backend, two things happen. The data is added within the external Lucene index. You can use this index to create a website search using Examine. More information about this can be found here.

Data is also added into the Umbraco frontend cache. This cache is used to provide quick and fast access to the content within the CMS. Using the APIs that query the cache avoids the need for Umbraco to query the database. Querying the database would not be ideal for performance. If Umbraco queried the database anytime any content needed to be rendered, your site would run extremely slowly and your server would only be able to handle limited traffic.

When you are trying to write your frontend code to render data from the CMS, you should always use the APIs that call the cache rather than the database. The APIs that work with the frontend cache will all return CMS data as type IPublishedContent.

To access items contained within the cache, you can use one of several APIs. Firstly, you can use IUmbracoContextAccessor. You can use this API like this:

It is also possible to query the cache using IUmbracoContextFactory, like this:

Both of these APIs will return content as IPublishedContent. If you did a deeper dive into what properties and methods IPublishedContent provide, you will notice it returns data related with presentational concerns. You will get access to properties like Children, ChildrenForAllCultures and UrlSegment. Using extensions using via the Umbraco.Extensions, you will also get access to useful properties like Breadcrumbs(), Ancestors(), and Descendants().


Not all content created within the CMS will be published content. It is possible to schedule content and save content without publishing it. Umbraco also provides APIs that can access all content created within the CMS, not just the live published data.

When you need to work with non-published content it is likely you are creating some backend plug-in or doing some form of infrequent call. The APIs that you can use to work with the backend content is not as performant as the APIs that work with the cache. The content-related APIs may query the database directly, rather than the frontend cache. The API that queries all the content within the CMS, will return content as typeIContent. The API you will need to use to access IContent items is IContentService:

Items of type IContent expose properties and methods that allow you to do more CMS level management on the items. Using IContent you can access properties like PublishedState, PublishedVersionId, and Blueprint. Umbraco also provides some additional extension methods that you can use with IContent items, within the Umbraco.Extensions namespace. Using ContentExtensions you can access methods like StoreFile, SetValue, and ContentSchedule.

On a normal day-to-day basis, you should not use the IContentService API. You should only use IContentService when you are trying to create a backend plug-in within the CMS, or you want to do more content processing.

Now you know the difference between published content and normal content within Umbraco. When building normal web pages always use IPublishedContent. If you need to create some backend extension, use the APIs that work with IContent Happy Coding 🤘