IContentRepository and DataFactory

This topic provides an introduction to repository methods for Episerver content, as well as how to load, list and persist content instances.

How it works

EPiServer.IContentRepository is the primary API that defines repository methods for IContent objects. If you prefer a concrete class, use the corresponding EPiServer.DataFactory class, which has an Instance property that gives access to the singleton instance of the repository.

Through the repository, you can perform CRUD (Create, Read, Update, Delete) operations and other operations on content instances such as listing and move (that is, instances implementing EPiServer.Core.IContent).

Many base classes (such as PageBase, UserControlBase, and PropertyData) expose the Locate property, which in turn exposes the EPiServer.IContentRepository API. You also can get a content instance from inversion of control (IoC) container through the call:

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

The following examples show common operations for instances of content.

Loading 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 = Locate.ContentRepository().Get<TextPage>(pageLink);

If the content item cannot be assigned to the type given as 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 repository implements IContent.)

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

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

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

You can load several content instances at the same time with the following calls.

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

When you load several items, if a type is not matching, the result is filtered for types that are assignable to 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"));

Listing children of a content instance

CMS stores content in a tree hierarchy. The following example shows how to get the children of a content instance:

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

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

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

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

Persisting 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 that controls which action occurs when saved, such as publishing the page. The following example shows how to programmatically update a page property.

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