Create VSTO add-in / plug-in, commandbar, popup menu
ribbon for Office Outlook 2010, 2007, 2003 in C#, VB.NET

Add-in Express™
for Microsoft® Office and VSTO

Add-in Express Home > Add-in Express for Office and VSTO > Online Guide > Tips on Outlook add-ins in VSTO

Developing Office add-ins in VSTO - useful tips

Don't you have an impression that creating Office add-ins in VSTO is a very simple task? Sure, Add-in Express .NET for VSTO makes embedding your code into Office applications very simple, but you should write the application code yourself, and we guess it would be something more complex than a single call of MessageBox.

Below you can find some tips on developing your Outlook add-ins, creating pop-up menus, sharing ribbon controls using Add-in Express .NET for VSTO. You may also want to download a sample Outlook plug-in with source code.

Add New Item dialog

Add-in Express for VSTO adds several new templates to this dialog:

  • Add-in Express Excel Task Pane - a form designed for being embedded into Excel windows. See Excel task panes.
  • Add-in Express Module - the core of any Add-in Express COM add-in. See Add-in Express Module.
  • Add-in Express Outlook Form - a form designed for being embedded into Outlook Explorer and Inspector windows.
  • Add-in Express PowerPoint Task Pane - a form designed for being embedded into PowerPoint.
  • Add-in Express Word Task Pane - a form designed for being embedded into Word documents.
  • Add-in Express ClickOnce Module - allows accessing ClickOnce-related features in ClickOnce deployment.
  • Outlook Options Page - the form designed for extending Outlook Options and Folder Properties dialogs with custom pages. See Outlook property page and Developig Microsoft Outlook Add-in in VSTO.
  • Outlook Items Events - provides easy access to the events of the Items class of Outlook (see Event classes).
  • Outlook Folders Events - provides easy access to the events of the Folders class of Outlook.
  • Outlook Item Events - provides easy access to the events of the MailItem, TaskItem, ContactItem, and other classes of Outlook.

Add New Item dialog

COM Add-ins dialog

In version 2007 of Word, Excel, PowerPoint and Access you click the Office Menu button, then click {Office application} options and choose the Add-ins tab. Now choose COM Add-ins in the Manage dropdown and click Go.

In Office 2003, you need to add the COM Add-ins command to a toolbar or menu of your choice. To do so, follow the steps below:

  • Open the host application (Outlook, Excel, Word, etc)
  • On the Tools menu, click Customize.
  • Click the Commands tab.
  • In the Categories list, click the Tools category.
  • In the Commands list, click COM Add-Ins and drag it to a toolbar or menu of your choice.

VSTO solution deployment

To understand the deployment of VSTO projects, please use the MSDN site. Below there are some of the links that could be of interest:

1. Deploying Office Solutions
2. Deploying Visual Studio 2005 Tools for Office Solutions Using Windows Installer (Part 1 of 2)

1. Add-in Express for VSTO adds a single assembly to your setup project. The assembly is AddinExpress.VSTO.dll. In your setup project, you should add it to the Application Folder.

2. The links were correct at the moment of writing.

Releasing COM objects

The list of rules is very short:

  • You must never release COM objects obtained through the parameters of events provided by Add-in Express.
  • You must always release COM objects retrieved by you ("manually") from any COM object.

Note, just set a variable of say, Outlook.MailItem type to null (Nothing in VB) has nothing to do with releasing its underlying COM object. To release it, you call the.Marshal.ReleaseComObject method (System.Runtime.InteropServices namespace) and pass the variable as a parameter.

You may also want to read the following article - Why Outlook is not closing when I run my add-in?

Sharing ribbon controls across multiple add-ins

First off, you assign a string value to the Namespace property of AddinModule. This makes Add-in Express to add two xmlns attributes to the customUI tag in the resulting Xml markup:

  • xmlns:default="%ProgId of your add-in, see the ProgID attribute of the AddinModule class%",
  • xmlns:shared="%the value of the AddinModule.Namespace property%".

Originally, all the Ribbon controls are located in the default namespace (id="%Ribbon control's id%" or idQ="default:%Ribbon control's id%") and you have full control over them via the callbacks provided by Add-in Express. When you specify the Namespace property, Add-in Express changes the markup to use idQ's instead of id's.

Then, in all the add-ins that should share a Ribbon control, for the control with the same Id (you can change the Id's to match), you set the Shared property to True. For the Ribbon control whose Shared property is True, Add-in Express changes its idQ to use the shared namespace (idQ="shared:%Ribbon control's id%") instead of the default one. Also, for such Ribbon controls, Add-in Express cuts out all the callbacks and replaces them with "static" versions of the attributes. Say, getVisible="getVisible_CallBack" will be replaced with visible="%value%".

The shareable Ribbon controls are the following Ribbon container controls:

  • Ribbon Tab - ADXRibbonTab
  • Ribbon Box - ADXRibbonBox
  • Ribbon Group - ADXRibbonGroup
  • Ribbon Button Group - ADXRibbonButtonGroup

When referring to a shared Ribbon control in the BeforeId and AfterId properties of another Ribbon control, you use the shared controls' idQ: %namespace abbreviation% + ":" + %control id%. The abbreviations of these namespaces are "default" and "shared" string values.

Resulting Xml markup may resemble the following one:


<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui"
          xmlns:default="MyOutlookAddin1.AddinModule"
          xmlns:shared="MyNameSpace" [callbacks omitted]>
<ribbon>
  <tabs>
   <tab idQ=" shared:adxRibbonTab1" visible="true" label="My Tab">
    <group idQ="default:adxRibbonGroup1" [callbacks omitted]>
     <button idQ="default:adxRibbonButton1" [callbacks omitted]/>
    </group>
   </tab>
  </tabs>
 </ribbon>
</customUI>

In the XML-code above, the add-in creates a shared tab, containing a private group, containing a button (private again). See also Office Ribbon UI designer.

Deploying Office add-ins

  • Make sure Vista, Windows XP, and Office have all the updates: Microsoft eventually closes their slips and blunders with service packs and other updates. Keep an eye on Visual Studio 2005 updates, too.
  • Whenever possible, include the Shared Add-in Support Update for Microsoft .NET Framework 2.0 (KB908002) to Prerequisites of your VS2005 project. On Vista, if you add-in will be installed for all users under an admin account, then the admin must run setup.exe. A Vista standard user must run msi and not setup.exe.
  • If a non-admin user will install your add-in, use [AppDataFolder] as a default location. Make sure the user is instructed to run MSI. On Vista, if the user runs setup.exe, a non-admin will get the elevation dialog and this can end with installing the add-in to the admin profile. In such a case, the add-in will not be available for the standard user.

How to get access to the add-in host applications

For your convenience, the Add-in Module provides host-related properties to the Add-in module, such as OutlookApp and ExcelApp. Also, the ThisApplication property returns the ThisApplication property of the VSTO add-in.

Show an Outlook toolbar for a given subfolder(s)

Set the FolderName property to a string like this: "Personal Folders\Inbox\My SubFolder". The toolbar will be shown for this subfolder if (and only if) the subfolder default type corresponds to the ItemTypes property value. The same approach also works if the current Outlook profile includes several PST files - just use the real folder names. To show the toolbar for a set of fixed subfolders, add their names to the FolderNames collection.

Event classes

An Event class cannot be connected to several event sources (say, Items collections of several folders). Instead, you create several instances of the Event class.

ControlTag vs Tag

Add-in Express identifies all its controls (command bar controls) through the use of the ControlTag property (the Tag property of the CommandBarControl interface). The value of this property is generated automatically and you don't need to change it. For your own needs, use the Tag property instead.

Pop-ups

According to the Microsoft's terminology, the term "pop-up" can be used for several controls: pop-up menu, pop-up button, and submenu. With Add-in Express you can create your own pop-up as a command bar control and populate it using the Controls property. But pop-ups have a very annoying feature: if an edit box or a combo box is added to a pop-up, their events are fired very oddly. Don't regard this bug as that of Add-in Express. Seems, it was introduced by MS intentionally.

How to display the commandbar as a popup (context) menu

Use the CommandBar.Position = adxMsoBarPopup option to display the commandbar as a popup (context) menu. In the appropriate event handler you write the following code:

AdxOlExplorerCommandBar1.CommandBarObj.GetType.InvokeMember("ShowPopup", _
 Reflection.BindingFlags.InvokeMethod, Nothing, _
 AdxOlExplorerCommandBar1.CommandBarObj, Nothing)

The same applies to other commandbar types.

CommandBar.Position = adxMsoBarMenuBar

This option can be used in some scenarios with Excel solutions only.

Edits, Combos, and the Change event

The Change event appears only after the control's value is changed AND the focus is shifted. This is not our bug either, but MS guys' "trick".

Built-in controls and command bars

You can connect an ADXCommandBar instance to any built-in command bar. For example, you can add your own controls to the "Standard" command bar or remove some controls from it. To do this, just add to the add-in module a new ADXCommandBar instance and specify the name of the built-in command bar you need via the CommandBarName property.

Also you can add any built-in controls to custom command bars. Just add an ADXCommandBarControl instance to the ADXCommandBar.Controls collection and specify the Id of the built-in control you need via the Id property. Pay attention please that in this case you just add the built-in control but do not handle its event excluding buttons with witch you also can disable its standard action. To handle events of other built-in controls use the ADXBuiltInControl object.

Note. Add-in Express provides additional components for COM Add-ins in Outlook. For more information, please see:

Custom task panes for Outlook and Excel <<

>> Deploying Office VSTO solutions
See Also