Click here to Skip to main content
15,867,686 members
Articles / Programming Languages / C#
Article

Adding custom property pages to Outlook 2003 using C#

Rate me:
Please Sign up or sign in to vote.
4.67/5 (16 votes)
30 Nov 20043 min read 128K   884   48   24
How to create custom property pages and add those to Outlook 2003

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.

C#
applicationObject.OptionsPagesAdd +=
new ApplicationEvents_11_OptionsPagesAddEventHandler(
  applicationObject_OptionsPagesAdd);
private void applicationObject_OptionsPagesAdd(PropertyPages Pages){}
C#
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.

C#
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

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

The PropertyPage Interface expects us to implement three methods:

  • public bool Dirty
  • C#
    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.

C#
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.

C#
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.

C#
[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:

C#
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.

C#
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.

License

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


Written By
Germany Germany
Feel free to visit my blog at www.hannes-pavelka.com

Comments and Discussions

 
GeneralSame thing for Visual Basic Pin
Member 1235435617-Jul-21 1:33
Member 1235435617-Jul-21 1:33 
QuestionEnhance post with some images Pin
deostroll11-Jun-15 20:29
deostroll11-Jun-15 20:29 
GeneralGetting PropertyPageSite Pin
Jon Webb19-Nov-09 8:13
Jon Webb19-Nov-09 8:13 
GeneralRe: Getting PropertyPageSite Pin
Jon Webb20-Nov-09 7:54
Jon Webb20-Nov-09 7:54 
GeneralThanks you Pin
dusna27-Jan-09 2:25
dusna27-Jan-09 2:25 
GeneralApplying Themes to the PropertyPage Pin
Pavelsua28-May-08 22:21
Pavelsua28-May-08 22:21 
GeneralCannot add message boxes to property pages Pin
Vimzz8-May-08 23:03
Vimzz8-May-08 23:03 
GeneralRe: Cannot add message boxes to property pages Pin
digicate2-Apr-12 17:32
digicate2-Apr-12 17:32 
QuestionHow to add custom property pages to PowerPoint 2003 and 2007 using C# ? Pin
Darwin DeVore2-May-08 19:59
Darwin DeVore2-May-08 19:59 
Questioncan't get example to work - what am i doing wrong? Pin
a332188949527-Jul-07 13:31
a332188949527-Jul-07 13:31 
AnswerRe: can't get example to work - what am i doing wrong? Pin
Member 301209527-Feb-09 13:26
Member 301209527-Feb-09 13:26 
QuestionDisplaying custom propety Pin
A. Bhandari a.k.a Amit Bhandari2-Jul-07 2:29
A. Bhandari a.k.a Amit Bhandari2-Jul-07 2:29 
NewsError : The operation Failed Pin
prakash.guru2-Jun-07 4:59
prakash.guru2-Jun-07 4:59 
GeneralRe: Error : The operation Failed Pin
MOLBERG21-Jul-07 21:31
MOLBERG21-Jul-07 21:31 
QuestionError while calling OnStatusChange() Pin
codebased4-Apr-07 20:09
codebased4-Apr-07 20:09 
AnswerRe: Error while calling OnStatusChange() Pin
PeterClark20-Nov-08 7:54
PeterClark20-Nov-08 7:54 
QuestionHow do i read digital signature? Pls. help Pin
ay-ay17-Jan-07 16:31
ay-ay17-Jan-07 16:31 
Generalconvert to vb [modified] Pin
tap5238420-Sep-06 20:46
tap5238420-Sep-06 20:46 
GeneralProblem!!! Please help Pin
DLL_hell11-Jul-06 22:29
DLL_hell11-Jul-06 22:29 
GeneralClose Options Page Pin
HakunaMatada28-Oct-05 23:37
HakunaMatada28-Oct-05 23:37 
Thanks to you wonderful article, I was able to add the options page to Outlook. But I got a small problem. I have a button on the user control which opens a "Compose Email" window. When I try to do this, an exception is thrown saying a dialog is already open. Is there any way to close the Options page through code or any other way to display the "Compose Email Window"? Smile | :)

Bikash Rai
GeneralWhen Deploy it in other machines... Pin
tmg_20009-Jul-05 22:22
tmg_20009-Jul-05 22:22 
GeneralSetting the background colour Pin
mball16-Feb-05 23:00
mball16-Feb-05 23:00 
GeneralRe: Setting the background colour Pin
David Wulff15-May-05 14:40
David Wulff15-May-05 14:40 
QuestionRe: Setting the background colour Pin
ahardy9-Oct-06 18:29
ahardy9-Oct-06 18: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.