Adding custom property pages to Outlook 2003 using C#

• Download source code - 12.9 Kb

Introduction

In this article I will explain how to add custom property pages to Outlook 2003. PropertyPages can either be added to the Outlook Options dialog box or to the folder Properties dialog box.

I assume you have a running Outlook Add-In , creating an Outlook Add-In is beyond the scope of this article. There are plenty of good articles covering this topic.

OptionsPagesAdd Event

You need to handle the OptionsPagesAdd Event to add a custom property page. This event is either raised by your application object or by your namespace object. If you want to add a custom property page to the Outlook Option dialog you have to handle the OptionsPagesAdd event from the application object, if you want to add it the folder properties dialog box you handle the event raised by the namespace object.

applicationObject.OptionsPagesAdd +=
new ApplicationEvents_11_OptionsPagesAddEventHandler(
  applicationObject_OptionsPagesAdd);
private void applicationObject_OptionsPagesAdd(PropertyPages Pages){}

NameSpace ns = applicationObject.GetNamespace("MAPI");
ns.OptionsPagesAdd +=
new NameSpaceEvents_OptionsPagesAddEventHandler(ns_OptionsPagesAdd);
private void ns_OptionsPagesAdd(
  PropertyPages Pages, MAPIFolder Folder){}

Adding a Custom property page

We will use the PropertyPages add method to add a custom property page object to the collection.

Page.Add(object page, string title);

The first parameter of the add method expects an object representing our custom property page. We create our property page by implementing the the Outlook.PropertyPage interface. Furthermore to have a convenient way of adding controls to our property page we inherit from System.Windows.Forms.UserControl.

Creating a custom property class

public class MyOptionPage : System.Windows.Forms.UserControl , 
  Outlook.PropertyPage {}

The PropertyPage Interface expects us to implement three methods:

• public bool Dirty
• public void GetPageInfo(ref string HelpFile, ref int HelpContext)
• public void Apply()

The is Dirty property returns true if the contents of your property page have been altered. Microsoft Outlook queries this property in order to decide if the Apply Button will be visible or not.

With the GetPageInfo method you can specify the Help file associated with the property page.

Within the Apply method you write the code that implements how to react on user changes. e.g. store the values to the registry, or write config files etc.

Our custom PropertyPage would now look something this. I assume you added a button to the PropertyPage. The following code is simplified for better readability. Take a look at the sourcecode for the full code.

public class MyOptionPage : System.Windows.Forms.UserControl , 
  Outlook.PropertyPage
 {
      private bool isDirty;
      public MyOptionPage()
      { InitializeComponent();
        isDirty = false;
      } 
    public bool Dirty{get{return isDirty;}}
    public void Apply() { MessageBox.Show("Hello World"); }
    private void button1_Click(object sender, System.EventArgs e)
    { isDirty = true; } 
}  

Is it working ?

We can now try to add the custom property page.

Pages.Add(new MyOptionPage(),"Hello");

Our new tab is named "Unnamed"

Even though our new tab is displayed in the property dialog , its name is set to "Unnamed". For unknown reasons the second parameter of the add Method is ignored. We need to implement a custom caption property in our MyOptionPage class to make Outlook display the desired Tab Name.

[DispId(-518)]
public string Caption
{
get{return "DEMO";}
}

You have to add using System.Runtime.InteropServices to be able to use the DispID Attribute.

Clicking the button does not enable the Apply button

Another issue we have to fix is the fact that even if press our Button and thus setting isDirty=true Outlook is not enabling the Apply Button.

According to MSDN Microsoft Outlook queries the Dirty property in response to the OnStatusChange method of a PropertyPageSite object.

Getting the PropertyPageSite object

Unfortunately the PropertyPageSite object is an unsafe private field , we have to use reflection to get access to it.

Define a member variable private Outlook.PropertyPageSite ppSite and put the following code in your Load event of you MyOptionPage class:

Type myType = typeof(System.Object); 
string assembly = 
System.Text.RegularExpressions.Regex.Replace(myType.Assembly.CodeBase, 
  "mscorlib.dll", "System.Windows.Forms.dll");
assembly = System.Text.RegularExpressions.Regex.Replace(
  assembly, "file:///", "");
assembly = System.Reflection.AssemblyName.GetAssemblyName(
  assembly).FullName;
Type unmanaged =
Type.GetType(System.Reflection.Assembly.CreateQualifiedName(
  assembly, "System.Windows.Forms.UnsafeNativeMethods"));
Type oleObj = unmanaged.GetNestedType("IOleObject");
System.Reflection.MethodInfo mi = oleObj.GetMethod("GetClientSite");
object myppSite = mi.Invoke(this, null);
this.ppSite = (Outlook.PropertyPageSite)myppSite;

Calling the OnStatusChange() method of the PropertyPage object

When the user clicks our button we now can call the OnStatusChange method after setting isDirty = false.

private void button1_Click(object sender, System.EventArgs e)
    { isDirty = true; ppSite.OnStatusChange();} 

Final Notes

Adding custom property pages to Outlook 2003 is a little tricky, mainly because of the not directly exposed PropertyPageSite object.

I hope you find the article useful and I am looking forward to your feedback.