Custom properties (name-value pairs)

The designers of various objects as well as the project preferences give you the opportunity to specify so called custom properties. Custom properties are name - value pairs (both strings) which are generated into the code (except for project custom properties) and add both value to the XML comments added to the various methods and properties but also are available at runtime (Entities, Typed Views and Typed Lists).

This section describes in detail how to retrieve the custom properties for an entity, typed list or typed view or the custom properties for the fields of these objects.

The custom properties are stored in Dictionary<string, string> objects (entity custom properties) and Dictionary<string, Dictionary<String, String>> for field custom properties.

Entity/TypedList/TypedView custom properties

Entity, TypedList and TypedView custom properties are available in the form of a Dictionary object. This object is created once per type, in a static (shared) constructor. This means that the custom properties are not eating a lot of memory in your application, nor do they increase the size of your objects.

Each entity, typed list or typed view class has a static (shared) property called CustomProperties. This static property can be used to retrieve the Dictionary with the name (which is the key in the Dictionary) - value pairs for a particular class, at runtime.

Below is an example which illustrates the retrieval of the custom properties for the OrderEntity and which gets the value for the custom property 'Description' which was added in the designer by the user.

Dictionary<string, string>  customProperties = CustomerEntity.CustomProperties;
string description = customProperties["Description"];

Each entity/typed list/typed view instance also has a property called CustomPropertiesOfType. This property returns the hashtable of the type of the instance. This is convenient so you can get the custom properties from an instance as well during runtime without having to determine the type.

// customer is an instance of CustomerEntity
Dictionary<string, string> customProperties = ((IEntity2)customer).CustomPropertiesOfType;
string description = customProperties["Description"];

// customer is an instance of CustomerEntity
Dictionary<string, string> customProperties = ((IEntity)customer).CustomPropertiesOfType;
string description = customProperties["Description"];

Entity/TypedList/TypedView field custom properties

Besides custom properties per entity/typed list/typed view, you can also define custom properties per entity field/typed list field/typed view field. Per field these properties are stored in a Dictionary object.

These Dictionary objects are stored per field name in the entity/typed list/typed view class, similar to the class custom properties, also in a Dictionary. The Dictionary with the per-field Dictionaries is accessible through the static property 'FieldsCustomProperties' or through the instance property 'FieldsCustomPropertiesOfType'.

Below is an example which retrieves a custom property called 'Description' from the custom properties of a field called 'CustomerID' of the class CustomerEntity.

Dictionary<string, string> fieldCustomProperties = CustomerEntity.FieldsCustomProperties["CustomerID"];
string description = fieldCustomProperties["Description"];

For the runtime version, use the FieldCustomPropertiesOfType property on an instance, similar to the CustomPropertiesOfType property.