Property Sheet Shell Extension in C#

• Download demo project with source - 123 KB

Introduction

According to the platform SDK: "OLE property pages enable an object to display its properties in a tabbed dialog box known as a property sheet. An end user can then view and change the object’s properties."

These property pages are used extensively in Windows. Examples are the tabs shown when viewing the properties of a file, or when viewing the properties of an object in Active Directory (or any other MMC in fact), or pages used in some Control Panel applets and wizards, etc.

By default, there is no support for creating these controls in the .NET Framework. Here, we present a user control that can be used for this purpose.

Background

When you select the properties of a file, Explorer looks up all the registered property pages to load for that file type in the Registry, and loads them. Equally, when you view the properties of a User in Active Directory, the MMC looks at the display-specifiers and calls all the extension pages. The technology that enables all this is COM. Traditionally, in Visual C++, you would use ATL for the COM server and the MFC CPropertyPage control for the interface. CPropertyPage is basically a CDialog (equivalent to a Form in .NET) that fills in a PROPSHEETPAGE structure.

Our goal was to write an Active Directory MMC extension in C#. This has many obvious benefits, but proved to be quite a tricky task. In this article, we will describe some of the main points involved, and present a user-control that wraps the tricky parts. It should be noted that our team has used this component successfully and commercially (including a similar control for Wizards), but our work is in no way complete, and improvements are highly welcome.

Using the Code

The sample project will add a tab-page to the properties of a .EXE file in Windows Explorer. To use the sample, just extract the program files and run INSTALL.BAT. To change the sample, you should do the following:

1. Create an inherited user control, inheriting from SheetControl. (Sheet control is a base user control class, containing all code for handling TABs and the other messages.) Your control will be the property page that will be added. Design it according to your needs.
2. The actual loading of the page happens in the SheetLoader class. You must generate a GUID for your pages, and also create a new instance of it in IShellPropSheetExt.AddPages(), as demonstrated in the sample.
3. Finally, build the DLL, and register it according to the place it is intended to be used. In our sample, install.bat does this.

Points of Interest

There are actually quite a few tricks here!

1. First of all, we have a COM server which inherits and exports the needed IShellPropSheetExt, IShellExtInit, and IDataObject interfaces. If you look up these COM interfaces, you will notice that marshaling has been used extensively in the definitions.
2. After our COM is built and registered, when Win32 needs to show our property page, it will call IShellPropSheetExt.AddPages(). This is were we initialize our user-control, and ...
3. We use a plain resource file (i.e., an empty Win32 dialog window) as a "placeholder" for our .NET Framework classes placed controls (i.e., the user control). This is how:
1. The PROPSHEETPAGE and DLGTEMPLATE structures are filled minimally. (Again, marshaling is extensively used to keep the code safe.)
2. Using the SetParent() API call, the hWND handle to the empty dialog is set as the parent of our user-control.
3. We can design this user-control as needed. The reason we create and pass our form this way is that Win32 expects a dialog, and Windows Forms aren't dialogs.
4. Setting the parent of a form to any unmanaged container except IE is officially unsupported! This causes some form events to break. For example, tab stops work almost randomly, and focus events don't get called. (I have tried adding another layer in between, but that didn't work either.) Any workaround or documentation that explains what is happening is appreciated.
5. Our user-control contains its own message loop to handle WM_NOTIFY correctly.
6. Our user-control, SheetControl, encapsulates all the needed logic. You should simply inherit, and visually design your page as usual.
7. To have Win32 show the pages, a passed pointer function (lpfnAddPage) must be called. Unfortunately, a C++ pointer function can't be marshaled as a C# delegate - it will cause a runtime error. This means we can't call lpfnAddPage in managed code! A very small C++ wrapper does this for us.
8. We are almost finished, except that as soon as AddPages() finishes, our form will be deleted by the Garbage Collector! This is because there are no active references to it. .KeepAlive() fixes this by fooling the garbage collector.
9. Extending the wizards has similar concepts involved. You should be able to write the code for that yourself. :-)

History

Our source is based on a Microsoft sample presented in PDC 2001, which was later removed from GOTDOTNET.