Properties
Properties hold data that is stored on an entity. This page discusses how to get properties, their values 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.
This is related to the IsMultiLanguage property on the property definition.
Getting properties
For the following examples, assume that:
-
entityis an M.Asset entity -
Titleis culture insensitive property -
Descriptionis 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");
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.
ICultureInsensitiveProperty titleProperty = entity.GetProperty<ICultureInsensitiveProperty> ("Title");
ICultureSensitiveProperty descriptionProperty = entity.GetProperty<ICultureSensitiveProperty>("Description");
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.
All loaded properties can also be accessed using the IEntity.Properties property. This is useful for e.g. filtering properties with LINQ.
Getting 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);
Setting property values
Be aware of the values that are passed as there are no validations here.
To set a value on a ICultureInsensitiveProperty property, use:
titleProperty.SetValue("a new title");
To set a value on a ICultureSensitiveProperty property, it is 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 a 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);
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 as a shortcut where internally the property is fetched and then the value of that property is either returned or set.
Getting 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);
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.
Keep in mind what type of property is being used 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.
Setting values
To set a value on a ICultureInsensitiveProperty property, use:
entity.SetPropertyValue("Title", "a new title");
To set a value on a ICultureSensitiveProperty property, it is necessary to pass the culture also.
CultureInfo enUs = CultureInfo.GetCultureInfo("en-US");
entity.SetPropertyValue("Description", enUs, "a new description");
When the property does not exist, or is not loaded, SDK will throw an PropertyNotFoundException.
Similar to getting property values, keep in mind what type of property is being used when getting a property value directly from the entity.