Displaying a custom Thumbnail in the shell

The next thing that I wanted to do was to have a Thumbnail display in the shell for “Electronic Cookbook” files. My goal was to have each recipe file show an image of its recipe item. I’d never done this before and I didn’t know quite where to begin. I began an online search using the term “Thumbnail” and I discovered new API’s specific to Windows Vista that made creating custom thumbnails quite easy. In my search I also turned up a simple working sample in Mike Taulty’s Blog, which I based my sample on.


Vista shell enhancements

Mike’s blog was more than I had hoped for and was exactly what I needed. It also helped me to uncover the 3 ways that a file-type can take advantage of the new Vista shell.

Ø  ThumbnailProvider: This allows the implementer to define a custom image that explorer displays. (calls to this run out-of-process, making it safe to program against with .NET)

Ø  PreviewHandler: This allows the implementer to create a custom preview in the explorer. (Calls to this are made out-of-process, making it safe to program against with .NET)

Ø  PropertyHandler: This enables a file-type to surface its properties (pre-defined and custom) in the explorer, readable and optionally writable in the property pages or in the preview pane. (right-click->properties) (Calls to this are made in-process with shell explorer process, so it is not .NET safe. See next paragraph.)

Ø  See the Windows SDK C++ samples that show implementing these 3 features at: (\Program Files\Microsoft SDKs\Windows\v6.0\Samples\WinUI\Shell\AppShellIntegration).


.NET developers beware of PropertyHandlers

Incidentally, to save you from wasting valuable time, a PropertyHandler should not be implemented directly using the .NET Framework since the shell makes in-process calls to the PropertyHandler implementation. Much to my dismay, this was not mentioned in the MSDN docs (online or off) and so I found out the hard way after a week of work. Here’s the problem: The Explorer process does not check, and is not aware of, which version of the .NET framework it is loading. Therefore, there is no way to guarantee that the implementation will work, since it could be written in any version of the framework (.NET 1.0, 1.1, 2.0, 3.0 etc.). It actually works if there is only one version of the framework installed on the machine, but shipping an app that assumed this would be irresponsible. One potential workaround for this is to write a C++ PropertyHandler which then makes “out-of-process” calls to a .NET written PropertyHandler implementation. This was a bit more work than I had bargained for. The alternative, of course, is to write a PropertyHandler in pure C++ that parses the XML file and read/writes to the XML file. It looks as though I am going to need to do this, so I need to sharpen up my C++ skills.


XPS as an alternative for writing a PropertyHandler?

I was chatting in the hall with someone on our greater team, about the goals of this recipe application, and I learned that XPS (XML paper specification) files have 2 out of 3 of Vista shell capabilities built-in: the PropertyHandler and ThumbnailProvider. I went and talked to Doug Mahugh our resident XPS expert, and he showed me that XPS files can contain custom payloads. This means that XPS files can contain a print layout as well as proprietary data, and both are independent of each other and the proprietary data is preserved when the document is updated. The custom data will not surface in the XPS viewer. This can be very useful. My thought was to use XPS files to contain recipes, and get a PropertyHandler and ThumbnailProvider for free, but for my specific case this ended up not being an optimal solution since XPS files are already associated with the XPSViewer. Eventually I am going to write an application to open “Electronic Cookbook” files and I don't wish to launch the XPSViewer when opening ECB files. Still though, XPS files will be very useful for printing and archiving purposes. More on this later.



Incidentally, XPS conforms to Open Packaging Conventions (OPC specification.)  XPS files are self-contained zip files that house content and relationships between that content.  .NET 3.0 has nifty API’s that can access, manipulate, digitally sign and print these XPS files. Note that if you are manually manipulating an XPS file, you need to be aware that the contents are case sensitive (that threw me off). See more about XPS. Additionally Microsoft Office 2007 has implemented the Word, Excel and PowerPoint file-types as OPC implementations (e.g. .docx, .pptx, and .xlsx), and so they behave very similarly to XPS files.


In the next blog I will discuss the ECB ThumbnailProvider implementation.