Developing Property Handlers for Windows Search

  • Article

The property system enables a file format to store properties assigned to it and to expose that value when queried. Windows Search can then index and search for items using those properties. Property handlers are invoked out-of-process by Windows Search to read and index property values and are also invoked in-process by Windows Explorer to read and write property values directly in the files.

Implementing property handlers involves the following stages:

  1. Making some design decisions regarding the properties you want to support.
  2. Creating a .propdesc file for new properties not already in the System schema.
  3. Implementing and testing property handler interface(s).
  4. Installing and registering the property handler and property description files.
  5. Testing property handler installation and registration.

This topic is meant to supplement the Property System topic with information specific to Windows Search and contains the following sections:

  • Design Decisions for Property Handlers
  • Writing Property Description Files
  • Implementing Property Handlers
  • Installing and Registering Property Handlers
  • Testing Property Handlers
  • Related Topics

 

Design Decisions for Property Handlers

Before you begin, you need to answer a few design questions:

  • What properties does/should the file format support?
  • Are these properties already in the System schema?
  • Which properties should the file format display to end users?
  • Which properties should users be able to edit?
  • Should support for full-text search come from a property handler or a filter?
  • Do I need to support legacy applications? If so, what do I implement?

With these decisions made, you can write formal descriptions of your custom properties so that the Windows Search engine can begin indexing your files and properties. These formal descriptions are XML files, described in Property Description Schema.

Property Decisions

When considering which properties to support, you should identify your users' indexing and searching needs. For example, you may be able to identify one hundred potentially useful properties for your file type, but users may be interested in searching on only a handful. Furthermore, you may want to display a different, larger or smaller, group of those properties to users in Windows Explorer, and allow users to edit only a subset of those properties displayed.

Your file type can support any custom properties you define, as well as a set of system-defined properties. Before you create a custom property, be sure there isn't a system-defined property you can use instead. The system-defined properties read from the propsys.dll at runtime and can be enumerated using the PSEnumPropertyDescriptions API.

We recommend using a matrix to help you design your properties:

Property Indexable Displayable Editable
property1 Y Y N
property... Y Y N
propertyn N N N

For each of these properties, you need to determine what attributes it should have and then describe them formally in Property Description XML files. Attributes include the property's data type, label, help string and more. For indexable properties, you should pay particular attention to the following property attributes found in the searchInfo XML element of the Property Description file:

Attribute Description
inInvertedIndex Optional. Indicates whether the property value should be stored in the inverted index. This lets end users perform full-text queries over string values of this property (e.g., SELECT ... WHERE CONTAINS "sometext"). The default is "false".
isColumn Optional. Indicates whether the property should be stored in the Windows Search database as a column. If true, then end users (or developers) can specify the property in the columns to return (e.g., SELECT <PropertyColumn> WHERE ...) and do comparisons on the property values (e.g., SELECT ... WHERE "<PropertyColumn>" > 1000). The default is "false".
isColumnSparse Optional. The default is "true". If the property is multi-valued, this attribute is always "true".
columnIndexType Optional. To optimize sorting and grouping, the Windows search engine can create secondary indexes for properties that have isColumn="true". If the property tends to be sorted frequently by users, this attribute should be specified. This attribute is only useful when isInvertedIndex="true". The default is "NotIndexed". The following values are valid.
  • NotIndexed: No secondary index is created.
  • OnDisk: Store the index on disk.
maxSize Optional. The max size allowed for a certain property that is stored in the Windows search database. The default is "128" (bytes).

Full-Text Support

Generally speaking, full-text search is supported by components called filters; however, for text-based file types with uncomplicated file formats, property handlers may be able to provide this functionality with less development effort. You should review the Full-Text Contents section for a comparison of filter and property handler functionality to help you decide what is best for your file type.

Note  Because property handlers cannot chunk content the way filters can, large files (even if they are uncomplicated file formats) must be completely loaded into memory.

Operating System Considerations

Prior to Windows Vista, filters provided support for parsing and enumerating file content and properties. With the introduction of the property system, property handlers now handle file properties while filters handle file content. For Windows Vista, you need develop only a partial implementation of the IFilter interface in coordination with a property handler, as described in Developing Filters for Windows Search.

While the property system is also included with the Windows Search installation for Windows XP, third-party and legacy applications may require that filters handle both content and properties. Therefore, if you are developing on the XP platform, you should provide a full filter implementation as well as a property handler for your file type or custom property.

Writing Property Description Files

The structure of property description XML files (.propdesc) is described in the propertyDescription topic. Of particular interest for search are the attributes of the searchInfo element. Once you've decided which properties to support, you need to create and register property description files for your properties. When you register your .propdesc files, they are included in the schema's property description list and become column names within the Search engine's property store.

You can register your custom property descriptions using the PSRegisterPropertySchema function, a wrapper API that calls the schema subsystem's IPropertySystem::RegisterPropertySchema. This function informs the schema subsystem of the addition of property description schema (.propdesc) files, using file path(s) to the .propdesc file(s) on the local machine, usually the application's install directory under "Program Files". Typically, a setup or application (e.g., your property handler installer) will call this method after installing the .propdesc file(s).

Implementing Property Handlers

Implementing a property handler involves the following interfaces:

  • IInitialzeWithStream: Provides stream-based initialization of your property handler.
  • IPropertyStore: Enumerates, gets, and sets property values.
  • IPropertyStoreCapabilities: Optional. Identifies whether users can edit a property from a user interface.

IInitializeWithStream

As described in the Property System topic, we strongly recommend implementing property handlers with IInitializeWithStream to do stream-based initialization. If you chose not to implement IInitializeWithStream, the property handler must opt out of running in the isolated process by setting the DisableProcessIsolation flag on the property handler's registry key. Disabling process isolation is generally intended only for legacy property handlers and should be strenuously avoided by any new code.

IPropertyStore

To create a property handler, you must implement the IPropertyStore interface:

Method Description
Commit Saves a property change to the file.
GetAt Retrieves a property key from an item's array of properties.
GetCount Gets the number of properties attached to the file.
GetValue Retrieves data for a specific property.
SetValue Sets a new property value or replaces or removes an existing value.

Important considerations for implementing this interface are included in the IPropertyStore documentation and therefore won't be repeated here. If your property handler emits multiple values for the same property for a given item, only the last value emitted is stored in the catalog.

IPropertyStoreCapabilities

Property handlers can optionally implement this interface to disable a user's ability to edit specific properties. These properties are normally editable in the Details page and pane but editing them is not allowed under the implementing property handler. Implementing this interface correctly provides a better user experience than the alternative—a simple run-time error from the Shell.

Installing and Registering Property Handlers

With the property handler implemented, it must be registered and its file extension associated with the handler. The following example shows the registry keys and values required to do this.

HKEY_CLASSES_ROOT

CLSID

{<CLSID for property handler>}

(Default)= <Property Handler Name>

  • InProcServer32

HKEY_LOCAL_MACHINE

SOFTWARE

Microsoft

Windows

CurrentVersion

PropertySystem

PropertyHandlers

  • <.fileextention>

Shell Extensions

  • Approved

Testing Property Handlers

The following list provides advice on the kinds of tests you should perform:

  • Test getting output from every single property supported by the file type.
  • Use big property values, for example, use a large metatag in HTML documents.
  • Check that the property handler does not leak file handles by editing it after getting output from the property handler, or by using a tool like oh.exe before and after enumerating file properties.
  • Test all file types associated with the property handler. For example, check that the HTML filter works with .htm and .html file types.
  • Test with corrupted files. Property handler should fail gracefully.
  • If an application supports encryption, test that the property handler does not output encrypted text.
  • If your property handler supports full-text search:
    • Use multiple special Unicode characters in the file contents and test for their output.
    • Make sure output chunks are marked with the right LCID if the property handler supports multiple languages. Test all languages supported by the property handler.
    • Test the handling of very large documents to ensure the property handler works as expected.

Setup Tests

Lastly, you need to test your install and uninstall routines.

  • Installation must recover from failed installations (e.g., from canceling and then restarting setup).
  • Uninstall must delete all files associated with the property handler.
  • Uninstall must not delete files other than the ones associated with the property handler installation.
  • Registry keys associated with the property handler must be removed when uninstalled.
  • Uninstall must work even if files are deleted from the installation directory.