About Microsoft Office Visio Add-ons and COM Add-ins

Article
07/11/2006

Microsoft Corporation

December 2003

Applies to:
Microsoft Office System
Microsoft Office Visio

Summary: Learn the differences between Visio add-ons (.vsl and .exe files) and COM add-ins, and the benefits and limitations of extending Visio 2003 with each. (9 printed pages)

Introduction
Visio Add-ons
Implementing an Add-on Using a .vsl File
Implementing an Add-on Using an .exe File
COM Add-ins in Visio
Summary Table Comparing .vsl Files, .exe Files, and COM Add-ins

Introduction

A Microsoft Visio solution typically combines Visio shapes and programs that model the real world and solve specific drawing problems. Programs can help create a drawing, analyze a drawing, transfer information between the drawing and an external data source, or recognize events as they occur in the application.

Microsoft Visio 2003 provides several ways for developers using Automation in their custom solutions to extend Visio, such as:

Creating Visio add-ons. Visio add-ons have been supported since Visio 2.0 and can be implemented in one of two ways: in a Visio library file (.vsl file), which is a form of dynamic-link library that is Visio-specific, or in a stand-alone executable program (.exe file).
Creating Component Object Model (COM) add-ins. Visio 2003 includes support for COM add-ins. Because most Microsoft Office 2003 applications support the COM add-in architecture, you can use the same tools and installation file formats to develop add-ins for all of your Office System applications, including Visio.
Using Microsoft Visual Basic for Applications (VBA) code that is stored with a Visio document.

This article focuses on Visio add-ons and COM add-ins, both of which are designed as programs that run external to Visio documents. By understanding the differences in how each of these programs is designed, you can make informed decisions about the type of add-on or add-in to use with your custom solution. This article does not focus on how to create solutions by writing VBA code in a Visio document's project.

Visio Add-ons

The term add-on has a specific meaning when talking about programmatically extending the Visio application.

A Visio add-on is a user-written program that is one of two file types:

A .vsl file (Visio library file), which is a standard Microsoft Windows DLL with a prescribed Visio entry point.
An .exe file, which is a stand-alone executable program.

There are three ways to have the Visio application recognize add-ons:

Publish component. Starting in Microsoft Visio 2003, you can publish your add-ons, templates, stencils and other files as components to be integrated with the Visio application. Publishing components is the preferred method of integrating add-ons and other content with Visio. It offers tighter integration with the Visio application, and better performance on add-on discovery.

The publish component functionality enables developers to include a PublishComponent table in the Microsoft Windows Installer file that they create to install content (such as add-ons, templates, stencils, or other files). Each PublishComponent table entry contains information pertaining to how a specific file to be installed should be displayed in the Visio user interface. During installation, these entries are published to the Visio registry. Visio uses this information to display the add-on in its user interface, and install on-demand or repair the file as needed.
Path discovered. The Visio application will also recognize your add-on if you add the path where these files are installed to the Visio Start-up or Add-ons paths (on the Tools menu, click Options, and then on the Advanced tab, click File Paths).

Note Install the add-ons you develop in new folders you create to contain the add-ons, and append those new folders to the Start-up or Add-ons path. Do not place the add-ons you develop into folders containing Visio content
Add method. You can also add the files to the collection of add-ons in a Visio instance using the Add method of the application's Addons collection. This option is only available programmatically.

When Visio starts, any add-on that has been component-published, or is located in the Start-up or Add-ons path, is added to the application's Addons collection. Each Addon object in the collection can be retrieved from the collection by name or index. And most importantly, each add-on has a Run method, which enables Visio to run it in response to formula evaluation or actions in the user interface.

Note Visio treats add-ons that are component-published (to the registry) as being installed from a trusted publisher; they run regardless of the specified macro security settings. However, add-ons that are path-discovered are subject to the security setting each time the Visio application loads. (To specify macro security settings, on the Tools menu, click Options, and on the Security tab, click Macro Security.)

Internally, both types of add-ons (.exe or .vsl) appear the same to the Visio add-on management services—each has a name, can be run, and can have an enabled or disabled state.

You can run any Visio add-on in the following ways:

Use the RUNADDON or RUNADDONWARGS function in a formula contained in a ShapeSheet cell. This technique is often used in ShapeSheet cells in the Events section, which are evaluated when any of the corresponding events occur in the user interface, or in the Action cell in the Actions section, which is evaluated when a user clicks the corresponding command on the shortcut menu.

For information about changes in the RUNADDON function from previous versions of Visio, see Changes in the RUNADDON Function and the AddOnName Property for Visio 2002.
Choose the add-on from the Add-Ons submenu (Tools menu).
Use the AddonName property of a Menu, MenuItem, AccelItem, or ToolbarItem object if you are using the UIObject object model.
Use the OnAction property of a CommandBarButton control if you are using the command bar object model.
Use the Target property of an Event object you create using the Add method of an EventList collection.
Use the Run method of an Addon object.

The Visio application issues no warning if an add-on has the same name as another add-on in the Add-ons path. If duplicate add-ons exist, Visio arbitrarily chooses which add-on to run when it is run by name. To verify the names of the add-ons that can be run in a Visio instance, use the following code snippet:

For each vsoAddon in Addons
    Debug.Print vsoAddon.Name
Next

If you have both a debug and release version of your add-on with the same name, you can add the full path for the debug folder or the full path for the release folder to the Add-ons path to control which version is run.

Implementing an Add-on Using a .vsl File

A Visio library file (VSL, or .vsl file) is a Visio-specific dynamic-link library (DLL) that exports a function called VisioLibMain, which is the entry point for Visio communications with the VSL.

A VSL can contain one or more add-ons. Because a VSL is required to export the VisioLibMain function, it is typically created in C or C++.

When Visio identifies a VSL that is located in the Start-up or Add-ons path, it loads the VSL and identifies the number and names of add-ons that are implemented, along with other pertinent information, for example, whether the add-on is enabled or not.

In the case of add-ons that are published using PublishComponent table entries in a Windows Installer file, Visio does not need to load them in order to determine this implementation information. This information (such as enabled state, attributes, and so on) is specified in the PublishComponent table entry for the file, and is added to the registry when the add-on is installed. Visio does not load component-published add-ons until they are called.

Before Visio runs a specific add-on, it sends a message to the VSL (to VisioLibMain).

You can prevent an add-on contained in a VSL from appearing on the Add-Ons submenu by setting a flag in the atts field in VAOREGSTRUCT. This structure, and additional definitions that determine the interface between Visio and a VSL, are defined in VAO.H, which is located in the Include folder in \Visio11\SDK\Libraries\CPP\ in the Microsoft Office Visio 2003 SDK.

Note Entries in the PublishComponent table correspond to values in VAOREGSTRUCT, and override it for add-ons that are component-published.

The Vaddon.H and Vaddon.CPP files, located in the Include and Source folders of the previously described path, provide a base class that can be used to create add-ons in C++.

A VSL remains loaded for the duration of a Visio instance and is unloaded by Visio when it closes.

Implementation Considerations for .vsl Files

When implementing an add-on using a VSL, keep the following in mind:

A VSL runs in the same process as Visio, typically providing better performance than an add-on that runs in its own process.
Because the VSL runs in the same process, it is often easier to open a dialog box that is modal to the process in which the Visio instance is running.
If component-published, the location and load behavior of a .vsl file is provided in its registry entry.
Because the VSL runs in the same process, it can cause Visio to fail if it fails.

Implementing an Add-on Using an .exe File

Stand-alone executable programs can also be used as add-ons to extend Visio. An .exe file can be written in any language; however, in order for the add-on to make calls into Visio, it must be written in a language that supports Automation.

In addition to the many ways of launching a Visio add-on described earlier, an .exe file can also be launched from the desktop or Windows Explorer.

The name of an .exe file add-on in the Addons collection is the name of the .exe file itself. For example, if you created an .exe file named MyAddon.exe, the add-on's name in the collection is "MyAddon.exe" and the name shown on the Tools menu is "MyAddon".

Unlike an add-on in a .vsl file, a path-discovered .exe file is always in an enabled state. You can, however, prevent an .exe file from appearing on the Tools menu by prefixing the executable file with an underscore (_), for example, "_MyAddon.exe".

Executable files that are component-published may be specified as enabled or disabled. An .exe file used as a Visio add-on must be able to handle the command string passed to it by Visio. The command string identifies Visio as having launched the program, as well as other optional values that identify how the program was started. For example, if the .exe file was run from the Macros submenu, the command string would resemble the following:

/visio=instancehandle32

Or if the .exe file is run as the result of a shape's formula being evaluated, it would resemble the following:

/visio=instancehandle32  /doc=docIndex  /page=pagIndex  
   /shape= Nameid

Implementation Considerations for .exe Files

When implementing an add-on using an .exe file, keep the following in mind:

An .exe file is easy to build and can be written in many different languages.
By definition, an .exe file runs in its own process, and is loaded into memory in that process when it is initiated by Visio. Because calls from the .exe file must cross process boundaries, its performance can be slower than that of a VSL or COM add-in, which runs in the Visio process.
Because an .exe file runs in its own process, there may be issues concerning running modally with Visio. For example, Visio does not disable toolbars by default when your program displays a form or dialog box. For additional information about running modally with Visio, see the OnComponentEnterState method, which was implemented in Visio 2002.
If component-published, the location and load behavior of an .exe file is provided in its registry entry.
Because the .exe file runs in its own process, the only way Visio can call the add-on and pass parameters to it to make a command line call. Therefore, a new instance of the executable is launched each time Visio calls the add-on.
Because the .exe file runs in its own process, Visio does not end your program when the application quits. The .exe file must track the state of the Visio application in order to quit in a timely manner. This is typically handled by monitoring application events, for example, the BeforeQuit event.

COM Add-ins in Visio

In Visio, the term add-in refers specifically to a COM add-in, a COM object that implements the IDTExtensibility2 interface.

You can create a COM add-in in any Microsoft programming environment that can create a COM object and implement an interface. Although a COM add-in can be implemented as an ActiveX .exe file, COM add-ins are typically written as DLLs, because of their improved performance relative to .exe files.

Information about the name, location, and load behavior of a COM add-in is stored in the registry. Unlike a Visio add-on, once Visio (or any host application) has loaded a COM add-in, it has no way to call it directly. This is the most important distinction between a Visio add-on and a COM add-in—Visio can run an add-on in response to formula evaluation or actions in the user interface. By contrast, Visio can load a COM add-in but does not have any way to run it—that process is controlled by the COM add-in.

Because there is no way for Visio to call a COM add-in, Visio cannot run an add-in in response to a formula evaluation, or to menu or toolbar item selections when using the UIObject object model.

However, you can program your add-ins to monitor marker events and respond when they are raised. Use the QueueMarkerEvent add-on to raise marker events to notify your add-in of user actions. These user actions include: selection of menu or toolbar items; accelerator items implemented using the UIOBject or CommandBar objects; user actions that cause a persisted event to be raised; or user actions that cause an Action or Event cell in the ShapeSheet to be evaluated. This greatly expands the range of actions to which a COM add-in can respond within a Visio solution. Add-ins that use the QueueMarkerEvent add-on must be monitoring marker events before a marker event is queued. Therefore, these add-ins should be loaded on startup (or by demand) and should initialize their event handling as part of the loading process.

For more information about using the QueueMarkerEvent add-on, Using the QueueMarkerEvent Add-on in Visio Solutions.

In Visio 2003, there is also a QueueMarker ShapeSheet function, which can be used to raise marker events whenever a formula is evaluated.

A COM add-in has events that you can use to run code when the add-in is loaded or unloaded, or when the host application has completed the start process or started the close process. These add-ins often hook selected Visio events.

When using the command bar object model, you can bind your COM add-in to a CommandBarButton object using the OnAction property, or handle the object's Click event.

Like Visio add-ons contained in a VSL, Visio unloads COM add-ins when the application closes.

Implementation Considerations for COM Add-ins

When extending the Visio application with a COM add-in, keep these considerations in mind:

A COM add-in is relatively easy to build and can be developed in any language that supports Automation, including Visual Basic.
Like VSLs, a COM add-in provides better performance than an executable file because it runs in the same process as its host application.
Location and load behavior of a COM add-in is provided in its registry entry.
COM add-ins can be enabled or disabled by the user, either individually or as a group. (On the Visio Tools menu, point to Macros, and then click COM Add-ins.)

Note Only add-ins that are available to the individual user appear on this menu; add-ins available to all users of the application are not displayed.
COM add-ins can be designed to run in multiple Office applications.
Unlike Visio add-ons, you cannot launch a COM add-in in response to a ShapeSheet cell's formula recalculation. However, you can create COM add-ins that are loaded on application startup, and that then monitor for and respond to marker events raised by the QueueMarkerEvent add-on in response to user actions.

To work programmatically with the COMAddIns collection in Visio, use the COMAddIns property of the Visio Application object (you must have a reference in your project to the Office 11.0 object library).

Summary Table Comparing .vsl Files, .exe Files, and COM Add-ins

The following table offers a comparison between both types of Visio add-ons and COM add-ins.

Table 1. Comparison of .vsl files, .exe files, and COM add-ins

COM add-ins	Add-ons in .vsl files	Add-ons in.exe files
Support added in Microsoft Visio 2002.	Support added in Visio 2.0.	Support added in Visio 2.0.
Can run in-process.	Runs in-process.	Runs out-of-process.
A COM object that implements the IDTExtensibility2 interface, usually a DLL.	A DLL with an entry point of VisioLibMain.	A stand-alone executable program.
Can be created in any language that can create a COM object and implement an interface (including Microsoft .NET languages).	Can be created in languages that can support exporting functions, typically C++.	Can be created in any language that can create .exe Automation clients.
Can run in multiple Office System applications with proper implementation.	Visio-specific.	Can run in multiple Office System applications with proper implementation.
Load behavior is defined in the registry. Some examples are Startup, or On Demand.	Loaded when called.	Loaded when called.
Can be installed anywhere. Location information is contained in the registry entry.	Can be installed anywhere. However, for path discovery, the add-on file path must be added to the Visio Start-up or Add-ons path. For component-published add-ons, location information is contained in the registry entry.	Can be installed anywhere. However, for path-discovery, the add-on file path must be added to the Visio Start-up or Add-ons path. For component-published add-ons, location information is contained in the registry entry.
Cannot be called from the ShapeSheet. However, can monitor for and respond to marker events raised by the QueueMarkerEvent add-on or QueueMarker ShapeSheet function in response to user actions (such as the evaluation of a ShapeSheet cell formula).	Can be run in response to a formula recalculation (the RUNADDON and RUNADDONWARGS functions).	Can be run in response to a formula recalculation (the RUNADDON and RUNADDONWARGS functions).
Cannot be run from the Tools menu.	Can be run from the Add-ons submenu (Tools menu). Add-ons can also be designed to not appear on the Tools menu.	Can be run from the Add-ons submenu (Tools menu). Add-ons can also be designed to not appear on the Tools menu.
Cannot be run in response to UIObject objects. However, can monitor for and respond to marker events raised by the QueueMarkerEvent add-on in response to user actions (such as selection of items implemented using the UIObject object.)	Can be bound to a menu, menu item, toolbar item, or accelerator using the AddonName property when using the UIObject object model.	Can be bound to a menu, menu item, toolbar item, or accelerator using the AddonName property when using the UIObject object model.
Can be bound to a CommandBarButton object using the OnAction property when using the command bar object model, or handle its Click event.	Can be bound to a CommandBarButton object using the OnAction property when using the command bar object model, or handle its Click event.	Can be bound to a CommandBarButton object using the OnAction property when using the command bar object model, or handle its Click event.
Cannot be persisted. However, can monitor for and respond to marker events raised by the QueueMarkerEvent add-on in response to user actions (such as actions that cause a persisted event to be raised.)	Can be persisted in an object's EventList collection using the Event object's Target property.	Can be persisted in an object's EventList collection using the Event object's Target property.