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

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

Tip

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

This section explains the different load options and 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.

Note

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:
RequestResponse
```
new CultureLoadOption("en-US", "nl-BE");
```
By passing any type of collection (deriving from IEnumerable) of locale identifiers (LCID):
RequestResponse
```
string[] cultures = new [] {"en-US", "nl-BE"};
new CultureLoadOption(cultures);
```

By passing CultureInfo instances (comma separated):

RequestResponse

new CultureLoadOption(CultureInfo.GetCultureInfo("en-US"), CultureInfo.GetCultureInfo("nl-BE"));

By passing any type of collection (deriving from IEnumerable) of CultureInfo instances:

RequestResponse

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):
RequestResponse
```
new PropertyLoadOption("propertyName1", "propertyName2");
```

By passing any type of collection (deriving from IEnumerable) of property names:

RequestResponse

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):
RequestResponse
```
new RelationLoadOption("relationName1", "relationName2");
```

By passing any type of collection (deriving from IEnumerable) of relation names:

RequestResponse

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:

RequestResponse

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:
RequestResponse
```
RelationSpecification[] specs = new [] {spec1, spec2};
new RelationLoadOption(specs);
```

Load configurations

Load configurations are a "molecular unit" which aggregates multiple load options. Load configurations have default configuration values and support copy constructors.

Note

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:

RequestResponse

new EntityLoadConfiguration(
  CultureLoadOption.None,
  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.

Note

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

Note

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:

RequestResponse

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,