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

Add-in Express Home > Add-in Express for 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 applied 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.

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)

Notes!
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.

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

• Sample Outlook plug-in in VSTO
• Components for Outlook plug-ins, ribbons, keyboard shortcuts
• How To for Outlook plug-ins

Back to Add-in Express for VSTO homepage