	Visio 2003 Developer's Survival Pack
	NETVSL Adapter: Notes on Source Code
Visio 2003 DSP home This page

Overview

This page discusses various aspects of the source code relating to NETVSL Adapter and samples.

The supplied source code contains a number of sample .NET VSL projects (see Installation page for a list). This page focuses primarily on the NVTest_TwoAddons sample, as it demonstrates the NETVSL_Base classes which implement most of what you need to assemble a .NET VSL with low effort. You may also be interested to look at the NVTest_ColorInc sample, which avoids the NETVSL_Base class to demonstrate a minimal VSL. A number of the points in this page also pertain to that sample, and to .NET VSLs in general.

Structure of Project

The figure to the right shows how the NETVSLLib solution appears in the VS.NET Solution Explorer. The NVTest_TwoAddons project is expanded.

Item	Description
NVTest_TwoAddons.cs	Exposes the NVTest_TwoAddons.NETVSL class. This is the object that COM invokes through COM Interop and .NET, so it's the main entry point when Visio activates the VSL. (Most of the functionality of this object isinherited from the NETVSL_Base module, more on this below).
NVTest_TwoAddons_... Addon01.cs Addon02.cs	Modules that implement two separate addon classes. Addon01 is simple, Addon02 is more complex, and in turn invokes a couple of forms
NVTest_TwoAddons_... Addon02_Form1.cs Addon02_Form1.cs	Two different forms that can be invoked by Addon02.
NETVSL_Base	Provides basic functionality for an overall VSL object and for Addon objects.
NETVSL_Types	The original authoritative declarations for the INETVSL interface. Also several enums that are used as arguments for some of the INETVSL member functions. Inspect these to see variations of behaviors available from several of the member functions.
Other NETVSL_xxx.cs files	Helper objects.
	Note that items with the little arrow sybol are "linked" files. That is to say they are included in this project (and several others), but are not in the directory tree for this project. In general, do not edit these files. In your own projects, to link a file do the following: Select the project, the right-click > Add Existing Item. In the file dialog, browse to the desired file, and select (but don't double-click) it. Then use the drop-down on the "Save" button to select Link File. Or, if the file is linked in another project, in Solution Explorer control-drag that link from other project to this current one.

Structure of Objects in the NETVSL_Base Scheme

The following figure illustrates the NETVSL_Base objects, and shows how an example builds on these to create and actual .NET VSL.

The following chart describes how the NVTest_TwoAddons project corresponds to the above, and the finer points involved.

Feature in diagram	Corresponding NVTest_TwoAddons Feature	Discussion
MySolution.cs	NVTest_TwoAddons.cs
MySolution_SomeAddon.cs	NVTest_TwoAddons_Addon01.cs etc
MySolution namespace	NVTest_TwoAddons namespace	Used in all NVTest_TwoAddons_xxx files.
NETVSL class	NETVSL class	Solution-specific Requirements: -- Specific filename -- Specific namespace name -- Instantiate addons and add to Addons collection Code notes: -- public: so that it is expose to .NET and COM -- COM interface attributes and GUID are supplied by INETVSL class that NETVSL promises to implement via inheritance of TNETVSL_Base. -- ClassInterfaceType.None to prevent .NET addng a ClassInterface which COM caller (Adapter) doesn't expect.
SomeAddon class	TNVTest_TwoAddons_Addon01 etc classes	Solutioin-specific requirements: -- Set addon properties in constructor. Note special base-calling syntax. -- Supply a useful Run function! Code notes: -- Class is marked internal, like all other classes in the project (except NETVSL), because we don't want to offer these to .NET and COM. (Members can be public/private etc depending on whether we want other classes in project to see them.) -- Addon can call Visio through VisApp reference in Owner NETVSL class.

More code notes in the sections below.

Namespace + Class = COM class name

When the NETVSL Adapter (or any other COM caller, like VBA) wants to call a COM component (like our .NET VSL component), it does so through use of a class name. (Eg: when a caller wants to call Visio, it looks for a COM object called "visio.application"). For our .NET component, we rely on the COM Interop services to offer our component to the Adapter. COM Interop services composes a name for our component by combining the namespace name plus the C# class name, separated by a period. So for the sample component here, the COM class name will be NVTest_TwoAddons.NETVSL.

References

In most cases, the default references added by VS.NET are suitable. Usually you will want to add Visio as a reference. (Select References, right-click > Add Reference. In the Add Reference dialog COM tab, find Microsoft Visio 11.0 Type Library (or Microsoft Visio 2002 Type Library).

Usings

If you are unfamiliar with how the "using" statements work, you may want to take a look at the "using" statements in each of the source files to get some ideas.

Strong Name; Assembly; Key file

As noted in the Installation page, installation entails applying the "strong name" procedure to the output dll, so that it's permitted to be placed in the Global Assembly Cache (GAC). VS.NET will do the strong name procedure for you if you supply a crypto key file. This involves two preparatory steps (already done in the samples, so you can follow those):

1. Create a key file. You use the sn command line utility:
-- cd to the project directory
-- sn -k "key.snk"

2. Tell the AssemblyInfo.cs file about this key file:
-- [assembly: AssemblyKeyFile(@"..\..\key.snk")]
-- note the relative path: it's the path from bin\Debug\something.dll to the key location.

Installing for Testing

For each cycle of compile-test you'll need to perform the installation procedure described on the Install page. Mainly this means after compiling you'll need to run that project's GACnReg.bat file. You could probably set this up as a "Post Build Event" command line, in the Project Properties.

Debugging

To use the VS.NET debugger to step through your VSL code, you need to have VS.NET launch Visio.
-- Select the project, right-click, Properties. to get the Property Pages dialog
-- Choose: Treeview > Configuration Properties > Debugging.
-- In the Start Action section of the right pane, set Debug Mode to Program. In Start Application, browse to the Visio.EXE executable.
-- Optionally add Command Line Arguments in the Start Options dialog.

Trace window

Like VBVSL, the NETVSL adaptor provides a convenient "trace window". This window can be activated in three different ways:

From Visio's Tools > Addons menu, select the item that has the name of your VSL with the "_Adapter" suffix. (Ie: this is an additional addon automatically registered by the adapter.) This will open the trace window.
You can create a ShapeSheet function using RUNADDON("MySolution_Adapter")... adjust the name appropriately.
You can invoke the trace window (and send messages to it) from the solution code by using the EnqueueTraceMessage method (supplied by TNETVSL_Base), using the NETVSL_AdapterMessage.OpenTrace or .AddMessageWShow messages.

The trace window shows a variety of activity as it occurs, indicating who was responsible (Visio, the adapter, or the ActiveX/.NET solution component). In addition, there is an incrementing number showing how frequently the adapter polls the solution code for SessionEnds and trace messages.

Form and Window Management

The Visio-specific Form and Window management issues for a .NET solution are similar to those for VB6. The TwoAddons_Addon02 code shows one example of how to call the Win32 API from C# to set window parentage to coordinate the a form window with Visio (eg: when minimizing Visio, and for the form to stay in front). The VB6 samples (provided with the main Survival Pack download) elaborate more variations, and these should extend to .NET -- though in some cases .NET's forms expose attributes of windows that VB6 forms do not, so there's less need to resort to Win32 API.

Note on Bloody Tabs

It's unbelievable in this day and age that we're still wrestling with bloody tab characters. I note that despite my having told VS.NET to NOT use tab characters, it seems to still insert tab characters. So the source files look just fine for me with my settings of VS.NET, but look like a complete mess when viewed in, for example, Notepad, and quite possibly when you view in VS.NET.

All I can say is AARRRRRGGG!

So, in case you want to see the files in some sort of orderly manner, my settings of VS.NET editor are:

Tab size: 2
Indent size: 2
Insert spaces: Yes
Keep tabs: No.

In theory, if you load the source files under these conditions, you ought to be able to reformat as you like them. But then again, in theory with these settings you shouldn't see any bloody tabs in the first place.

(BTW -- some people think an indent size of 2 is too small -- hey, it's all a matter of what works with your visual system. Many book authors like an indent of 2 because we are working with limited page width, and can't afford to indent wildly. By way of reference, one of the C# books I like is WROX Visual C# .NET: A Guide for VB6 Developers. They seem to randomly use indents of 2, 3 or 4. Then again, that book had four authors. Hmmm).

Article Created: 2004-01-15 Last edit: Last edit: 04-02-24 Graham Wideman
Go to: DiagramAntics.com