Property Description Schema

  • Article

This topic introduces the property description schema used by the Shell property system.

Windows Vista and later support new search and organize features, which required that the existing Shell property system be enhanced and extended. The property system now includes:

  • A rich and extensible property description system that provides information about properties including display names, type, display type, sort and group behavior, and other attributes needed to present and operate over the properties.
  • A stock list of property types that can be associated with various properties, and a (combined with UI that can edit those types in different views like the listview, preview pane, property dialogs, and so on).
  • Property description lists, which define the set of properties displayed in various views.
  • A simplified interface, IPropertyStore, so property handlers can be written more easily and so properties can be persisted to files.
  • Support for non-file property handlers to expose properties in the view.

These features are achieved on an architecture that provides abstract access to the properties in an item. This abstraction is called the Shell property system.

  • What Is the Property Description Schema?
  • Why Use a Schema?
  • What Are the Major Schema Parts?
  • Changes for Windows 7
  • Related Topics

What Is the Property Description Schema?

The schema subsystem consists of the following:

  • One or more .propdesc schema files that define property descriptions. The property description schema is defined in a collection of XML schema files (using the .propdesc file extension) at run time on the system. These files are lazy-loaded when a part of the property system requires them.
  • An in-memory schema cache used to store the parsed schema files, which include all property descriptions introduced to the subsystem. There is no need to reparse the .propdesc config files that describe the schema. For more information, see PSRegisterPropertySchema, PSUnregisterPropertySchema, and PSRefreshPropertySchema.
  • A subsystem object that implements IPropertySystem, which is used to obtain or work with property descriptions.
  • A subsystem object that implements IPropertyDescription, which is used to inform and operate based on a property description.
  • A subsystem object that implements IPropertyDescriptionList, which is used as a collection of property descriptions.

Important  It is critical that you define properties carefully and strategically for the first release of the schema. Any changes to custom properties (such as column width or property type) will not be reflected in the database after a schema has been registered. The only way 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 (which consists of a canonical name and a PKEY) for each subequent 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.

Why Use a Schema?

Properties, by themselves, are not type-safe. A component can assign a numerical value to the System.Author property, or a FILETIME date-stamp to the System.Music.AlbumTitle property, and, without any further enforcement or guidance, the property stores will allow it. So, we needed a notion to "schematize" the properties, which brings us to the schema subsystem.

What Are the Major Schema Parts?

The property description schema used by the Shell property system is composed of a single propertyDescriptionList element, and a schemaVersion attribute, which indicates the version of this schema definition format. Note: value must be "1.0".

<!-- schema -->
    <xs:element name="schema">
      <xs:complexType>
        <xs:sequence>
          <xs:element ref="propertyDescriptionList" minOccurs="1" maxOccurs="1"/>
        </xs:sequence>
        <xs:attribute name="schemaVersion"  type="xs:string"/>
      </xs:complexType>
    </xs:element>

The propertyDescriptionList is composed of one or more propertyDescription elements, and publisher and product attributes.

<!-- propertyDescriptionList -->
    <xs:element name="propertyDescriptionList">
      <xs:complexType>
        <xs:sequence>
          <xs:element ref="propertyDescription" minOccurs="1" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:attribute name="publisher" type="xs:string"/>
        <xs:attribute name="product"   type="xs:string"/>
      </xs:complexType>
    </xs:element>

A propertyDescription is composed of one searchInfo and zero or one labelInfo, typeInfo, and displayInfo elements, as well as formatID, propID, propstr, and name attributes.

There should be one propertyDescription element for every unique canonical property name that is intended to be available in the system. The string attributes have a limit of 512 characters. Values longer than 512 characters are truncated.

<!-- propertyDescription -->
    <xs:element name="propertyDescription">
      <xs:complexType>
        <xs:all>
          <xs:element name="description"    type="xs:string" minOccurs="0" maxOccurs="1"/>
          <xs:element ref="searchInfo"   minOccurs="1" maxOccurs="1"/>
          <xs:element ref="labelInfo"    minOccurs="0" maxOccurs="1"/>
          <xs:element ref="typeInfo"     minOccurs="0" maxOccurs="1"/>
          <xs:element ref="displayInfo"  minOccurs="0" maxOccurs="1"/>
        </xs:all>
        <xs:attribute name="formatID"  type="upcase-uuid" use="required""/>
        <xs:attribute name="propID"    type="xs:nonNegativeInteger" use="required""/>
        <xs:attribute name="name"      type="canonical-name" use="required"/>
      </xs:complexType>
    </xs:element>

Changes for Windows 7

The property description schema has been changed for Windows 7. These are non-breaking changes. If a property element or attribute is no longer supported in Windows 7, the Windows 7 operating system simply ignores the Windows Vista element or attributes. Similarly, Windows Vista ignores new Windows 7 property elements or attributes as well.

However, updating custom properties for Windows 7 is recommended for a better and more consistent user experience.

The following are new elements and attributes:

The following elements and attributes have changed:

The following elements and attributes have been removed:

See Also

propertyDescription

searchInfo

labelInfo

typeInfo

displayInfo

stringFormat

booleanFormat

numberFormat

dateTimeFormat

enumeratedList

drawControl

editControl

filterControl

queryControl

image

 

 

Send comments about this topic to Microsoft

Build date: 4/28/2010