IContentLoader and IContentRepository

This topic provides an introduction to repository methods for Optimizely 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. 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 by 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.

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 = loader.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 = loader.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 = loader.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 = loader.GetItems(references, new LoaderOptions() { LanguageLoaderOption.FallbackWithMaster() });

When you load several items and 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

Optimizely 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 all 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 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 = repository.Get<TextPage>(pageLink).CreateWritableClone() as TextPage;
writablePage.MainBody = "something";
repository.Save(writablePage, SaveAction.Publish);