Overview of Add-ons and COM Add-ins in Visio 2007

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

Saul Candib, Microsoft Corporation

October 2007

Applies to:   2007 Microsoft Office System, Microsoft Office Visio 2007

Contents

• Overview of Creating Visio Solutions

• Visio Add-Ons

• Using a Visio Library File to Implement an Add-On

• Using an EXE File to Implement an Add-On

• COM Add-ins in Visio

• Comparing Visio Library Files, EXE Files, and COM Add-Ins

• Conclusion

• Additional Resources

Overview of Creating Visio Solutions

A Microsoft Office Visio 2007 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.

Visio 2007 provides several ways for developers who use 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 (.vsl) file, which is a form of dynamic link library (DLL) that is specific to Visio, or in a stand-alone executable program (.exe file).

• Creating Component Object Model (COM) add-ins. Visio 2007 includes support for COM add-ins. Because most 2007 Microsoft Office system 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 applications, including Visio.

• Using Microsoft Visual Basic for Applications (VBA) code. VBA code is stored with a Visio document, and you can create VBA solutions in the Visual Basic Editor environment that is part of Visio.

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. For more information, see the Visio 2007 Automation Reference. Or, in Visio 2007, on the Help menu, click Developer Reference.

Visio Add-Ons

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

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

• A .vsl file, which is a standard Windows DLL that has a prescribed Visio entry point.

• An .exe file, which is a stand-alone executable program.

There are three ways for Visio to recognize add-ons:

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

  When you publish content, you populate the PublishComponent table in a Windows Installer (.msi) file that you create to install content, such as add-ons, templates, stencils, and Help files. Each entry (row) in the PublishComponent table contains information pertaining to how a specific file to be installed should be displayed in the Visio user interface (UI). During installation, these entries are published to the Visio registry. Visio uses this information to display the add-on in its UI, and install on demand or repair the file as needed.

  For more information about publishing content, see Publishing Visio 2007 Solutions.

• Path-discovered. Visio also recognizes your add-on if you add the path where your add-on 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
  You must install the add-ons you develop in new folders you create to contain the add-ons, and then append those new folders to the Start-up path or the Add-ons path. Do not place the add-ons you develop into folders that already contain Visio content.

• Add method. You can also add the files to the collection of add-ons in a Visio instance by using the Add method of the application's Addons collection. (To get the Addons collection, use the Addons property of the Application object.) This option is only available programmatically.

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

Note
Visio treats add-ons that are 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 Visio loads. (To specify macro security settings, on the Tools menu, click Trust Center, and then click Macro Settings.)

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 (is executable), and can have an enabled or disabled state.

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

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

  For more information about using the RUNADDON function, see Changes in the RUNADDON Function and the AddOnName Property for Visio 2002.

• Select the add-on from the Add-Ons submenu (on the 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 that you create by using the Add method of an EventList collection.

• Use the Run method of an Addon object.

If an add-on has the same name as another add-on in the Add-ons path, Visio does not issue a warning. 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 example.

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

If both a debug version and a release version of your add-on have 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.

Using a Visio Library File to Implement an Add-On

A Visio library (.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 file.

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

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

Visio does not need to load add-ons that are published by using PublishComponent table entries in an .msi file to determine implementation information. This information, such as enabled state or attributes, 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 file (to VisioLibMain).

You can prevent an add-on contained in a .vsl file from appearing on the 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 file, are defined in VAO.H, which is located in the Include folder at the following default path in the Microsoft Office Visio 2007 Software Development Kit (SDK) installation:

C:\Program Files\Microsoft Office\Office12\VisSDK\Libraries\CPP\

To download the Visio 2007 SDK, see Visio 2007: Software Development Kit.

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 in the Visio 2007 SDK installation path, provide a base class that you can use to create add-ons in C++.

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

You can use the Microsoft Visual Studio 2005 Visio Add-in Wizard to create a shell add-on project in Visual Studio 2005 in Microsoft Visual C++, to help speed the development process. The Microsoft Visual Studio 2005 Visio Add-in Wizard is part of the Visio 2007 SDK.

Implementation Considerations for Visio Library Files

When you implement an add-on by using a .vsl file, keep the following in mind:

• A .vsl file runs in the same process as Visio, typically providing better performance than an add-on that runs in its own process.

• Because the .vsl file 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 a .vsl file is component-published, its location and load behavior are specified in its registry entry.

• Because the .vsl file runs in the same process, if it fails, it can cause Visio to fail

Using an EXE File to Implement an Add-On

You can also use stand-alone executable (.exe) programs as add-ons to extend Visio. You can write an .exe file in any programming language; however, for the add-on to make calls into Visio, you must write it in a language that supports Automation.

In addition to the many ways of starting a Visio add-on described earlier, you can also start an .exe file from the desktop or from 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 create 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. However, you can 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 started the program, and it may include optional values that identify how the program was started. For example, if the .exe file is run from the Macros submenu, the command string resembles the following:

/visio=instancehandle32

Or if the .exe file is run as the result of a shape's formula being evaluated, the command string resembles the following:

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

You can use the Microsoft Visual Studio 2005 Visio Add-in Wizard to create an .exe add-on project in Visual Studio 2005, in Visual Basic, Microsoft Visual C#, or C++. The Microsoft Visual Studio 2005 Visio Add-in Wizard is part of the Visio 2007 SDK.

Implementation Considerations for EXE Files

When you implement an add-on by 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, the performance of an .exe file can be slower than the performance of a .vsl file or COM add-in, each of which runs in the Visio process.

• Because an .exe file runs in its own process, you may encounter issues when you run it modally with Visio. For example, Visio does not disable toolbars by default when your program displays a form or dialog box. For more information about running modally with Visio, see OnComponentEnterState Method.

• If an .exe file is component-published, its location and load behavior are specified in its registry entry.

• Because an .exe file runs in its own process, the only way Visio can call the add-on and pass parameters to it is to make a command-line call. Therefore, a new instance of the executable is started each time Visio calls the add-on.

• Because an .exe file runs in its own process, Visio does not end your program when the application exits. The .exe file must track the state of Visio to close in a timely manner. Typically, you can handle this 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 you can implement a COM add-in 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 when Visio runs an add-on, after Visio (or any host application) loads 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 UI. By contrast, Visio can load a COM add-in but has no 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-item or toolbar-item commands created by using the UIObject object.

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 the following:

• Selecting menu or toolbar items.

• Pressing accelerator key combinations that you implement by using the UIObject or CommandBar objects.

• Causing a persisted event to be raised.

• Causing 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 start 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, see Using the QueueMarkerEvent Add-on in Visio Solutions.

Starting in Visio 2003, there is also a QUEUEMARKEREVENT ShapeSheet function, which you can use to raise marker events whenever a formula is evaluated. For more information, see QUEUEMARKEREVENT Function.

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 you use the command bar object model, you can bind your COM add-in to a CommandBarButton object by using the OnAction property; or you can handle the object's Click event.

As it does with add-ons contained in a .vsl, Visio unloads COM add-ins when the application closes.

You can use the Microsoft Visual Studio 2005 Visio Add-in Wizard to create a COM add-in project in Visual Studio 2005, in Visual Basic, C#, or C++. The Microsoft Visual Studio 2005 Visio Add-in Wizard is part of the Visio 2007 SDK.

Implementation Considerations for COM Add-Ins

When you extend Visio with a COM add-in, keep these considerations in mind:

• A COM add-in is relatively easy to build, and you can develop it in any language that supports Automation, including Visual Basic.

• Like .vsl files, COM add-ins provide better performance than .exe files, because they run in the same process as their host application.

• The location and load behavior of a COM add-in are specified in its registry entry.

• Users can enable or disable COM add-ins, either individually or as a group in the Office Trust Center. (On the Visio Tools menu, point to Trust Center, click Add-ins, and then click Go.)

  Note
  Only add-ins that are available to the individual user appear in this list; add-ins available to all users of the application are not displayed.

• You can design COM add-ins to run in multiple Microsoft Office applications.

• Unlike starting Visio add-ons, you cannot start a COM add-in in response to a ShapeSheet cell formula recalculation. However, you can create COM add-ins that are loaded on application start up, and 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 12.0 object library.)

Comparing Visio Library 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

Conclusion

This article explains the differences between Visio add-ons (.vsl and .exe files) and COM add-ins, and the benefits and limitations of extending Visio 2007 with each. It also discusses the benefits of publishing Visio solutions and points out when you can use the Microsoft Visual Studio 2005 Visio Add-in Wizard, part of the Visio 2007 SDK, to make it easier to create your custom Visio solutions.

Additional Resources

• Visio 2007: Software Development Kit

• Publishing Visio 2007 Solutions