![]() |
Visio 2003 Developer's Survival Pack Tools and Samples |
VBVSL General Install, Run and Source Code Notes | |
![]() ![]() |
This document provides general instructions pertaining to the VBVSL samples which demonstrate how to write Visio VSLs using Visual Basic, using the VBVSL_Adapter mechanism.
Before proceeding, I recommend considering the following issues:
Issue 1: You will need to decide where to install VSLs (actually the VBVSL Adapters) and stencils pertaining to this book. For example, create a VXDSP directory, under the Visio\...\Solutions folder (V2002 or V2003) or under My Documents\My Shapes (V2003). In V2003, you will need to use Tools > Options > Advanced > File Paths to set the Addons and Stencils paths so that Visio can find the VSLs and stencils.
(I've used VXDSP as the directory name here, "VX" for Visio 10 aka Visio 2002. If you have obtained these components with the Visio 2003 edition of the book, you might use V11DSP or somesuch as the directory -- the exact name is not critical.)
Issue 2: I recommend installing all the sample VSLs at once, so as to avoid confusion later as to which samples are operable and which not.
Issue 3: Since the VBVSL samples entail registering the ActiveX DLLs (and their locations) in the registry, it would be worthwhile placing the entire directory structure of samples at a location that you won't soon need to move. Moving can be done, but will require some thoughtful unregistering and re-registering, and results in puzzling errors if you forget to do so.
To install one or more of the VBVSL samples, follow the steps below. The procedure below is only suited to installation on a machine which already has Visual Basic 6 installed. To install on a machine without VB6, see the further section below on Deployment.
Step | Discussion |
Register each VBVSL DLL with Windows | The main functionality of each VBVSL sample is implemented
in an ActiveX DLL, as indicated in the index.htm page for each sample.
This needs to be registered with Windows, which you can do in one of two
ways:
Option 1: Use regsvr32 to register the ActiveX DLL. See regsvr32 notes
below on a convenient way to do this. Repeat this for each sample DLL. |
Create a VBVSL_Adapter for each VBVSL, and place it in a Visio\...\Solutions directory. | To allow Visio to talk to each ActiveX VSL DLL, we need to
provide an adapter for each one, installed according to Visio's requirements
for all VSLs. This entails two steps:
These two steps above can be performed automatically using the AdapterWTrace.bat file provided in each VBVSL directory. However, you will need to edit the paths in each one to conform to the directory layout on your computer. |
Provoke Visio into surveying the newly installed VSL(s) | The most definite way to do this is as follows. With Visio
not running...
These are located in the directory: C:\Documents and Settings\[username]\Local Settings\Application Data\Microsoft\Visio This can be done using Windows Explorer, or made easier using the VisioBinDel utility I provide (see instructions for that tool). When Visio is restarted, you will see a dialog asking you to wait while Visio reloads its cache of directory (and VSL, template and stencil) info. Alternatively, you can manually open Visio and visit the Tools > Addons menu |
![]() If you followed the steps above, you should arrive at a Solutions\VXDSP directory that looks something like this. |
![]() If Visio successfully surveys each VSL and its Addons, then when you visit the Tools > Addons menu, you should see the list shown here under the VXDSP branch. Note that the Tools > Addons menu only appears if you are running Visio in developer mode, which you can set using: Tools > Options > Advanced > Run in developer mode. |
To make regsvr32 more accessible, I recommend setting up a "Send to" shortcut for it. This allows you to select any ActiveX DLL in Windows Explorer, then right-click > Send To to install it.
To do this, place a shortcut to regsvr32.exe in the SendTo folder in the appropriate Profiles or Documents and Settings folder for your user, or All Users. (You can just Control-Shift-drag regsvr32.exe from Winnt\system32 to the SendTo folder -- or similar on your machine.)
If you wish, you can also set up a SendTo item for uninstalling. In that case create a batch file containing the lines:
C:\WINNT\system32\regsvr32.exe /U %1 Exit
... and place this batch file directly in the SendTo folder.
The above "manual" installation of a VBVSL takes you through the main steps that you would need in any VBVSL installation, except for one crucial one. VBVSLs being written in Visual Basic, rely upon the Visual Basic runtime libraries. These are already present and available on any machine where VB6 is already installed, but not necessarily on users machines, though some other VB-based application may have installed them.
Consequently, to actually deploy a VBVSL you would proceed as with any VB-based deployment. You would need to use the Visual Basic Package and Deployment features, or the installer software of your choice. To that installation you would add the few extra steps needed to complete the VSL-specific part of the installation on a user's machine, namely:
Here are a few brief notes on working with Visual Basic source code for the VBVSL samples.
Common VB/VBVSL Modules
There are several modules that are common to all or many of the VBVSL samples. These common modules are located in the VB\VBCommon directory. (This is also apparent if you inspect a vbp file, or look at the module tree view in the VB IDE).
VB References
Several of the VBVSL samples depend on References to other type libraries, such as the Microsoft Visio 200x type library. Before loading one of the VB projects into the VB IDE, first inspect the project file (xxx.vbp) in a text editor (such as Notepad) and note down the References that it specifies. Then, when you load this project, visit VB's Project > References dialog and make sure that these references are indeed workable in the environment on your PC. If not, endeavor to get them hooked up again. (See the References documentation in the VB Help.)
VBVSL Type Library
The VBVSL projects all need references to the VBVSL type library, to inform Visual Basic about the various classes and types incorporated in the VBVSL mechanism. This type library is built into each VBVSL_Adapter, therefore you can use any method you like to set a reference to one of those VSLs.
The least energetic way to do this is to simply use the VB menu Project > References dialog, and use the Browse button to find one of those VSLs. You might for example choose VBVSL_Adapter_NoTrace.vsl in the VB\VBCommon directory. (Note that the type library contents are the same for both the WithTrace and NoTrace versions of the adapter.)
If you want, you can actually register one of those VSLs, which will cause the Project > References dialog to offer the VBVSL_Types library on its list of Available References. Ideally, this could be done with the Windows regsvr32 utility, and the SendTo trick discussed earlier since a VBVSL adapter is just a DLL. However, it appears that regsvr32 may not want to register a DLL with an oddball extension like "vsl". To circumvent this problem, you can instead use the TypeLibReg utility provided in this kit. (See separate documentation for that utility.)
Note that registering a VBVSL_Adapter in this way is only needed on a development machine fo use by the VB IDE. It's not needed on an end-user machine so does not need to be part of a normal deployment process.
Example References Dialog Listing
Here's an example of what the References dialog should look like.
Following the default references for Visual Basic and OLE Automation, note the presence of the Microsoft Visio 200x Type Library, and also the VBVSL Types library. This particular project also uses an IDataObject TypeLib (supplied in the VBCommon directory).
Compiling
When compiling a fresh copy of a VBVSL ActiveX DLL, you may need to shut down Visio. If Visio is running and you have invoked this particular VSL, then Visio will have locked the DLL file, and therefore VB will not be able to replace it with the newly compiled version.
Debugging with Visual Basic
You can debug a DLL (in this case a VBVSL DLL) in a manner similar to any standalone Visual Basic project. In outline, you instruct the VB IDE to launch Visio and debug the instance of the DLL that Visio loads. You specify this using VB's Project > [projectname] Properties dialog, Debugging tab, "Start Program" button and textbox. Browse to set the path to Visio.exe.
Common Failure Mode
When creating your own VBVSLs, if a fatal bug occurs in your code the VBVSL Adapter generally prevents it from crashing Visio, though your DLL may no longer function. However, one class of failures creates slightly more alarming results. For example, if your code has obtained resources and fails to shut them down in an orderly fashion before Visio closes, then Visio may issue error messages on exit.
Starting with Visio 2003, Visio performs a security check on VSLs. Consequently, there is now the burden of code-signing your VSLs if you want to reduce the hassles for your users. If you do not sign a VSL, then depending on the user's Visio security settings, Visio will either refuse to load the VSL (possibly without warning), or present a security dialog.
At this writing, I have an article on code signing in preparation. Watch this book's main support page for details.
Article Created: 2003-09-01 Last edit: Last edit:
03-10-29 Graham
Wideman
Go to:
DiagramAntics.com