Creating Custom Properties

Properties used in the property system of Windows Vista and later are declared in property schemas. These property schemas are defined in XML files and describe various aspects of a property including its type (including information on its primitive type and whether it is multi-valued), how it can be displayed in the Windows UI, what kind of labels (user-friendly editing strings) are to be used with it, and how it is cached in the search store for faster access. Properties are identified by their Canonical Name or their Property Key (PKEY).

A canonical name is the reader-friendly name of the property and uses a namespace convention similar to that used in Microsoft .NET. For system-defined properties (those that are included with Windows), the convention is System.GroupName.PropertyName. Note that the Pascal casing scheme, which capitalizes letters at the beginning of each word, is used in these names. Canonical names are used in various places including property lists and column names in the property cache. They are therefore used in Structured Query Language (SQL) queries to retrieve a property value.

A PKEY is a pair of values consisting of a GUID and a DWORD, referred to as a formatID and propID respectively. It is represented by a PROPERTYKEY structure. Most of the property system APIs accept these property keys. The Windows Software Development Kit (SDK) includes the header file Propkey.h that includes a macro definition of each of the System property keys with the convention of PKEY_GroupName_PropertyName. For example, PKEY_Photo_DateTaken is the property key for the property with canonical name System.Photo.DateTaken. Property values are stored in the form of a PROPVARIANT structure, which is an extension of the OLE VARIANT types.

This section contains the following topic, which is integral to creating custom properties:

Note  Due to potential difficulties that the indexer may have when consuming the property system's schema, it is critical that you define attributes carefully and strategically for the first release of the schema. Any changes to attributes (type, column width, whether indexible) will not be reflected in the database after a schema has been registered. The only ways to have these changes recognized after the schema has been registered once on a system would be either to rebuild the index and then register the new schema, or to register the schema and then create a new property for each subsequent release; for example PKEY_GroupName_PropertyNameV2, PKEY_GroupName_PropertyNameV3, and so forth). We do not recommend creating new properties in this manner, because multiple extraneous columns may impact system performance.

Related topics

Implementing Property Handlers
Property Description Schema