The Great Flying Tortoise : Property Handlers

Troubleshooting: Why isn't my property handler getting indexed?

benkaras — Tue, 24 Jul 2007 20:31:00 GMT

Having trouble getting your property handler working with the indexer? Here are some troubleshooting tips.

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.

Property handlers and .NET

benkaras — Wed, 02 May 2007 23:06:00 GMT

A reader asked:

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]

Property Handler Decisions and Preparation

benkaras — Tue, 30 Jan 2007 09:47:00 GMT

Viewed as a data flow component, a property handler has a single file stream input and outputs a one or more properties. Unfortunately, writing one requires making many decisions before you even set eyes on the code. Let's look at a few of these preparations.

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