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.
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.
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");
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);
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);
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 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");
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 you are using when getting a property value directly from the entity.