Click here to Skip to main content
13,798,308 members
Click here to Skip to main content
Add your own
alternative version


48 bookmarked
Posted 30 Nov 2004

Adding custom property pages to Outlook 2003 using C#

, 30 Nov 2004
Rate this:
Please Sign up or sign in to vote.
How to create custom property pages and add those to Outlook 2003


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

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(
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 
  • 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 , 
      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

Method is ignored. We need to implement a custom caption property in our MyOptionPage class to make Outlook display the desired Tab Name.

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


Type myType = typeof(System.Object); 
string assembly = 
  "mscorlib.dll", "System.Windows.Forms.dll");
assembly = System.Text.RegularExpressions.Regex.Replace(
  assembly, "file:///", "");
assembly = System.Reflection.AssemblyName.GetAssemblyName(
Type unmanaged =
  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

When the user clicks our button we now can call the

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.


This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


About the Author

Hannes Pavelka
Germany Germany
Feel free to visit my blog at

You may also be interested in...


Comments and Discussions

QuestionEnhance post with some images Pin
deostroll11-Jun-15 21:29
memberdeostroll11-Jun-15 21:29 
GeneralGetting PropertyPageSite Pin
Jon Webb19-Nov-09 9:13
memberJon Webb19-Nov-09 9:13 
GeneralRe: Getting PropertyPageSite Pin
Jon Webb20-Nov-09 8:54
memberJon Webb20-Nov-09 8:54 
GeneralThanks you Pin
dusna27-Jan-09 3:25
memberdusna27-Jan-09 3:25 
GeneralApplying Themes to the PropertyPage Pin
Pavelsua28-May-08 23:21
memberPavelsua28-May-08 23:21 
GeneralCannot add message boxes to property pages Pin
Vimzz9-May-08 0:03
memberVimzz9-May-08 0:03 
GeneralRe: Cannot add message boxes to property pages Pin
digicate2-Apr-12 18:32
memberdigicate2-Apr-12 18:32 
QuestionHow to add custom property pages to PowerPoint 2003 and 2007 using C# ? Pin
Darwin DeVore2-May-08 20:59
memberDarwin DeVore2-May-08 20:59 
Questioncan't get example to work - what am i doing wrong? Pin
a332188949527-Jul-07 14:31
membera332188949527-Jul-07 14:31 
AnswerRe: can't get example to work - what am i doing wrong? Pin
Member 301209527-Feb-09 14:26
memberMember 301209527-Feb-09 14:26 
QuestionDisplaying custom propety Pin
A. Bhandari a.k.a Amit Bhandari2-Jul-07 3:29
memberA. Bhandari a.k.a Amit Bhandari2-Jul-07 3:29 
NewsError : The operation Failed Pin
prakash.guru2-Jun-07 5:59
memberprakash.guru2-Jun-07 5:59 
GeneralRe: Error : The operation Failed Pin
MOLBERG21-Jul-07 22:31
memberMOLBERG21-Jul-07 22:31 
QuestionError while calling OnStatusChange() Pin
codebased4-Apr-07 21:09
membercodebased4-Apr-07 21:09 
AnswerRe: Error while calling OnStatusChange() Pin
PeterClark20-Nov-08 8:54
memberPeterClark20-Nov-08 8:54 
QuestionHow do i read digital signature? Pls. help Pin
ay-ay17-Jan-07 17:31
memberay-ay17-Jan-07 17:31 
Generalconvert to vb [modified] Pin
tap5238420-Sep-06 21:46
membertap5238420-Sep-06 21:46 
GeneralProblem!!! Please help Pin
DLL_hell11-Jul-06 23:29
memberDLL_hell11-Jul-06 23:29 
GeneralClose Options Page Pin
HakunaMatada29-Oct-05 0:37
memberHakunaMatada29-Oct-05 0:37 
GeneralWhen Deploy it in other machines... Pin
tmg_20009-Jul-05 23:22
membertmg_20009-Jul-05 23:22 
GeneralSetting the background colour Pin
mball17-Feb-05 0:00
membermball17-Feb-05 0:00 
GeneralRe: Setting the background colour Pin
David Wulff15-May-05 15:40
memberDavid Wulff15-May-05 15:40 
QuestionRe: Setting the background colour Pin
ahardy9-Oct-06 19:29
memberahardy9-Oct-06 19:29 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Permalink | Advertise | Privacy | Cookies | Terms of Use | Mobile
Web03 | 2.8.181207.3 | Last Updated 30 Nov 2004
Article Copyright 2004 by Hannes Pavelka
Everything else Copyright © CodeProject, 1999-2018
Layout: fixed | fluid