Property Descriptors

Jul 04, 2022
4 minutes to read

The XPCollection and XPServerCollectionSource components support property descriptors for object references. You can use them while setting the component’s DisplayableProperties property (see XPBaseCollection.DisplayableProperties and XPServerCollectionSource.DisplayableProperties), and binding controls to the component’s properties.

Property descriptors include:

PropertyName - The descriptor specifying a property’s name.
PropertyName.NestedPropertyName - The descriptor referring to a sub-property of a specific property.
This - represents a reference to a persistent object.
PropertyName! - A descriptor with a name ending with an exclamation point (“!”) represents a reference to the persistent object identified by the ‘PropertyName’ property. It can be applied to a persistent property only.
PropertyName!Key - A descriptor with a name ending with !Key represents a key of the persistent object identified by the ‘PropertyName’ property. It can be applied to a persistent property only.

Using “PropertyName!Key” vs. “PropertyName.Oid”

This question arises when binding controls to a property of a persistent class type. The most common example of such controls is lookup editors. Generally, you shouldn’t bind these controls to PropertyName.Oid, because when a new value is set to this type of property, the PropertyName’s Oid field is changed instead of the PropertyName itself. Obviously, this is not the expected behavior when you edit a PropertyName via a lookup editor. You must bind it to PropertyName!Key instead. In this case, XPO will find an object by its key and change the reference, as required. You can also use PropertyName! to bind to a lookup editor - internally it doesn’t work the same way as PropertyName!Key, but produces the same result.

Using “PropertyName!” vs. “PropertyName!Key” in Lookup Editors

In ASP.NET applications, you must use descriptors ending with !Key for lookup editors. With Windows Forms applications, you can also use descriptors ending with !. However, you should always use the !Key descriptor for lookup columns in the GridView, if their values are used for filtering. Otherwise, filters will not be properly restored and MRU Filter List may stop working. Please remember that an object referenced by the !Key descriptor can only find those objects which are saved in the database. When an object is not saved, it cannot be found by the Session.GetObjectByKey function.