Load configurations

The SDK and Stylelabs.M.Base.Querying use load configurations and load options to specify:

  • Whether entities need to be loaded or not

  • Which cultures an entity has to be loaded in

  • Which members to load in an entity


The load configurations are located at: Stylelabs.M.Framework.Essentials.LoadConfigurations.The load options are located at: Stylelabs.M.Framework.Essentials.LoadOptions.


Try to load the least amount of data using the load options and configurations to minimize the overhead on the server.

In this section, first explained is the different load options, then how to use the load configurations with the load options.

Load options

Load options are an "atomic unit" which specifies how to load a specific item. The currently supported load options are:

  • Culture load option

  • Property load option

  • Relation load option

Every load option has a default, a static and a read-only instance for common use cases. Also, loading options have a copy constructor. This can be used to copy the read-only loading options so that they can be modified.

All the above mentioned load option classes have a LoadOption (an enum) property which can be:

  • None

  • Default

  • Custom

  • All

When set to Custom, the object has to specify what to load by providing a list of property names for the PropertyLoadOption. When the LoadOption is not set to Custom, the list is ignored.

Culture load option

The following are the default culture load options :

  • CultureLoadOption.All: loads all registered cultures in Sitecore Content Hub.

  • CultureLoadOption.Default: loads the default culture in Sitecore Content Hub.

  • CultureLoadOption.None: loads no cultures.


When entities are loaded without cultures, there will be no culture sensitive properties on the entity. When entities are loaded in a specific set of cultures, culture sensitive properties will only be available in those cultures.

To load a specific set of cultures, create a new CultureLoadOption by using one of the following methods:

  • By passing locale identifiers (LCID) comma separated:

    new CultureLoadOption("en-US", "nl-BE");
  • By passing any type of collection (deriving from IEnumerable) of locale identifiers (LCID):

    string[] cultures = new [] {"en-US", "nl-BE"};
    new CultureLoadOption(cultures);
  • By passing CultureInfo instances (comma separated):

    new CultureLoadOption(CultureInfo.GetCultureInfo("en-US"), CultureInfo.GetCultureInfo("nl-BE"));
  • By passing any type of collection (deriving from IEnumerable) of CultureInfo instances:

    CultureInfo[] cultures = new [] {CultureInfo.GetCultureInfo("en-US"), CultureInfo.GetCultureInfo("nl-BE")};
    new CultureLoadOption(cultures);

Property load option

The following are the default property load options:

  • PropertyLoadOption.All: loads all properties on the entity.

  • PropertyLoadOption.None: loads no properties on the entity.

To load a specific set of properties, create a new PropertyLoadOption using one of the following methods :

  • By passing the property names (comma separated):

    new PropertyLoadOption("propertyName1", "propertyName2");
  • By passing any type of collection (deriving from IEnumerable) of property names:

    string[] names = new [] {"propertyName1", "propertyName2"};
    new PropertyLoadOption(names);

Relation load option

The following are the default relation load options:

  • RelationLoadOption.All: loads all relations on the entity.

  • RelationLoadOption.None: loads no relations on the entity.

To load a specific set of relations, create a new RelationLoadOption using one of the following methods :

  • By passing the relation names (comma separated):

    new RelationLoadOption("relationName1", "relationName2");
  • By passing any type of collection (deriving from IEnumerable) of relation names:

    string[] names = new [] {"relationName1", "relationName2"};
    new RelationLoadOption(names);

In order to specify which role to load (e.g. load self-referencing relations), create RelationSpecification objects using one of the following methods:

  • By passing relation specifications comma separated:

    RelationSpecification spec1 = new RelationSpecification
      Name = "childSelfReferencingRelation",
      Role = RelationRole.Child
    RelationSpecification spec2 = new RelationSpecification
      Name = "paentSelfReferencingRelation",
      Role = RelationRole.Parent
    new RelationLoadOption(spec1, spec2);
  • By passing any type of collection (deriving from IEnumerable) of relation specifications:

    RelationSpecification[] specs = new [] {spec1, spec2};
    new RelationLoadOption(specs);

Load configurations

Loading configurations are a "molecular unit" which aggregates multiple load options.


Loading configurations also have default configuration values and support copy constructors.


Previously the IQueryLoadConfiguration was mentioned here, but since the split of the Query and LoadConfiguration, the IQueryLoadConfiguration should only be used internally in the SDK.

Entity load configuration

The configuration consists of:

  • CultureLoadOption

  • PropertyLoadOption

  • RelationLoadOption

The following are the default entity loading configurations :

  • EntityLoadConfiguration.Minimal: loads entities without any cultures, properties and relations. Only system properties are available (id, definition, created on, created by...).

  • EntityLoadConfiguration.Default: loads entities in the default culture, all properties and no relations.

  • EntityLoadConfiguration.DefaultCultureFull: loads entities in the default culture, with all properties and all relations.

  • EntityLoadConfiguration.Full: loads entities in all cultures, all properties and all relations.

A Custom configuration is created in the following method :


new EntityLoadConfiguration(
  new PropertyLoadOption("Title", "FileName"),
  new RelationLoadOption("AssetTypeToAsset")

This example loads the entity without any cultures, with the Title and FileName properties, and with the AssetTypeToAsset relation.


It is also possible to set the load options using the properties instead of the constructor.


When no EntityLoadConfiguration is specified, the SDK always defaults to the Default configuration.

Entity load configuration builder

The IEntityLoadConfiguration comes with a builder to easily create or extend load configurations.

The following example starts from the minimal load configuration, but adds two relations:


var loadConfig = EntityLoadConfiguration.Minimal.Builder().WithRelations(new[] { "Relation1", "Relation2" }).Build();

This line consists of multiple parts:

  • EntityLoadConfiguration.Minimal: it starts from a default provided load configuration.

  • Builder(): to build a new configuration, we need to get the builder.

  • WithRelations(new[] { "Relation1", "Relation2" }): changes the load configuration inside the builder. This can be chained with all other builder methods.

  • .Build(): finally we finish the build process and get the final load configuration.

Do you have some feedback for us?

If you have suggestions for improving this article,