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.

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

Note

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.

RequestResponse

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.

RequestResponse

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

RequestResponse

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.

Note

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:

RequestResponse

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:

RequestResponse

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

string description = descriptionProperty.GetValue<string>(enUs);

Setting property values

Warning

Be aware of the values that are passed as there are no validations here.

To set a value on a ICultureInsensitiveProperty property, use:

RequestResponse

titleProperty.SetValue("a new title");

To set a value on a ICultureSensitiveProperty property, it is also required to pass a culture.

RequestResponse

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:

RequestResponse

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 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:

RequestResponse

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

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

RequestResponse

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 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:

RequestResponse

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

To set a value on a ICultureSensitiveProperty property, it is necessary to pass the culture also.

RequestResponse

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 is being used when getting a property value directly from the entity.

Do you have some feedback for us?

If you have suggestions for improving this article,