Hello Word Outlook Add-In using C#

weblogs.asp.net/.../93712.aspx

One thing I’d like to play with is extending Outlook through add-ins with C#. It’ll be a good opportunity to learn more about .NET development and the Windows tools. Plus, I can “fix” some of the things that annoy me about Outlook. I’ve been talking to Omar about this too, and hopefully we can collaborate on a few projects. We’ve been sharing a few links back and forth on getting started. It’s a bit hard to find the right information to get started, but it’s out there. I’ve compiled steps below for a “hello world” type Outlook project that I’ll be building off in the future. I hope this will be useful to others trying to get started on developing Outlook add-ins using managed code. Please let me know if I’m missing anything or have errors.

Install Primary Interop Assemblies

.NET can interface with COM code using interop assemblies. You can create these as needed by adding a reference to a COM type library. However, if you do this for the Outlook/Office type libraries, this will lead to strange problems like this. This doesn’t sound like the thing I want to find out about the hard way. The solution is to install “primary interop assemblies” that live in the GAC and will be used instead of custom generated ones. You can download PIAs for Outlook XP here. For Outlook 2003, you can go to Control Panels->Add/Remove programs and customize your installation to add them. Just choose “.NET Programmability” under the various components. They are initially set to install on first use – I don’t know what would actually trigger this. Once these are installed, adding a reference to the COM type libraries will add these “magic” versions instead of generating new versions with strange issues.

Create a Visual Studio.NET project

Create a new Visual Studio.Net project. For the project type, select Other Projects->Extensibility Projects->Shared Add-ins (who would think to look here?). This brings you through a wizard where you can select the language (C#, of course!) and which hosts to support. One cool thing you can do with the Office COM-plugins is support multiple apps with the same plugin, but I’m only interested in Outlook for now. Then, you have the chance to fill in some other random info, and your project is created. The project will have template code that implements the IDTExtensibility2 interface required to create an add-in.

Add references

We need to add references to a couple of things we’ll be using. Right-click References under the add-in project, select “Add Reference”, go to the COM tab, and select Microsoft Outlook 11.0 Object Library (or Outlook 10.0 if you are using Outlook XP). If the PIA stuff worked right, when you select it in the solution explorer, the path in the properties tab should be pointing into the GAC, not into the office folder. Next, select

“Add Reference” again, and add “System.Windows.Forms” from the .NET tab. This will let us do our “Hello World” dialog.

Flesh out code

First, we need to add a member variable. We’ll also change the type of the application object to be the Outlook type (since we’ll only support Outlook):

private Microsoft.Office.Interop.Outlook.Application applicationObject;

private object addInInstance;

private CommandBarButton toolbarButton;

Next, we’ll update OnConnection to cast to the Outlook object type, and add some logic from kb 302901 (why isn’t this in the template if it’s the right thing to do?):

public void OnConnection(object application, Extensibility.ext_ConnectMode connectMode, object addInInst, ref System.Array custom)

{    

   applicationObject = (Microsoft.Office.Interop.Outlook.Application)application;

   addInInstance = addInInst;

   if(connectMode != Extensibility.ext_ConnectMode.ext_cm_Startup)

   {

       OnStartupComplete(ref custom);

   }

}

Likewise, we’ll update OnDisconnection according to kb 302901:

public void OnDisconnection(Extensibility.ext_DisconnectMode disconnectMode, ref System.Array custom)

{

   if(disconnectMode != Extensibility.ext_DisconnectMode.ext_dm_HostShutdown)

   {

       OnBeginShutdown(ref custom);

   }

   applicationObject = null;

}

Next, when we’re done loading, we will create a toolbar button. The version in kb 302901 is more complex because it’s generalize to work in apps other than Outlook:

public void OnStartupComplete(ref System.Array custom)

{

   CommandBars commandBars = applicationObject.ActiveExplorer().CommandBars;

   // Create a toolbar button on the standard toolbar that calls ToolbarButton_Click when clicked

   try

   {

        // See if it already exists

        this.toolbarButton = (CommandBarButton)commandBars["Standard"].Controls["Hello"];

   }

   catch(Exception)

   {

       // Create it

       this.toolbarButton = (CommandBarButton)commandBars["Standard"].Controls.Add(1, System.Reflection.Missing.Value, System.Reflection.Missing.Value, System.Reflection.Missing.Value, System.Reflection.Missing.Value);

       this.toolbarButton.Caption = "Hello";

       this.toolbarButton.Style = MsoButtonStyle.msoButtonCaption;

   }

   this.toolbarButton.Tag = "Hello Button";

   this.toolbarButton.OnAction = "!<MyAddin1.Connect>";

   this.toolbarButton.Visible = true;

   this.toolbarButton.Click += new Microsoft.Office.Core._CommandBarButtonEvents_ClickEventHandler(this.OnToolbarButtonClick);

}

On shutdown, we’ll delete our toolbar button:

public void OnBeginShutdown(ref System.Array custom)

{

   this.toolbarButton.Delete(System.Reflection.Missing.Value);

   this.toolbarButton = null;

}

And, we’ll define the action when clicking the button:

private void OnToolbarButtonClick(CommandBarButton cmdBarbutton,ref bool cancel)

{

   System.Windows.Forms.MessageBox.Show("Hello World","My Addin");

}

To test it out, you build the addin project, and then the setup project. Quit Outlook, then right-click the setup project and select “Install”.  When you launch Outlook, a button named “Hello” will show up in the main toolbar. Selecting it will say “Hello World”. You can manage this add-in by going to the COM add-in dialog at Tools->Options->Other->Advanced Options->COM Add-Ins.

What’s missing

There are some steps that need to be taken to install the PIA when installing your add-in. See the steps here. That sample also has a lot of information about signing your plugin, which I’ve ignored so far.

What’s next

Next, I have to learn more about the Outlook object model and how to actually do interesting things. I also need to learn how to debug the add-ins.

Reference

General description of COM Add-Ins: msdn.microsoft.com/.../default.asp

A sample Visual Basic.NET plugin (describes the PIA stuff): msdn.microsoft.com/.../default.asp

KB 302901 (building an Office COM plugin using Visual C#.NET): support.microsoft.com

Niobe, a library for Outlook managed plug-ins (I’m not sure what you get above doing it from scratch, there isn’t much documentation): www.gotdotnet.com/.../workspace.aspx