Designers for COM add-ins, RTD servers, smart tags
Excel Automation add-ins, XLL in C#, VB.NET, C++

Add-in Express™
for Microsoft® Office and .net

Add-in Express Home >

Add-in Express .NET designers

There are several Add-in Express designer types responsible for common tasks in automating Microsoft Office 2010 - 2000 in .NET (C#, VB.NET, C++). Add-in Express installs a number of items to the New Project dialog as well as to the Add New Item dialog in order to allow creating the following customization types:

New Project dialog

Add-in Express adds several project templates to the Extensibility folder of the New Project dialog in Visual Studio. To see the dialog, choose File | New | Project… in the main menu.

New Project dialog in Add-in Express

Whichever Add-in Express project template you choose, it starts a project wizard that allows selecting a programming language for your project, interop assemblies to use as well as other options. The project wizard creates a new solution containing an appropriate Add-in Express project.

Each Add-in Express project contains an appropriate designer class also called "module": add-in module, XLL module, RTD server module, etc. Project-specific modules are the core components of Add-in Express. You can add any components onto the modules. Add-in Express provides a number of components that simplify and speed up the development of Office extensions, see Add-in Express components.

Add New Item dialog

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

Add New Item dialog in Add-in Express

  • Add-in Express Excel Task Pane – a form designed for being embedded into Excel windows. See Excel task panes.
  • Add-in Express Outlook Form - a form designed for being embedded into Outlook Explorer and Inspector windows. See Advanced Outlook regions.
  • 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.
  • COM Add-in Module - the core of any Add-in Express COM add-in.
  • Excel Worksheet Event Class - provides easy access to the events of the Worksheet class.
  • XLL Add-in Module - allows developing user-defined functions in Excel. See Excel XLL Add-ins and UDF tips.
  • XLL Add-in Additional Module - it is an additional XLL add-in module. See How to develop the modular architecture of your COM and XLL add-in.
  • COM Add-in Additional Module - it is an additional add-in module.
  • Word Document Module - allows handling events of any MS Forms controls placed on a specified Word document. See Word documents.
  • ClickOnce Module - allows accessing ClickOnce-related features in ClickOnce deployment.
  • Outlook Property Page - the form designed for extending Outlook Options and Folder Properties dialogs with custom pages. See Outlook property page.
  • Outlook Items Event Class - provides easy access to the events of the Items class of Outlook (see Event Classes).
  • Outlook Folders Event Class - provides easy access to the events of the Folders class of Outlook.
  • Outlook Item Event Class - provides easy access to the events of the MailItem, TaskItem, ContactItem, etc classes of Outlook.
  • COM Excel Add-in Module - this module allows implementing user-defined functions in Excel. See Excel Automation Add-ins.
  • Excel Worksheet Module - allows handling events of any MS Forms controls placed on a specified Excel worksheet. See Excel Workbooks.
  • Excel Worksheet Event Class - provides easy access to the events of the Worksheet class.
  • XLL Add-in Module - allows developing user-defined functions in Excel.
  • XLL Add-in Additional Module - it is an additional XLL add-in module.

COM add-ins

COM add-ins have been around since Office 2000 when Microsoft allowed Office applications to extend their features with COM DLLs supporting the IDTExtensibility2 interface (it is a COM interface, of course). Since then thousands of developers have racked their brains over this interface and the Office object model that provided COM objects representing command bars, command bar controls, etc. These were the sources of Add-in Express.

Why COM add-ins?

COM add-ins is the only way to provide new or re-use built-in UI elements such as command bar controls and Ribbon controls. Say, a COM add-in can show a command bar or Ribbon button to process selected Outlook e-mails, Excel cells, or paragraphs in a Word document and perform some actions on the selected objects. A COM add-in supporting Outlook, Excel, Word or PowerPoint can show custom task panes in Office 2007 and higher and Add-in Express panes in Office 2000-2010, see Task panes. In a COM add-in targeting Outlook, you can add custom option pages to the Tools | Options and Folder Properties dialogs (see Step 14. Adding property pages to the Folder Properties dialog). A COM add-in also handles events and calls properties and methods provided by the object model of the host application. For instance, a COM add-in can modify an e-mail when it is being sent; it can cancel saving an Excel workbook; or, it can check if a Word document meets some conditions.

Per-user and per-machine COM add-ins

A COM add-in can be registered either for the current user (the user running the installer) or for all users on the machine. That's why the corresponding module type, ADXAddinModule, provides the RegisterForAllUsers property. Registering for all users means writing to HKLM and that means the user registering a per-machine add-in must have administrative permissions. Accordingly, RegisterForAllUsers = Flase means writing to HKCU (=for the current user). See also Registry keys.

An add-in deployed via ClickOnce can be registered with HKCU only. See also ClickOnce deployment.

A standard user may turn a per-user add-in off and on in the COM Add-ins dialog. You use that dialog as well as the {host application} | Options | Add-ins dialog in Office 2007-2010 to find if your add-in is active.

Creating a COM Add-in project

To create a COM add-in, choose the Add-in Express COM Add-in project template in the New Project dialog. The core of the project is the add-in module, of the ADXAddinModule type. The add-in module represents a COM add-in in any Office application. To add another add-in to your assembly, add another add-in module to your project (see Add New Item dialog). For the add-in, you specify its name, host application(s) and load behavior.

The typical value for the LoadBehavior property is Connected & LoadAtStartup. That value is written to the registry when you register the add-in.

For Outlook add-ins, you also specify pages for the Tools | Options and Folder Properties dialogs (see Outlook Property page).

See also what Add-in Express components you add onto add-in modules. Pay attention to the AddinExpress.MSO.ADXAddinModule.CurrentInstance method (it's static in C#, Shared in VB.NET); it allows accessing public properties and method outside of the module. Use the AddinStartupComplete and AddinBeginShutdown events to handle add-in startup and shutdown.

Here you can find two sample add-in projects: sample Excel add-in project and sample Outlook add-in project.

What's next?

You need to study the following areas before implementing the business logic of your add-in:

RTD servers

RTD Server is a technology introduced in Excel 2002 (XP). An RTD server is used to provide the end user with a flow of changing data such as stock quotes, currency exchange rates etc. If an RTD server is mentioned in a formula (placed on an Excel worksheet), Excel loads the RTD server and waits for new data from it. When data arrive, Excel seeks for a proper moment and updates the formula with new data.

RTD server terminology:

  • RTD server is a Component Object Model (COM) Automation server that implements the IRtdServer interface. Excel uses the RTD server to communicate with a real-time data source on one or more topics.
  • Real-time data source is any source of data that you can access programmatically.
  • Topic is a string (or a set of strings) that uniquely identifies a piece of data that resides in a real-time data source. The RTD server passes the topic to the real-time data source and receives the value of the topic from the real-time data source; the RTD server then passes the value of the topic to Excel for display. For example, the RTD server passes the topic " New Topic" to the real-time data source, and the RTD server receives the topic's value of "72.12" from the real-time data source. The RTD server then passes the topic's value to Excel for display.

Per-user and per-machine RTD Servers

An RTD Server can be registered either for the current user (the user running the installer) or for all users on the machine. That's why the corresponding module type, ADXRTDServerModule, provides the RegisterForAllUsers property. Registering for all users means writing to HKLM and that means the user registering a per-machine RTD server must have administrative permissions. Accordingly, RegisterForAllUsers = Flase means writing to HKCU (=for the current user).

Creating an RTD server

To create an RTD server, choose Add-in Express RTD Server in the Add New Item dialog. The project designer type is ADXRtdServerModule (RTD server module). The only Add-in Express component allowed for this designer is RTD Topic. The module provides the Interval property that indicates the time interval between updates (in milliseconds).

You refer to an existing RTD Server using the RTD worksheet function in Excel:

=RTD(ProgID, Server, String1, String2, ... String28)

The ProgID parameter is a required string value representing the programmatic ID (or ProgID - see What is ProgID) of the RTD server. See attributes of the RTDServerModule class for the ProgID of your RTD Server. The current version of Add-in Express requires the Server parameter to be an empty string. Use two quotation marks (""). The String1 through String28 parameters allow specifying topics of the RTD server. Only the String1 parameter is required; the String2 through String28 parameters are optional. The actual values for the String1 through String28 parameters depend on the requirements of the real-time data server.

What's next?

Please see RTD Topic and a sample RTD server project. Also, find useful information in How to get actual parameters of the RTD function when using an asterisk in the string## properties of a topic? and Inserting the RTD function in a user-friendly way.

Smart tags

Office XP bestowed Smart Tags upon us in Word and Excel. Office 2003 added PowerPoint to the list of smart tag host applications. This technology provides Office users with more interactivity for the content of their Office documents. A smart tag is an element of text in an Office document having custom actions associated with it. Smart tags allow recognizing such text using either a dictionary-based or a custom-processing approach. An example of such text might be an e-mail address you type into a Word document or an Excel workbook. When smart tag recognizes the e-mail address, it allows the user to choose one of the actions associated with the text. For e-mail addresses, possible actions are to look up additional contact information or send a new e-mail message to that contact.

Note. Smart tags are deprecated in Excel 2010 and Word 2010. Although you can still use the related APIs in projects for Excel 2010 and Word 2010, these applications do not automatically recognize terms, and recognized terms are no longer underlined. Users must trigger recognition and view custom actions associated with text by right-clicking the text and clicking the Additional Actions on the context menu. Please see Changes in Word 2010 and Changes in Excel 2010.

ADXSmartTagModule lies at the base of the Add-in Express Smart Tags. It represents a set or a library of smart tag recognizers in Excel, Word, and PowerPoint. The only Add-in Express component you add to the designer is Smart Tag.

To create a smart tag, choose Add-in Express Smart Tag in the New Project dialog. ADXSmartTagModule, smart tag module, constitutes the base of Add-in Express smart tags. It represents a set or a library of smart tag recognizers in Excel, Word, and PowerPoint. The only Add-in Express component you add to the designer is Smart Tag. See how to build smart tags for Word and Excel.

Excel UDFs

Excel UDFs are used to build custom functions in Excel for the end user to use them in formulas. This definition underlines the main restriction of an Excel UDF: it must return a result that can be used in a formula - not an object of any given type but a number, a string, or an error value (Booleans and dates are essentially numbers). When used in an array formula, the UDF must return a properly dimensioned array of values of the types above.

There are two Excel UDF types: Excel Automation add-ins and Excel XLL add-ins. They differ in several ways: see What Excel UDF type to choose?

Excel Automation add-ins

Excel 2002 brought in Automation Add-ins - a technology that allows writing user-defined functions for use in Excel formulas. Add-in Express .NET provides you with a specialized module, COM Excel Add-in Module, that reduces this task to just writing one ore more user-defined functions. A typical function accepts one or more Excel ranges and/or other parameters. Excel shows the resulting value of the function in the cell where the user calls the function.

To create an Excel Automation add-in, create a COM add-in project (see COM Add-ins) and choose COM Excel Add-in Module in COM Add-in in the Add New Item dialog. This adds an ADXExcelAddinModule (Excel add-in module) to the COM add-in project. The module represents an Excel Automation add-in. It does not provide any properties. See how to create Excel Automation Add-in step-by-step.

Excel XLL add-ins

An XLL is a DLL written in such a way that Excel can open it directly. Like Excel Automation add-ins, XLL add-ins are mostly used to create user-defined functions, however they do it much faster. This technology was introduced in Excel 4.0; Wikipedia states that this happened in 1992! Since then, XLL interfaces have been available for C and C++ developers only. Now, Add-in Express hides XLL complexities for .NET developers.

To create an XLL add-in, choose Add-in Express XLL Add-in in the New Project dialog. The project designer class is ADXXLLModule (XLL add-in module). The module contains a special class, XLLContainer, where you add your public static (in VB, Public Shared) functions. Just adding a function is enough for a quick start. Using the module's designer, you are able to specify all other function-related stuff: description, help reference, category, descriptions of the function's parameters, etc. In addition, you can instruct Excel to call your function whenever recalculation is required (IsVolatile property). Another option is specifying the AcceptAsArray property that allows accepting an Excel range passed to your UDF as a 2D array of values or as a reference to an object of the ADXExcelRef type. See a sample XLL add-in project.

What Excel UDF type to choose?

Excel Automation add-ins are supported starting from Excel 2002; Excel XLL add-ins work in Excel 2000 and higher. Automation add-ins are suitable if your UDF deals a lot with the Excel object model; XLL add-ins are faster in financial and mathematical calculations. Note however that native code XLL add-ins work faster than managed UDFs.

Information below applies to the Add-in Express implementation of Excel Automation add-ins and XLL Add-ins.

  • Due to a bug in the 64-bit version of .NET Framework 2.0, your XLL add-ins developed in .NET Framework 2.0, 3.0 or 3.5 will crash Excel 2010 64-bit; the workaround is to use .NET Framework 4.0. Excel Automation add-ins aren't affected by this issue.
  • When developing a combination of Excel extensions (see Developing multiple Office extensions in the same project), Add-in Express loads all of them into the same AppDomain. The only exception is the Excel Automation Add-in, which is loaded into the default AppDomain. You can bypass this by calling any public method of your Excel Automation add-in via ExcelApp.Evaluate(...) before Excel invokes the Automation add-in. ExcelApp.Evaluate(...) returns an error code if the Automation add-in isn't loaded; if it is the case, you need to call that method later, say in WorkbookActivate. We assume, however that this approach will not help in the general case. There's no such problem with XLL add-ins; they always load into the AppDomain shared by all Office extensions in your assembly.
  • An XLL add-in doesn't show the description in some situations. The description of an Automation add-in is taken from the ProgId attribute applied to the Excel Add-in Module (of the ADXExcelAddinModule type). According to Microsoft, ProgId is limited to 39 characters and can contain no punctuation other than a period.
  • In an Automation add-in, neither functions nor their arguments can have a description. For an XLL add-in, see Step 4.Configuring UDFs. See also My XLL Add-in doesn't show descriptions.
  • You cannot hide a function in an Automation add-in. Moreover, in the Insert Function dialog, the user will see all public functions exposed by ADXExcelAddinModule, such as GetType and GetLifetimeService.In an XLL add-in, you hide a function by setting ADXExcelFunctionDescriptor.IsHidden=True.
  • Only functions (=methods returning a value) are acceptable in an Automation add-in. An XLL add-in may contain a procedure (=method, the return type of which is void); you can hide it in the UI (see above) and call it from say, a COM add-in, via ExcelApp.Evaluate(...).
  • XLL add-ins provide access to low-level Excel features through the ADXXLLModule.CallWorksheetFunction method; this method is a handy interface to functions exported by XLCALL32.DLL. No such feature is available for Automation add-ins.
  • Automation add-ins cannot modify arbitrary cells; XLL add-ins may do this, see Can an Excel UDF Modify Multiple Cells?

Excel workbooks

Sometimes you need to automate a given Excel workbook (template). You can do it with ADXExcelSheetModule that represents one worksheet of the workbook. The Document property allows creating and browsing for the workbook. If you choose creating a new workbook, the dialog appears where you specify the name and location of the workbook as well as the Property Name and Property Value textboxes. Add-in Express adds this property to the list of custom properties of the workbook and uses the name and value of the property in order to recognize the workbook. Accordingly, you specify the PropertyId and PropertyValue properties of the module. The module provides a full set of events available for an Excel workbook. For the Add-in Express components available for the module see the following chapters: Command Bars: toolbars, menus, and context menus and Application-level events. More about customizing Excel workbooks.

Note. There is a sample project for this module type. It is called TimeSheet. Together with other sample projects, it can be downloaded here.

Word documents

To automate a given Word document, you use the ADXWordDocumentModule. The module allows creating and browsing for the document. If you choose creating a new document, the dialog appears where you specify the name and location of the document as well as the Property Name and Property Value textboxes. Add-in Express adds this property to the list of custom properties of the document and uses the name and value of the property in order to recognize the document. Accordingly, you specify the PropertyId and PropertyValue properties of the module. The module provides a full set of events available for Word document.

Note. There is a sample add-in for Word for this module type. It is called WordFax. Together with other sample projects, you can download it from the HowTo section.
See Also