About Microsoft Visio Add-ons and COM Add-ins

Article
06/14/2014

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Microsoft Corporation

February 2002

Applies to:
Microsoft Visio Standard 2002
Microsoft Visio Professional 2002

Summary: This article describes the differences between Visio add-ons (.vsl and .exe files) and COM add-ins, and the benefits and limitations of extending Microsoft Visio with each. (8 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
Additional Information

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 listen to events as they occur in the application.

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

By 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).
By creating Component Object Model (COM) add-ins. Visio 2002 has added support for COM add-ins. Because most Microsoft Office XP applications support the COM add-in architecture, you can now use the same tools and installation file formats to develop add-ins for all your Office XP applications, including Visio.
By 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 architected as programs that run external to Visio documents. By understanding the differences in how each of these programs is architected, you can make informed decisions about the type of add-on or add-in to use with your custom solution.

**Note **This article first appeared in the Visio 2002 SDK, and the content is identical. This article also does not focus on how to create solutions by writing VBA code in a Visio document's project. For more information on programming Visio with VBA, see Developing Microsoft Visio Solutions.

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.

To be recognized as an add-on by the application, these files must be installed in the Visio Start-up or Add-ons path (Tools menu, File Paths tab), or added to the collection of add-ons in a Visio instance using the Add method of the application's Addons collection.

**Note **It is strongly recommended that you install 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 rather than place add-ons you develop into Visio folders.

When Visio starts, any .exe files or add-on contained in a .vsl file 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.

Internally, both types of add-ons 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.
Choose the add-on from the Macros submenu (Tools menu) or from the Add-Ons submenu (if Visio is running in developer mode).
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.

Note 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 in either the Start-up or Add-ons path, it loads the VSL and identifies the number and names of any add-ons that are implemented in it along with other pertinent information, for example, whether the add-on is enabled or not.

When Visio wants to run 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 Macros or Add-Ons submenu by setting a flag in the atts field in VAOREGSTRUCT. This structure, and additional definitions that define the interface between Visio and a VSL, are defined in VAO.H, which is located in the Include folder in \Visio10\SDK\Libraries\CPP\ in the Microsoft Visio 2002 SDK.

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.
Because the VSL runs in the same process, it can cause Visio to fail if it fails.

Note For more information about creating a VSL and programming Visio with C++, see Developing Microsoft Visio Solutions.

For a sample VSL, look in the following path in the Microsoft Visio 2002 SDK:

\Visio10\SDK\Samples\CPP\MyAddon

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 that supports Automation, which includes Microsoft Visual Basic®, C/C++, or Microsoft Visual J++®.

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, an .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 with an underscore (_), for example, "_MyAddon.exe".

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 Visio instructs it to run. 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.
Because the .exe file runs in its own process, the only way Visio can call the add-on and pass it parameters is 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 know to 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 listening to application events, for example, the BeforeQuit event.

Note For more information about the command string passed from Visio to your .exe file, as well as general information about programming Visio with Visual Basic, see Developing Microsoft Visio Solutions.

COM Add-ins in Visio

The term add-in in Visio 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 improved performance over .exe files.

**Note **While Visio 2002 includes Microsoft Visual Basic for Applications (VBA) 6.3, you also need the extended Visual Basic Editor in Microsoft® Office Developer or Office XP Developer to create COM add-ins in VBA.

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 knows when to load a COM add-in but does not have any way to run it—a COM add-in controls when it runs.

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. For these cases, you must create a Visio add-on.

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 finished starting or begun quitting. 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 the following in mind:

A COM add-in is fairly 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.
The location and load behavior of a COM add-in is provided in its registry entry—it does not have to be installed in the Visio Start-up or Add-ons path.
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.)
COM add-ins can be architected to run in multiple Office XP applications.
Unlike Visio add-ons, you cannot launch a COM add-in in response to a ShapeSheet cell's formula recalculation.

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 10.0 object library).

Note For more information about creating COM add-ins for Visio, see Developing Microsoft Visio Solutions.

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 XP applications with proper implementation.	Visio-specific.	Can run in multiple Office XP 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).	Must be installed in the Visio Start-up or Add-ons path.	Must be installed in the Visio Start-up or Add-ons path.
Cannot be called from the ShapeSheet.	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 Macros submenu (Tools menu) in the user interface; if running in developer mode, 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 Macros submenu (Tools menu) in the user interface; if running in developer mode, 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.	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.	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.

Additional Information

The following table contains suggestions of where to look for more information on subjects related to this article. The sources described in the table can be found in the \Visio10\SDK\Docs\ path in the Microsoft Visio 2002 SDK or in the Visio Developer Center on MSDN®, the Microsoft Developer Network.

Table 2. Sources of additional information

Item	Information source
AccelItem object	Automation Reference
Add method (Addons collection)	Automation Reference
Add method (EventList collection)	Automation Reference
Addon object	Automation Reference
AddonName property	Automation Reference
Addons collection	Automation Reference
BeforeQuit event	Automation Reference
COMAddins property	Automation Reference
Command bars	Developing Microsoft Visio Solutions, Chapter 22, "Customizing the Visio User Interface"
Command line string sent to an .exe file	Developing Microsoft Visio Solutions, Chapter 27, "Programming Visio with Visual Basic"
Creating a COM add-in for Visio	Developing Microsoft Visio Solutions, Chapter 23, "Using COM Add-ins in a Visio Solution"
Creating an executable program	Developing Microsoft Visio Solutions, Chapter 27, "Programming Visio with Visual Basic"
Creating a VBA project to extend Visio	Developing Microsoft Visio Solutions, Chapter 15, "Programming Visio with VBA"
Creating a VSL	Developing Microsoft Visio Solutions, Chapter 28, "Programming Visio with C++"
Event object	Automation Reference and Developing Microsoft Visio Solutions, Chapter 21, "Handling Visio Events"
EventList collection	Automation Reference
Formulas in ShapeSheet cells	Developing Microsoft Visio Solutions, Chapter 4, "Formulas," and Chapter 17, "Automating Formulas"
Menu object	Automation Reference
MenuItem object	Automation Reference
OnComponentEnterState method	Automation Reference
Run method	Automation Reference
RUNADDON function	ShapeSheet Reference
RUNADDONWARGS function	ShapeSheet Reference
Target property	Automation Reference and Developing Microsoft Visio Solutions, Chapter 21, "Handling Visio Events"
ToolbarItem object	Automation Reference
UIObject object	Automation Reference and Developing Microsoft Visio Solutions, Chapter 22, "Customizing the Visio User Interface"

Share via