How to build COM add-in in Visual Studio .NET.
Tips about PIAs, Vista, Excel Automation - C#, VB.NET.

Add-in Express Home > Add-in Express.NET > Online Guide > COM add-in tips

COM add-in tips

You might have an impression that building add-ins is a very simple task. Please don't get too enthusiastic. Sure, Add-in Express .NET makes embedding your code to Microsoft Office applications very simple, but you are to write the applied code yourself. On this page you will find some tips and tricks related to building Office add-ins in Visual Studio .NET: VB, C#, C++, using version-independent PIAs, installing your add-in on Vista etc.

Add-in Express uses interfaces from the Office Type Library. We do not describe them here. Please refer to the VBA help and application type libraries.

Project wizard options

The Isolation group box in the Add-in Express project wizard allows choosing the shim to be used with your add-in. To understand shims, see Deploying Add-in Express projects.
Check the "Configure the setup project for the standard user" checkbox, for your add-in to be installed by a non-admin user – it disables the "Everyone / Just Me" choice in the setup UI and targets the DefaultLocation property of the setup project to [AppDataFolder] instead of [ProgramFilesFolder]. If you check the "Enable UAC for the setup on Vista" checkbox, the setup will require administrative privileges to be asked, when run by a non-admin user on Vista. For VS2003 developers, these features are available with the following command lines:

%AddinExpressInstallFodler%\Bin\DisableUAC.exe %BuiltOuputPath% /UAC=On
%AddinExpressInstallFodler%\Bin\DisableUAC.exe %BuiltOuputPath% /UAC=Off 

They emulate checking the "Configure for the standard user" and checking/clearing the "Enable UAC" checkboxes. % BuiltOuputPath% specifies the path and file name of the MSI.
"Add the Primary Interop Assemblies to the Project" adds a currently installed PIA(s) (see What are PIAs?) to the project. "Use Version-neutral Office PIAs" adds the PIAs supplied with Add-in Express installation package (see Why version-neutral PIAs?).

User Account Control (UAC) on Vista

The User Account Control (UAC) must be turned on for the Office 2007 add-in installed to HKCU (for the current user account only) to work. For instance, if UAC is turned on, the user can turn the add-in on / off via the COM Add-ins dialog. Otherwise, Office 2007 will show your add-in in this dialog but will not load the add-in.

.NET Framework 1.1 and 2.0 installed on the development PC

In a mixed .NET Framework environment, you may need to use the Host Configuration command of an ADX Module. This command [creates and] changes the configuration file for your host application. The examples of configuration file names are outlook.exe.config and excel.exe.config. The file is located in C:\Program Files\Microsoft Office\OFFICE11.

Add New Item dialog

Add-in Express .NET installs the following items to the Add New Item dialog (right-click on your project item in Solution Explorer and choose the Add New Item menu).

• Add-in Express Outlook Form – a form designed for being embedded into Outlook Explorer and Inspector windows. This item is available in Standard and higher Add-in Express .NET packages.
• COM Add-in Additional Module – it is an additional add-in module. Indeed. It will supplement your main module in case it has grown up too big in size.
• Outlook Property Page – the form designed for extending Outlook Options and Folder Properties dialogs with custom pages. See Outlook Property page and How to develop your first Microsoft Outlook COM add-in.
• Outlook Folders Event Class – provides easy access to the events of the Folders class of Outlook (see Add-in Express Event classes).
• COM Excel Add-in Module – this module allows implementing the functionality of the Excel Automation Add-in. You may need it only if you want to add new functions that can be used in Excel formulas.
• Excel Worksheet Event Class – provides easy access to the events of the Worksheet class.
• COM Add-in Module – the core of any Add-in Express COM add-in. See COM add-ins.
• Word Document Module – allows handling events of any MS Forms controls placed on a specified Word document. See Word documents.
• Outlook Items Event Class – provides easy access to the events of the Items class of Outlook.
• Outlook Item Event Class – provides easy access to the events of the MailItem, TaskItem, ContactItem, etc classes of Outlook.
• Excel Worksheet Module – allows handling events of any MS Forms controls placed on a specified Excel worksheet.
• The current version of Add-in Express supports Excel XLL add-ins except for Excel 2007 specific feature. They will be supported in the next public version.
• Excel workbooks.

What are PIAs?

PIAs (Primary Interop Assemblies) provide the compiler with early-binding information on the host application objects, their properties, and methods. In Visual Basic 6 terms, PIAs correspond to references you set using the Project / References dialog. Office applications are almost 100% backward compatible and you can use PIAs from an earlier Office version to work with a newer one. Say, you can develop your add-in using Outlook 2000 PIA and it will work with Outlook 2007. Note, in this case, you can access Outlook 2007 features using late binding (see the InvokeMember method in MSDN). Obviously, you cannot expect the add-in developed with Outlook 2007 PIA to work with Outlook 2000: say Outlook 2000 (as well as Outlook XP and Outlook 2003) doesn't have the Explorer.Search event specified in Outlook 2007 PIA. See also a post on Add-in Express blog: Microsoft Office PIAs in your COM add-in projects.

Version-neutral interop assemblies

Add-in Express includes version-neutral PIAs for all Office applications: just check the Version-neutral PIAs checkbox in the Add-in Express Project Wizard. This will add interop assemblies for the earliest versions of your add-in's host applications. Say, if you host your add-in in Outlook, this will be Outlook 2000 PIA. And for InfoPath, this will be InfoPath 2007 PIA.

Getting help with COM objects, properties and methods

To get assistance with host applications’ objects, their properties and methods as well as help info, use the Object Browser. Go to the VBA environment (in the host application, choose menu Tools / Macro / Visual Basic Editor or just press Alt+F11), press F2, select the host application (also Office and MSForms) in the topmost combo and/or specify a search string in the search combo. Select a class/property/method and press F1 to get the help topic that relates to the object.

How to get access to the add-in's host applications

The add-in module provides the HostApplication property that returns the Application object (of the Object type) of the host application the add-in is currently running in. For your convenience, the COM Add-in project wizard adds host-related properties to the add-in module, such as OutlookApp and ExcelApp. To identify the host application, you can also use the HostName, HostType, and HostVersion properties of the module.

Commands of the Add-in module

• Add CommandBar – adds a command bar to your add-in (see Command bar: toolbars, menus, and context menus)
• Add Explorer CommandBar – adds an Outlook Explorer command bar to your add-in
• Add Inspector CommandBar – adds an Outlook Inspector command bar to your add-in
• Add Built-in Control Connector – adds a component that allows intercepting the action of a built-in control of the host application(s) (see Built-in Control Connector) 
• Add Keyboard Shortcut– adds a component that allows intercepting application-level keyboard shortcuts (see Keyboard shortcut) 
• Add Outlook Bar Shortcut Manager – adds a component that allows adding Outlook Bar shortcuts and shortcut groups (see Outlook Bar Shortcut Manager) 
• Add Outlook Forms Manager – adds a component that allows embedding custom .NET forms into Outlook windows (see Outlook Forms Manager)
• Add Ribbon Tab – adds a Ribbon tab to your add-in (see Office 2007 Ribbon components)
• Add Ribbon Command – adds a component that allows re-purposing Ribbon controls
• Add Ribbon Quick Access Toolbar – adds a component that allows customizing the Ribbon Quick Access Toolbar in your add-in
• Add Ribbon Office Menu – adds a component that allows customizing the Ribbon Office Menu in your add-in
• Add Excel Task Panes Manager – see Advanced Custom Task Panes in Excel 2000-2007
• Add Outlook Forms Manager
• Add Events – adds or deletes components that provide access to application-level events of the add-in host applications (see Application-level events) 
• Host configuration – see .NET Framework 1.1 and 2.0 Installed on the Development PC

Releasing COM objects

The list of rules is very short:

• You must never release COM objects obtained via Add-in Express properties, methods, or through event parameters.
• You must always release COM objects retrieved by you ("manually") from any COM object.

Note, just setting 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?

What is ProgId?

ProgID – Program Identifier. This is a textual name that represents a server object. It consists of the project name and the class name, like MyServer.MyClass. You find it in ProgIDAttribute of an ADX Module. For instance:

...
'Add-in Express Add-in Module
<GuidAttribute("43F48D82-7C6F-4705-96BB-03859E881E2C"), _
       ProgIdAttribute("MyAddin1.AddinModule")> _
Public Class AddinModule
    Inherits AddinExpress.MSO.ADXAddinModule
... 

Registry entries

COM Add-ins registry entries are located in the following registry branches:
HKEY_CURRENT_USER\Software\Microsoft\Office\<OfficeApplication>\AddIns\<Add-in ProgID>
HKEY_CLASSES_ROOT\CLSID\<ADX Project GUID>

FolderPath Property Value in Outlook 2000 and 2002 (XP)

This property is available in Outlook 2003 and Outlook 2007. For Outlook 2000 and 2002 (XP), use the following function to get a full folder path for a folder:

      Public Shared Function GetFolderPath(ByVal MAPIFolder As _
         Outlook.MAPIFolder) As String

         If MAPIFolder Is Nothing Then Return ""

         Dim CurrentPath As String = ""
         Do
            CurrentPath = "\" + MAPIFolder.Name + CurrentPath
            Dim Obj As Object = MAPIFolder.Parent
            'The parent of a root folder is of the Outlook.Namespace type
            If Not TypeOf Obj Is Outlook.MAPIFolder Then Exit Do
            MAPIFolder = CType(Obj, Outlook.MAPIFolder)
         Loop

         CurrentPath = "\" + CurrentPath
         Return CurrentPath
      End Function

How to develop the modular architecture of your COM and XLL add-in?

Let's suppose that your COM add-in should conditionally provide (or not provide) some feature: let's call it Feature A. You create a class library project, add an ADXAddinAdditionalModule, and implement the feature. Then you build a setup project that can, at your choice, either register the assembly using the vsdrpCOM option in the Register parameter of the assembly, or create appropriate keys in HKCU. Note that the former way requires the administrative privileges for the user. Now the class library can write the ProgID of the ADXAddinAdditionalModule into the app.config file of the add-in. When the add-in starts, it reads the app.config, creates an ADXAddinAdditionalModuleItem and adds it to the Modules collection of the ADXAddinModule class. The best place is the Initialize event of the add-in module. For instance:

Friend WithEvents FeatureA As  _
      AddinExpress.MSO.ADXAddinAdditionalModuleItem

   Private Sub AddinModule_AddinInitialize( _
      ByVal sender As Object, ByVal e As System.EventArgs) _
      Handles Me.AddinInitialize

      Dim FeatureAProgId As String = System.Configuration. _
         ConfigurationManager.AppSettings("FeatureAProgId")

      If FeatureAProgId IsNot Nothing Then
         Me.FeatureA = _
            New AddinExpress.MSO.ADXAddinAdditionalModuleItem(Me.components)
         Me.FeatureA.ModuleProgID = FeatureAProgId
         Me.Modules.Add(Me.FeatureA)
      End If
   End Sub

The same approach is applicable for the Excel XLL add-in. Just use proper class types in the sample above.

No RTD servers in EXE

Add-in Express currently supports RTD Servers in DLLs only.

Update speed for an RTD server

Microsoft limits the minimal interval between updates to 2 seconds. There is a way to change this minimum value but Microsoft doesn't recommend doing this.

See also some tips about:

• Office CommandBars and their controls
• Office 2007 ribbons
• Deploying and debugging

Note, If you didn't find the answer to your questions on this page, please see the HOWTOs section:

• VB .NET how to for Outlook, Excel, PowerPoint
• C# how to for Outlook, Excel, Word
• C++ how to for Outlook, Excel

Back to Add-in Express.NET homepage