Scripting SDK

Properties

Properties hold data that is stored on an entity. This page discusses how to access properties, their value(s) and how to modify these values.

Property types

The SDK uses two types of properties:

ICultureSensitiveProperty - properties with a value per culture.
ICultureInsensitiveProperty - properties that have one value and do not support cultures.

Note

This is related to the IsMultiLanguage property on the property definition.

Getting properties

For the following examples, assume that:

entity is an M.Asset entity
Title is culture insensitive property
Description is culture sensitive property

Property names are not case sensitive.

Non-generic

All property types derive from IProperty, but to access its value(s), a cast to a specific subtype is required.

IProperty titleProperty = entity.GetProperty("Title");

Warning

Exceptions will be thrown when casting to the wrong type of property. Check the (property) definition when in doubt whether a property is culture sensitive or not. IProperty.IsCultureSensitive can also be used.

Generic

Alternatively, use the generic overloads to cast it automatically to either a ICultureInsensitiveProperty or ICultureSensitiveProperty.

All loaded properties can also be accessed using the IEntity.Properties property. This is useful for filtering properties with LINQ, for example.

ICultureInsensitiveProperty titleProperty = entity.GetProperty ICultureInsensitiveProperty ("Title");

ICultureSensitiveProperty descriptionProperty = entity.GetProperty ICultureSensitiveProperty ("Description");

Note

When the property is not found or is not loaded, null will be returned. However, properties can be lazy loaded. See lazy loading for more information.

Get property values

To get a value from a ICultureInsensitiveProperty property, use:

string title = titleProperty.GetValue string ();

To get a value from a ICultureSensitiveProperty property, you are also required to pass a culture. This will get the description in English:

CultureInfo enUs = CultureInfo.GetCultureInfo("en-US");

string description = descriptionProperty.GetValue string (enUs);

Set property values

To set a value on a ICultureInsensitiveProperty property, use:

titleProperty.SetValue("a new title");

To set a value on a ICultureSensitiveProperty property, you are also required to pass a culture.

CultureInfo enUs = CultureInfo.GetCultureInfo("en-US");

descriptionProperty.SetValue(enUs, "a new description");

Multi-value properties

When properties are multi-value, their type changes to an array type. Suppose that MultiDescription is multi-value and culture sensitive string property, getting the property value can be done like this:

ICultureSensitiveProperty property = entity.GetProperty ICultureSensitiveProperty ("MultiDescription");

CultureInfo enUs = CultureInfo.GetCultureInfo("en-US");

string[] values = property.GetValue string[] (enUs);

Note

This is related to the IsMultiValue property on the property definition.

Using property values directly on an entity

It is also possible to get and set property values directly from an entity (IEntity). This acts a shortcut where internally the property is fetched and then the value of that property is either returned or set.

Get values

To get a value from a ICultureInsensitiveProperty property, use:

string title = entity.GetPropertyValue string ("Title");

To get a value from a ICultureSensitiveProperty property, you also need to pass the culture.

CultureInfo enUs = CultureInfo.GetCultureInfo("en-US");
string description = entity.GetPropertyValue string ("Description", enUs);

Warning

When the property does not exist, or is not loaded, the default value of the requested type (here string) will be returned. It is advised to pass nullable types (like long? instead of long for primitives), so that null can be returned. Otherwise the default value of a primitive might cause confusion.

Warning

Keep in mind what type of property you are using when getting a property value directly from the entity. If it is a culture sensitive property, make sure to pass a culture, otherwise an InvalidOperationException exception will be thrown.

Set values

To set a value on a ICultureInsensitiveProperty property, use:

entity.SetPropertyValue("Title", "a new title");

To set a value on a ICultureSensitiveProperty property, you also need to pass the culture.

CultureInfo enUs = CultureInfo.GetCultureInfo("en-US");

entity.SetPropertyValue("Description", enUs, "a new description");

Warning

When the property does not exist, or is not loaded, SDK will throw an PropertyNotFoundException.

Warning

Similar to getting property values, keep in mind what type of property you are using when getting a property value directly from the entity.

If you have suggestions for improving this article, let us know!