1.       Verify that your propdesc file(s) are in a global location

2.       Verify that you registered your propdesc file(s) using absolute paths

3.       Verify that the event log did not record any failures from registering your propdesc file.

4.       Verify that your property description is well formed, accurate, and was registered properly.

5.       Verify that your property descriptions are marked isColumn="true", isViewable="true", and isQueryable="true" as appropriate.

6.       Verify that your DLL is in a global location (e.g. not under your user profile)

7.       Verify that your DLL is registered under HKLM\Software\Classes

8.       Verify that your DLL is registered using full paths (or REG_EXPAND_SZ strings that expand to absolute paths using environment variables known by the System account)

9.       Verify that your property handler works under explorer

10.    We prefer that you use IInitializeWithStream.  If you must use IInitializeWithFile or IInitializeWithItem, verify that you specify DisableProcessIsolation

11.    Verify that the "Indexing Options" control panel lists your filetype as an indexed filetype

12.    Verify that the test file is in an indexed location

13.    Verify that the test file's has been modified since after you installed your property handler

Common Mistakes:

1.       Placing propdesc files or DLLs under a user directory

2.       Registering things with relative paths

3.       Registering things under HKCU instead of HKLM (remember that HKCR shows a merged view of the two hives)

4.       Forgetting DisableProcessIsolation for non-stream handlers

5.       The test file wasn't modified or wasn't in an indexed location

If all else fails, you can use Image File Execution Options to attach a debugger to searchindexer.exe and child processes (On Vista, I use "<pathto>\ntsd.exe -server tcp:port=8001,icfenable -gG -o -snul";  On Win7, I use: "<pathto>\ntsd.exe -server npipe:pipe=foo -gG -o -snul").   Reboot, attach to the debugger, and type "sxeld mypropertyhandler".  The debugger will break when your DLL gets loaded.  Use of debuggers is an advanced topic that I won't get into right now.

I've been reading up the issues with using .NET for property handlers. I know you can't using .NET Interop to create a property handler without getting into issues with the version of the .NET framework. I discovered though that .NET Assemblies can be registered and used as COM objects. Could one implement the required functions of IPropertyStore in c++ and then inside those functions make calls to a COM object that does all the real work?

 

I know you said that you feel property handlers should be written in c/c++ for performance reasons but would this get around the issue of the framework version issue?

This is a very good question, but the answer is "probably not". 

The reason is that property handlers cannot cause .NET code to get loaded in the caller's process which is not supported.  It has nothing to do with performance.  So you cannot get around the issue by writing a C++ stub that calls a .NET COM object in the same process.

The only thing that works is to write a C++ stub that calls a .NET class running in a different process altogether.  But that's a lot more work, introduces a lot of failure paths, may introduce subtle interactions, etc.

Raymond Chen digs into the reasons with this post:  http://blogs.msdn.com/1317290.aspx

 [Update 2007-06-04: I found another article (from 2006) which repeats this warning:  http://msdn.microsoft.com/msdnmag/issues/04/01/WindowsShell/default.aspx]

First, pick a file type.  You'll be writing a property handler for this file type.

Now decide which properties you want to store.  Properties generally fall into a few categories.  Take a moment to consider which of the following you want to support:

• System defined properties (e.g. System.Author)
• Properties you define for your filetype (e.g. MyCompany.MyApp.MyProperty)
• Properties other people define and want to set on your file (e.g. SomeoneElse.Other.Property, aka "open metadata")

Next, decide where in the file you'll be storing the properties.  Hopefully the file's format allows for this already.  If it doesn't, you'll have to collaborate with other users of this file format to accomodate these properties.  Here are a few storage options:

• Compute the property from other data in the file (e.g. System.Document.WordCount)
• Read the property from a specific location in the file (e.g. the EXIF header in certain image formats)
• Read the property from a dynamic storage structure (e.g. suitable for storing SomeoneElse.Other.Property)

And let's not forget deciding which of your properties will be viewable, editable, searchable, etc.  Better start taking notes if you haven't already!

Once you know where to place your properties, you get to decide how to format them in your file.  Will you turn them into strings?  Or would a binary format be better?  Maybe you'll want to store some properties directly in the file format and others into a special dumping ground for open metadata.

Also quite important is choosing which API you will use to write to the file format.  Hopefully it supports stream inputs.  If it doesn't you'll have to flag your handler as "legacy".  Typically you'll end up writing a small layer mapping propert keys and values to whatever the format-specific API uses.

There is one easy decision in this mix.  Choose your programming language from the following list: C++, C.  Regrettably, shell extensions cannot use the CLR, so you may not use C# or any other .NET language.

As you can see, there are a lot of little decisions you get to make when writing a property handler.  There are undoubtedly more that I've missed, but you'll stumble upon those as you prepare your handler.  Additionally, there are many little options and flags you can use to tweak the way your property handler works and to accomplish more advanced tasks.  I am skipping those for now in favor of presenting them as a list later.

-Ben Karas

Knowing what you are trying to accomplish is the first step to using the property system.  Property handlers provide a specific set of services which support specific behaviors in the Windows shell.  So let's delve into the role of a property handler and how it relates to other components.

As a data flow diagram, a property handler is pretty simple:

The input is a file stream.  The output is a set of properties.  Yup, that simple. 

Notice that although property handlers interpret files, they don't open the files themselves.  The layer above it does!  There are good reasons for this which I'll discuss another time.  To prepare the property handler, the file system namespace creates the file stream, creates the property handler, and passes the stream to the property handler via the IInitializeWithStream interface.  Once the property stack is completed, the application is free to read and write properties through the stack.  If the layers above the property handler don't answer a question, they'll pass it down to the property handler.

It is also very important to understand what property handlers do not do.  Applying a bit of logic, we can reason out much of the role a property handler plays:

• A single property handler gets created per file.  Thus...
  • A property handler must be the authority on the layout of the file stream it is handed. 
  • It is not possible to "augment" the set of properties on a file.
• The property handler must glean its properties from the file stream itself.  Thus...
  • The property system, in general, cannot store properties on every file.  Not all files allow storing properties inside them.
  • Not all properties can get written to all file types.  Bummer.
• The caller is not guaranteed to ask the property handler for properties.  This means...
  • To be considerate, the property handler should intialize quickly, delaying heavy work until it is actually needed.
• The property handler is dealing with files.  This means...
  • For large files, if you have control over the file layout, consider making it stream-friendly. 
    • Reserve extra space in the property section.
    • Clump things together so that the handler doesn't have to read the whole disk to piece together data.
• Property handlers are an extensibility point of the file system namespace.  Thus...
  • Other namespaces may have different extensibility mechanisms (or none at all).
  • Other namespaces may be able to delegate to the file system namespace when it comes to properties.  (The search results do this)
  • Other namespaces may choose to reuse the same extensibility mechanism.  (ZIP folders do this).
• Property handlers just provide values.  Thus...
  • Although they provide the data, the windows shell controls the way it gets displayed.
  • It is not directly possible to customize the way the data is visualized(1)
  • When I say "property handlers" make the shell do this or that, I really mean that the shell will do "this or that" in the presense of a property handler that provides the right set of data.

Ok, so that's a big dose of reality for one post.  Despite our best wishes, property handlers are not magic.  They provide specific functionality to enable specific behaviors.  As a reminder, the upside of the role of a property handler is that it enables the great integration with the Windows user interface.

-Ben Karas

(1) Property descriptions contain hints about how to display a value (e.g. using a stars or a text box).  Property descriptions are system-wide and therefore a handler only can set the hints for properties it introduced to the system.

In this series, I will be presenting Windows Vista functionality with a focus on the the file system namespace.  Feel free to ask questions, especially if you want to know how things work on XP or in other namespaces, since I'll otherwise ignore those topics for now.

But first, let's get some terminology out of the way. 

The Windows Shell includes the Windows user interface and also reusable bits such as the save-as and folder browser dialogs.  The shell includes things like the start menu, task bar, desktop, folder views, details pane, properties dialog, and the search UI. 

The Indexer is a service that gathers properties and full text from files and items and answers search queries.

There are also various other applications that choose to use the property system to read or write properties to files.

All these applications connect to the property system via IShellItem2::GetPropertyStore.  This API creates a bunch of components and stacks them together.

The top layer I'm calling the Coercion Layer.  It's job is to ensure that values are of the correct type by weeding out bad ones, removing duplicates from vectors, and trimming spaces from strings.

The Shell Item Layer provides a set of properties, including PKEY_SFGAOFlags.  The shell item layer sits atop the shell namespace extensibility point.  As I mentioned earlier, I will focus on one in particular: the file system namespace.

The Shell File System Namespace provides properties about files such as PKEY_Size and PKEY_ItemType.  It sits atop the property handler extensibility point.

The Property Handler is at the bottom of the stack and provides a set of properties derived from the contents of a file.  Property handlers exist only in the file system namespace.

The way to really grok this stack is to understand that each layer wraps the one below it.  When asked for a property, any given layer chooses whether to return the value itself or to ask the layer beneath it.  The property stack is really just a chain of command.

-Ben Karas

Here I've created three .book files.  This is a file type I made up last weekend, so clearly Windows cannot know how to figure out all the data on the screen above without help.  That is where a property handler comes in.  It knows about the properties that apply to each .book file and helps Windows to display this information.

In addition to displaying properties, property handlers let users edit them within the standard Windows user interface:

Property handlers also let users search for files based on the property values.  I can search for "Haunting" and Windows will show "Blindness" in the result set.  And all this can happen from within the standard Windows user interface.

So, in summary, property handlers help your file types fit better into the Windows search and organize experience.  By exposing properties directly in the Windows UI, your users can seamlessly interact with your files without having to open them in applications all the time.  When they have property handlers, your file types feel less bolted onto Windows.

-Ben Karas

The exams in an analaysis of algorithms course I took several years ago were particularly interesting.  Consisting of only one or two questions, they asked you to perform analysis on an algorithm you had probably never seen before.  Consequently, there wasn't much you could really do to prepare for the exam.

This all led to a strange incident on the first exam day.  The professor, who shall remain unnamed, was handing out the exam papers at the start of class.  As he did so, one of the students raised his hand and asked, almost seriously,  "Is this exam open book?".

The professor casually replied, "Um, sure, why not?"

:-)

Needless to say this didn't make the exam any easier.  Somehow, I miss those days.

-Ben

-Ben Karas

What I like about this service is that it is free and has a single non-annoying, unobtrusive ad that refreshes every few seconds.  Not bad!  This is especially nice with IE 7 tabs.  I can place Pandora on one tab and then continue surfing the net.  When it comes time to rate a new song, I just tab over and then tab back. 

-Ben Karas

ps.  I keep meaning to blog about how to write a property handler.  Honestly!  But I've discovered that blogging is hard if you want to talk about technical content.  Not only do I have to write a program ahead of time, but I have to research the nooks and crannies of the APIs, design a way to present it, etc.  Plus I've been working hard lately (writing documentation, working late, waiting for the Seattle buses to put their chains on, etc.).  Maybe I should just develop funny opinions which are quicker to blog?

1. propreader.exe <file>
    - Prints a list of all properties we know about the file
   
2. propwriter.exe <file> <property> <value>
    - Writes a single value
   
3. proplister.exe <file> <proplist>
    - Prints all the properties included in a proplist (e.g. System.PropList.PreviewDetails)

I've attached the code here (code.zip). 

Enjoy!

-Ben Karas

code.zip