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.
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
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:
- 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.
- 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.
- 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!
- First of all, we have a COM server which inherits and exports the needed
If you look up these COM interfaces, you will notice that marshaling has been used extensively in the definitions.
- After our COM is built and registered, when Win32 needs to show our property page, it will call
This is were we initialize our user-control, and ...
- 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:
DLGTEMPLATE structures are filled minimally. (Again, marshaling is extensively used to keep the code safe.)
- Using the
SetParent() API call, the
hWND handle to the empty dialog is set as the parent of our user-control.
- 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.
- 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.
- Our user-control contains its own message loop to handle
- Our user-control,
SheetControl, encapsulates all the needed logic. You should simply inherit, and visually design your page as usual.
- 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.
- 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
.KeepAlive() fixes this by fooling the garbage collector.
- Extending the wizards has similar concepts involved. You should be able to write the code for that yourself.
Our source is based on a Microsoft sample presented in PDC 2001, which was later removed from GOTDOTNET.