Upravit

Sdílet prostřednictvím

Understanding the Property Description Schema

  • Článek

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

The introduction of new features for Windows Vista and later required that the existing Shell property system be extended to:

  • Support 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.
  • Support a stock list of property types (combined with UI that can edit those types in different views like the listview, preview pane, property dialogs, and so on) that can be associated with various properties.
  • Supply property description lists, which define the set of properties displayed in various views.
  • Provide 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 of a Shell item. This abstraction is called the Shell property system.

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 runtime 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.

Note

You must add xmlns=http://schemas.microsoft.com/windows/2006/propertydescription to the root schema element of your .propdesc files.

 

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, as well as 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, as well as 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 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:

propertyDescription

searchInfo

labelInfo

typeInfo

displayInfo

stringFormat

booleanFormat

numberFormat

dateTimeFormat

enumeratedList

drawControl

editControl

filterControl

queryControl

image