IContentLoader and IContentRepository

9 min

EPiServer.IContentRepository is the primary API that defines repository methods for IContent objects. Through the repository, you can perform CRUD (Create, Read, Update, Delete) operations on content instances implementing EPiServer.Core.IContent, for example, listing and move.

You would normally get an instance of any interface using dependency injection (for example, by constructor injection). But you can also get a content instance by calling the inversion of control (IoC) container directly:

var repository = EPiServer.ServiceLocation.ServiceLocator.Current.GetInstance<IContentRepository>();

If you only need read-only access to content, use the IContentLoader interface instead:

var loader = EPiServer.ServiceLocation.ServiceLocator.Current.GetInstance<IContentLoader>();

The following examples show common operations for instances of content.

Load a content instance

To load a single content instance, call the method: Get<T> where T : IContentData. The T type parameter specifies which type you want. So, if there is a type representing a page as:

[ContentType]
public class TextPage: PageData {
  public virtual string MainBody {
    get;
    set;
  }
}

...and you know to which type a given reference refers, you can load the page as:

TextPage page = loader.Get<TextPage>(pageLink);

If you cannot assign the content item to the type given as a type argument, a TypeMismatchException occurs. If you do not know an item's type, you can safely load the item with IContent as type argument. (The constraint is IContentData, but in runtime, each instance loadable from the repository implements IContent.)

var content = loader.Get<IContent>(pageLink);

If you want to load an item as a given type but do not want to generate an exception if the type is not correct, you can load it as:

TextPage page = loader.Get<IContent>(pageLink) as TextPage;

You can load several content instances simultaneously with the following calls.

IEnumerable < ContentReference > references = GetSomeReferences();
IEnumerable < IContent > items = loader.GetItems(references, new LoaderOptions() {
  LanguageLoaderOption.FallbackWithMaster()
});

When you load several items and a type is not matching, it filters the result for types that are assignable to the type argument (and does not generate a TypeMismatchException).

You can specify a language version of content by using an overload that takes a CultureInfo or a LanguageLoaderOption. If you do not specify CultureInfo, content is retrieved in the same language that the current request specifies; see ContentLanguage.PreferredCulture. You can specify CultureInfo to consider the language fallback and replacement settings by using a LanguageLoaderOption with fallback enabled. The following example shows how to get the Swedish version of the page.

page = Locate.ContentRepository().Get<TextPage>(pageLink, CultureInfo.GetCultureInfo("sv"));

List children of a content instance

Optimizely Content Management System (CMS) stores content in a tree hierarchy. The following example shows how to get the children of a content instance:

IEnumerable<IContent> children = loader.GetChildren<IContent>(pageLink);

To get children that are pages to a content instance, use the following call:

IEnumerable<PageData> pages = loader.GetChildren<PageData>(pageLink);

If you want the children in a specific language, use overloads to GetChildren that takes a LoaderOption.

Persist a content instance

To persist an IContent instance, call the Save method. If the IContent instance implements IReadOnly, call CreateWritableClone before you modify the instance. The save method has a SaveAction flag parameter controls which action occurs when saved, such as publishing the page. The following example shows how to update a page property programmatically.

var writablePage = repository.Get < TextPage > (pageLink).CreateWritableClone() as TextPage;
writablePage.MainBody = "something";
repository.Save(writablePage, SaveAction.Publish);

DataFactory

The EPiServer.DataFactory class, which has an Instance property that gives access to the singleton instance of the repository, is a façade that implements IContentRepository and forwards calls to the actual implementation (DataFactory also acts as a front for other interfaces such as IContentVersionRepository). DataFactory is the legacy implementation for many APIs and is only kept for backward compatibility.