Introduction

On November 2006, Microsoft released Visual Studio 2005 Tools for the 2007 Office System, also known as VSTO 2005 SE (Second Edition). Developers have long been able to create custom add-ins for Visio. With VSTO 2005 SE, developers are now able to create VSTO add-ins for Visio.

You might be wondering, “Why should I care about VSTO 2005 SE when I have already been able to create custom add-ins for Visio?”

Here’s why. VSTO 2005 SE allows you to create secure add-ins for Visio. When you create a VSTO add-in, you can isolate your add-in from unexpected crashes of other add-ins. You can digitally sign your VSTO add-in. This allows your add-in to run when an administrator turns on the “Require Application Add-ins to be signed by Trusted Publisher” setting. Finally, VSTO add-ins operate under the .NET Code Access Security model. Your VSTO add-in has to be granted Full Trust in order to be loaded by Visio.

In this blog entry, I am going to:

·        Overview of the different Visio solution options

·        Recap the problem with Shared Add-ins

·        Walkthrough on creating and deploying VSTO add-in for Visio

Overview of Visio Solution Options

Simply put, there are many ways to create a Visio solution. The following list briefly describes each of the options, in the order they were first made available:

·        VSL add-ons: VSL’s (ViSio Libraries) were first made available with Visio 2.0. In fact, many of the out-of-the-box Visio solutions, such as the Organization Chart, are implemented as a VSL add-on. You create VSL add-ons using C or C++. The emphasis of this Visio solution option is sheer speed.

·        EXE add-ons: EXE add-ons were also first made available with Visio 2.0. They are simply standalone executables that can be launched from Visio and can be created with virtually any programming language. EXE add-ons run in a separate process space as Visio, so you should avoid this option if your solution needs to access the Visio Automation Library a lot.

·        VBA: Before Microsoft acquired Visio Corporation, Visio was probably one of the first non-Microsoft products to support Visual Basic for Applications (or VBA). VBA solutions are document-centric, meaning that code is embedded within the Visio drawing file. I like to use VBA for quick prototypes, especially with the Macro Recorder.

·        COM add-ins: While VBA macros run at the document level, COM add-ins run at the Visio application level. They are created using unmanaged environments like Visual Basic 6.0, or unmanaged C++.

·        Shared add-ins: Shared add-ins are application-level solutions created using .NET languages like VB.NET and C#. They are typically created using the Shared Add-in wizard, or by using the “Visio add-in or add-on” wizard that comes with the Visio SDK. They still fundamentally use COM to extend Visio, but using managed code.

·        Visio Drawing Control: The Visio Drawing Control is an ActiveX component that lets you put your own chrome around Visio. You can embed the Visio Drawing Control in your Windows Forms or browser-based applications. It is essentially a wrapper around the Visio engine itself. You need to have Visio installed on the client machine.

·        VSTO add-ins: VSTO add-ins are also managed code add-ins that run at the Visio application level, but require the VSTO runtime. The VSTO runtime includes a dedicated add-in loader that provides AppDomain isolation. VSTO add-ins must be granted full-trust on the target machine. The emphasis here is security.

For more information on VSL add-ons and EXE add-ons, please refer to About Microsoft Office Visio Add-ons and COM Add-ins.

For more information on the Visio Drawing Control, please refer to Programming with the Microsoft Office Visio 2003 ActiveX Control and Host an Interactive Visio Drawing Surface in .NET Custom Clients.

Since Visio 2002, Visio solution developers have had a helpful Visio software development kit (SDK), which provides code samples, sample applications, tools, and documentation. The Visio SDK includes the “Visio add-in or add-on” wizard, that shows up as an additional project type for VB.NET, C#, and C++ in Visual Studio. The add-ins you create with this “Visio add-in or add-on” wizard is identical to the ones you create using the Shared Add-in wizard.  The difference is that the “Visio add-in or add-on” wizard allows you to create add-ons. For VB.NET and C#, you can create EXE add-ons. For C++ you also can create VSL add-ons.

The Visio 2007 SDK has been updated with more code samples and documentation that highlight the new Data Link and Data Graphics capabilities in Visio 2007. For more information, please go to the Visio Developer Portal.

Recap of the Problems of Shared Add-ins

Shared add-ins are not all that bad. If your add-in needs to work in multiple Office applications (e.g. Visio, Excel, and Word), you need to create a Shared add-in. VSTO add-ins are specific to their Office host. Also, if your add-in needs to work when multiple versions of Office applications are installed on the same machine, you will have better luck with a Shared add-in (although this is not recommended). Microsoft does not support VSTO development in the scenario where different versions of the same Office application are installed on the same machine.

VSTO add-ins address several problems that Shared add-ins have. Here I will shamelessly copy and paste from a couple of other blogs and articles that already do a great job describing the problems of Shared add-ins.

Brian A. Randall describes three problems with Shared add-ins in Migrating a Shared Add-in to a Visual Studio Tools for Office Add-In:

Mscoree.dll is the main entry DLL to the goodness that is the common language runtime (CLR). To ensure that the CLR is correctly loaded into a host application before your shared add-in, mscoree.dll is listed in the registry as the in-process server to load, not your managed assembly. This creates a few problems.

 

The first problem is that if your shared add-in (or some other one) causes an unhandled exception and crashes the host, the host will provide the user with an opportunity to stop the add-in from loading the next time. If the user chooses this option, the host lists the add-in as disabled. The problem is that the host application cannot distinguish between one shared add-in and another. It will ban mscoree.dll and thus all shared managed add-ins from the host.

 

The second problem is that when the CLR is initialized, it creates a default application domain and all shared add-ins loaded by the host are put into the same application domain. The problem with this is that one add-in can cause another add-in to fail. For example, one add-in could call ReleaseComObject on an object that both add-ins are using. This could happen in a case where there are two add-ins loaded into Excel, ExcelAddinOne and ExcelAddinTwo. By default, the two add-ins are put into the same default application domain. One of them is aggressive about memory management, say ExcelAddinTwo, and it calls FinalReleaseComObject on the Excel.Application reference that both add-ins are holding a reference to via a shared runtime callable wrapper (RCW). When ExcelAddinOne tries to access its reference to Excel it is a System.AccessViolationException: Attempted to read or write protected memory.

 

The third problem is an issue of trust. While most Office applications (in Office 2003, for example) trust add-ins out of the box (Publisher 2003 being an exception), it is possible for a security-minded user or administrator to disallow unsigned add-ins (those that don not have a valid X.509 signature). If this is done, your shared add-in will not work—even if you do sign it. Why? Once again it is mscoree.dll. Your Office application is looking to see if mscoree.dll is signed, not your managed assembly.

 

You can avoid these problems associated with Shared add-ins by creating a custom COM shim. A COM shim is essentially an unmanaged DLL that creates a separate AppDomain for your managed Shared add-in to run. You can then digitally sign your custom COM shim.

COM shims aren’t without problems either, as Andrew Whitechapel points out in Architecture of the Outlook Add-in Support in Visual Studio 2005 Tools for Office. Although the article was written for Outlook Add-in Support (VSTO 2005 “First Edition”), many of the points in this article still apply to VSTO 2005 SE:

You can download a Visual Studio COM Shim Wizard and project set from Microsoft, which enables you to build an unmanaged shim for managed add-ins. This approach solves some of the problems of a managed add-in that does not include a shim, but some issues remain:

 

·        This approach is unsupported by Microsoft.

·        This approach requires you to deploy an unmanaged shim component, plus one or more managed components with different installation requirements. This can be confusing for administrators (and developers) to maintain.

·        The (wizard-generated) shim is written in C++, a development language with which managed add-in developers are not always familiar.

·        With this model, each add-in requires an associated shim DLL, even though more than 99 percent of the code is identical across all such shims.

 

VSTO 2005 SE overcomes these issues by providing a supported, codesigned, single VSTO add-in loader.

For more information on the COM Shim Wizard, please see Andrew Whitechapel’s blog entry titled, COM Shim Wizards v2. It’s worth pointing out again from the early quote regarding the COM Shim Wizard, “This approach is unsupported by Microsoft.”

Creating a VSTO add-in for Visio 2007

Creating a VSTO add-in project for Visio is really simple. After you download and install the Visual Studio 2005 Tools for the 2007 Office System, you will get several new project templates in Visual Studio. Under your preferred programming language, let’s say Visual Basic, expand Office, and then 2007 Add-ins. There you will find a project template to create a Visio Add-in.

Here are the steps to follow to create your first VSTO add-in for Visio 2007:

1.      Start Visual Studio 2005. Click Create Project.

2.      Under Visual Basic | Office | 2007 Add-ins, and then select Visio Add-in.

3.      Type MyVisioVSTOAddin for the name of the project. Click OK.

Visual Studio will then create a new project for a VSTO add-in that can be loaded in Visio 2007. The project will have all the required references, including the Visio 2007 Primary Interop Assembly. The debug settings of the project will be set so that when you press F5 to debug, Visio starts up. A class named ThisAddIn will also be defined automatically for you. This class replaces the Connect class that you may have been familiar with in a Shared Add-in. Finally, Visual Studio will create a new setup project for your add-in to get you started. (Emphasis on the “to get you started”-- you need to do more to actually get it to deploy your add-in on a test machine.)

ThisAddIn is an improvement from the Connect class. Instead of the four methods you had to implement with IDTExensibility interface, ThisAddIn requires two: Startup and Shutdown. ThisAddIn also takes advantage of the partial class feature introduces with Visual Studio 2005. The VSTO add-in project template adds ThisAddIn.Designer.vb, a partial class that contains generated code to support VSTO add-in functionality. Tip: If you are using Visual Basic, you might need to click the “Show All Files” option under the Project menu to see ThisAddIn.Designer.vb.

By default the partial class defined in ThisAddIn.Designer.vb declares the Visio Application object using WithEvents:

Friend WithEvents Application As Microsoft.Office.Interop.Visio.Application

I strongly recommend that you remove the WithEvents keyword. As you may know, Visio has two event handling models. The first is by using the WithEvents keyword, the second is by using the AddAdvise method. When you use AddAdvise, Visio will raise an event for the events that you specify. When you use WithEvents, Visio will raise all events, even though you may not have an event handlers defined for all events. I recommend that you always use AddAdvise when creating Visio solutions because Visio won’t have to raise events for events you don’t care about.

For now, let’s display a simple “Hello, world!” message box when Visio starts up.

4.      Add the following code to the ThisAdd_Startup procedure:

 

System.Windows.Forms.MessageBox.Show("Hello, world!")

 

5.      Compile and run.

When you run the code, Visio should start up and display “Hello, world!” in a message box.

Deployment

Now here’s where it starts to get pretty tricky. In order for your add-in to work on a non-development machine, you have to make sure that the following steps are taken:

1.      Install .NET 2.0 Framework

2.      Install VSTO SE Runtime

3.      Install Visio 2007 Primary Interop Assembly

4.      Add required add-in registry settings

5.      Copy add-in assembly.

6.      Copy any Visio templates and stencils

7.      Grant full trust to add-in

The Setup project that is created for you by the VSTO SE add-in project template only takes care of steps 1, 4 and 5. Step 6, adding Visio templates and stencils is very easy. You just have to right-click on the setup project in Solution Explorer, and then click Add | File.

To do steps 2, 3, and 7, you need to customize the setup project. Fortunately, there are two great MSDN articles that show you how to do these customizations:

·        Deploying Visual Studio 2005 Tools for Office Second Edition Solutions Using Windows Installer (Part 1 of 2)

·        Deploying Visual Studio 2005 Tools for Office Second Edition Solutions Using Windows Installer: Walkthroughs (Part 2 of 2)

In the next few sections, I will copy and paste excerpts from the above two articles, including and editing what is relevant for Visio 2007 solution development. However, I strongly recommend that you take the time to read the above two articles in its entirety.

The first step is to install the accompanying download of the above two articles: OfficeVSTO2005SEWindowsInstaller.msi. This download contains custom setup bootstrapper packages for the VSTO 2005 SE runtime and Office 2007 PIA’s. It also contains the required custom action project to grant full trust to your add-in assembly.

After you install the accompanying download, follow the steps below from Deploying Visual Studio 2005 Tools for Office Second Edition Solutions Using Windows Installer (Part 1 of 2). The default location of the {SamplesDir} token below is “C:\Program Files\Microsoft Visual Studio 2005 Tools for Office SE Resources\VSTO2005SE Windows Installer Sample”:

Adding the Visual Studio Tools for Office Packages to the Bootstrapper

The following instructions describe how to add the packages listed above to the bootstrapper package directory. These changes need be made only once and only on your development computer.

This task shows how to use the files that are available in the Windows Installer download that accompanies this article. To use them, prepare the files before you copy them into the bootstrapper package directory.

Preparing the Runtime

To prepare the VSTO 2005 SE runtime bootstrapper package

1.    Download Microsoft Visual Studio 2005 Tools for Office Second Edition runtime from the Microsoft Download Center.

2.    Copy vstor.exe into the {SamplesDir}\packages\VSTOSERuntime directory.

Preparing the Visual Studio Tools for Office Language Pack Bootstrapper Package

If any users run your solutions with non–English settings for Windows, they must have the Visual Studio Tools for Office Language Pack to see runtime messages in the same language as Windows.

To prepare the Visual Studio Tools for Office Language Pack

1.    Download the Microsoft Visual Studio 2005 Tools for the Microsoft Office System (VSTO2005) Language Package from the Microsoft Download Center.

2.    Copy the file vstolp20.exe into the directory {SamplesDir}\packages\VSTOLP.

Preparing the Office Component Check

Compile the Office component checker sample for the primary interop assemblies redistributable packages.

Important:

If you are using VSTO 2005 SE in conjunction with VSTO 2005, ensure that you have installed both the .NET Framework 2.0 software development kit (SDK) and the Windows SDK.

Note:

By default, Visual Studio Tools for Office does not install the .NET Framework 2.0 SDK. You can download it or install it from the installation media by using the Add or Remove Programs command in Visual Studio Tools for Office. In addition, you need to download a copy of the Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime Components from the Microsoft Download Center. You can also download a copy of the .NET Framework 2.0 Software Development Kit (SDK) (x86) from the Microsoft Download Center.

 

Note:

These downloads are not required if you are using a version of Visual Studio with Visual C++ installed.

To prepare the Office component check

1.    Open the Command Prompt window needed to compile the check.

If you are using Visual Studio 2005 Professional, Team Suite, or one of the role-based Team editions, open the Visual Studio 2005 Command Prompt window by clicking Start, and then pointing to Programs, pointing to Microsoft Visual Studio 2005, pointing to Visual Studio Tools, and then clicking Visual Studio 2005 Command Prompt.

If you are using Visual Studio Tools for Office, run CMD Shell by clicking Start, pointing to Programs, pointing to Microsoft Windows SDK, and then clicking CMD Shell.

[If you are running on Vista, you should right-click and Run as administrator.]

2.    At the command prompt, change the directory to {SamplesDir}\projects\Checks

Tip:

By default, the SamplesDir directory is C:\Program Files\Microsoft Visual Studio 2005 Tools for Office SE Resources\VSTO2005SE Windows Installer Sample.

3.    Compile the component checker by typing the following command.

cl.exe /Oxs /MT /GS ComponentCheck.cpp advapi32.lib

4.    Close the Command Prompt window.

5.    Using Windows Explorer, copy the executable file ComponentCheck.exe into {SamplesDir}\packages\Office2003PIA and {SamplesDir}\packages\Office2007PIA.

 

Preparing for the 2007 Release of Office

You must include the primary interop assemblies for 2007 in the corresponding bootstrapper package if your solution will run in the 2007 release of Office, including VSTO 2005 Excel and Word document solutions.

To prepare the primary interop assemblies bootstrapper package

1.    Download the 2007 Microsoft Office System Update: Redistributable Primary Interop Assemblies from the Microsoft Download Center.

2.    Run the primary interop assembly installer.

3.    Accept the Microsoft Software License Terms, which gives you the right to package the primary interop assemblies as part of your installer.

4.    In Windows Explorer, open the folder to which the installer extracted the files.

5.    Copy O2007PIA.msi into the directory {SamplesDir}\packages\Office2007PIA.

Note:

Because you cannot directly download the redistributable package, you must always include it with your Windows Installer. If you set the prerequisite installation location to the Web, you are warned that this particular package must be included when you build the Setup project, as shown here: WARNING: No 'HomeSite' attribute has been provided for '2007 Microsoft Office Primary Interop Assemblies', so the package will be published to the same location as the bootstrapper.

Copying the Packages into the Bootstrapper Directory

Now that you have prepared the prerequisites, copy them into the bootstrapper package directory.

To copy the packages into the bootstrapper

1.    Determine where your bootstrapper package directory is located.

In Visual Studio Tools for Office, the default directory is here:

C:\Program Files\Microsoft.NET\SDK\v2.0\BootStrapper\Packages\

In Visual Studio 2005 Professional, Team Suite, or one of the role-based Team editions, the default directory is here:

C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\BootStrapper\Packages

Tip:

If in doubt, you can determine the location by appending \bootstrapper\packages to the value of this registry key: \HKLM\SOFTWARE\Microsoft\.NETFramework\sdkInstallRootv2.0

2.    Copy the contents of the directory {SamplesDir}\packages into the bootstrapper directory.

 

The next set of steps is to be completed for each of your VSTO add-in projects for Visio. Let’s do these steps for our MyVisioVSTOAddin project. The excerpt below is from Deploying Visual Studio 2005 Tools for Office Second Edition Solutions Using Windows Installer: Walkthroughs (Part 2 of 2) with my revisions:

Walkthrough: Enhancing the Visio Add-in Setup Project

This section describes how to enhance the Setup project that Visual Studio defines when you create an Outlook add-in project. It explains how to perform the following steps:

·        Modify the Setup project so that it installs the prerequisites: the VSTO 2005 SE runtime and, optionally, the Visual Studio 2005 Tools for Office Language Pack.

·        Add a step to the Setup project to grant security trust to the customization assembly.

·        Add launch conditions to the Windows Installer (.msi) file to prevent installation if the prerequisites are not installed.

Signing the Assembly

Later in this article, you will grant trust to the customization assembly based upon a strong name and its location. However, you must first sign the assembly.

To sign the assembly

1.    In Solution Explorer, right-click MyVisioVSTOAddin, and then click Properties.

2.    Click the Signing tab.

3.    Select the Sign the assembly check box.

4.    In the Choose a strong name key file list, click <New. . .>.

5.    Type the name MyVisioVSTOAddin in the Key file name box.

6.    Type a password in the Enter password and Confirm password boxes.

7.    Click OK.

8.    Close the Properties pages.

 

Adding the Prerequisites to the Setup Project

Add the prerequisites that the bootstrapper will install. A later step addresses adding launch conditions.

To add the prerequisites

1.    In Solution Explorer, right-click MyVisioVSTOAddinSetup, and then click Properties.

2.    In the Property Pages dialog box, click Prerequisites.

3.    In the list of prerequisites, select the following items:

a.     2007 Microsoft Office Primary Interop Assemblies

b.    Microsoft Visual Studio 2005 Tools for Office SE Runtime

4.    Select Microsoft Visual Studio 2005 Tools for Office Runtime Language Pack if any users run your solutions with non–English settings for Windows. These users must have the Visual Studio 2005 Tools for Office Language Pack to see runtime messages in the same language as Windows.

5.    Click OK twice.

Adding a Custom Action to Grant Trust to the Assembly

Grant trust to the customization assembly using the supplied custom action sample.

To add the supplied project

1.    Using Windows Explorer, copy the SetSecurity project from the {SamplesDir}\projects directory to the directory that contains the OutlookAddin solution.

Tip:

By default, the {SamplesDir} directory is C:\Program Files\Microsoft Visual Studio 2005 Tools for Office SE Resources\VSTO2005SE Windows Installer Sample

2.    In Solution Explorer, right-click MyVisioVSTOAddin.

3.    Point to Add on the shortcut menu, and then click Existing Project.

4.    Select the SetSecurity project.

5.    Click OK.

6.    In Solution Explorer, right-click the SetSecurity project, and then click Build.

[If you are running on Vista, you should copy the setup project to a folder outside of the Program Files tree.]

To add the primary output of the custom action project to the Setup project

1.    In Solution Explorer, right-click MyVisioVSTOAddinSetup.

2.    Point to View on the shortcut menu, and then click Custom Actions.

3.    In the Custom Actions editor, right-click Custom Actions, and then click Add Custom Action.

4.    In the Look In list, click Application Folder, and then click Add Output.

The Add Project Output Group dialog box opens.

5.    In the Project list, click SetSecurity.

6.    Select Primary output from the list of output types, and then click OK.

7.    Verify that Primary output from SetSecurity (Active) is added to the list of primary outputs for the Setup project.

This enables the Windows Installer file to run the custom action that edits the application manifest.

To add the custom action data for the Install method

1.    In the Custom Actions editor, expand Install.

2.    Right-click Primary output from SetSecurity (Active), and then click Properties Window.

3.    In the Properties window, set the CustomActionData property to the following string. Enter this as one long string, and change MyCompanyName to your company name.

/assemblyName="MyVisioVSTOAddin.dll" /targetDir="[TARGETDIR]\" /solutionCodeGroupName="MyCompanyName.MyVisioVSTOAddin" /solutionCodeGroupDescription="Code group for MyVisioVSTOAddin" /assemblyCodeGroupName="MyVisioVSTOAddin" /assemblyCodeGroupDescription="Code group for MyVisioVSTOAddin" /allUsers=[ALLUSERS]

Tip:

You do not need to add extra quotation marks if your company name contains a space.

To add the custom action data for the Rollback method

1.    In the Custom Actions editor, expand Rollback.

2.    Right-click Primary output from SetSecurity (Active), and then click Properties Window.

3.    In the Properties window, set the CustomActionData property to the following string:

/solutionCodeGroupName="MyCompanyName.MyVisioVSTOAddin"

To add the custom action data for the Uninstall method

1.    In the Custom Actions editor, expand Uninstall.

2.    Right-click Primary output from SetSecurity (Active), and then click Properties Window.

3.    In the Properties window, set the CustomActionData property to the following string:

/solutionCodeGroupName="MyCompanyName.MyVisioVSTOAddin"

Note:

Although you did not override the Commit method with a custom action, the base Windows Installer class provides an implementation. Thus, you must still call the method. However, it does not require any custom action data.

Adding Launch Conditions to the Windows Installer File

When the user runs Setup.exe, the Windows Installer checks for the prerequisites, and installs them if necessary. Alternatively, the user can double-click the .msi file to install the solution. In that case, the prerequisites are not installed and the solution cannot run. In other cases, Setup might fail because resources it needs are not present; for example, custom actions might require the .NET Framework.

This section shows you how to use the Launch Conditions editor to add launch conditions to the .msi file to prevent installation if certain dependencies are not installed.

To view the Launch Conditions editor

1.    In Solution Explorer, right-click MyVisioVSTOAddinSetup.

2.    Point to View on the shortcut menu, and then click Launch Conditions.

Add a launch condition for the VSTO 2005 SE runtime.

To add a launch condition for the VSTO 2005 SE runtime

1.    In the Launch Conditions editor, right-click Requirements on Target Machine, and then click Add Registry Launch Condition.

2.    Select the newly added search condition, Search for RegistryEntry1.

3.    Rename the search condition to Search for VSTO 2005 SE Runtime.

4.    In the Properties window, change the value of Property to VSTORTVERSION.

5.    Also in the Properties window, set the value of RegKey to the following string.

Software\Microsoft\vsto runtime Setup\v2.0.50727

6.    Leave the Root property set to vsdrrHKLM and change the Value property to Update.

7.    Select the newly added launch condition, Condition1.

8.    Rename it to Display message if the Visual Studio 2005 Tools for Office SE Runtime is not installed.

9.    In the Properties window, change the value of the Condition property to the following string.

VSTORTVERSION >= "#1"

10.  Leave the InstallURL property blank.

11.  Change the value of the Message property to The Visual Studio 2005 Tools for Office SE Runtime is not installed. Please run Setup.exe.

If any users run your solutions with non–English settings for Windows, they must have the Visual Studio 2005 Tools for Office Language Pack to see runtime messages in the same language as Windows. Add a launch condition to check for the Language Pack.

To add a launch condition for the Visual Studio 2005 Tools for Office Language Pack

1.    In the Launch Conditions editor, right-click Requirements on Target Machine, and then click Add Windows Installer Launch Condition.

2.    Select the newly added search condition, Search for Component1.

3.    Rename the search condition to Search for VSTO Language Pack.

4.    In the Properties window, in the ComponentId property, type the following GUID:

{2E3A394E-C9BD-40C3-9990-BA7AF7C8B4AF}

5.    Change the value of Property to COMPONENTEXISTS_VSTOLP.

6.    Select the newly added launch condition, (Condition1).

7.    Rename it to Display message if the Visual Studio 2005 Tools for Office Language Pack is not installed.

8.    In the Properties window, change the value of the Condition property to COMPONENTEXISTS_VSTOLP.

9.    Leave the InstallURL property blank.

10.  Change the value of the Message property to The Visual Studio 2005 Tools for Office Language Pack is not installed. Please run Setup.exe.

When you create the launch conditions for the VSTO 2005 SE runtime and the Visual Studio 2005 Tools for Office Language Pack, you must right-click the Requirements on Target Machine node. This created both the search condition and the corresponding launch condition.

Testing the Installation

To test your Windows Installer, run it on a computer other than your development computer, because many of the prerequisites are already installed. Remember to run the Setup.exe file to test the bootstrapper. Remember first to build your Setup project.

To build Setup

·        In Solution Explorer, right-click the MyVisioVSTOAddinSetup project, and then click Build.

Conclusion

As you can see, there are some extra steps that you have to complete in order to deploy a VSTO 2005 SE add-in for Visio. Shared add-ins are more straightforward when it comes to deployment. However, the payoff of using a VSTO 2005 SE to create Visio add-ins is significant. You will be able to digitally sign your assembly and take advantage of the VSTO add-in loader.

 

--Chris

 This posting is provide “AS IS” with no warranties, and confers no rights.

Some of you have discovered that the Visio Add-in or Add-on Wizard does not work in Visual Studio 2005. Bill Morein, a Program Manager on the Visio team, posted a great article on his blog that describes how to use the Shared Add-in Wizard to create a Visio Add-in. If you want to create an Add-on, you'll have to use Visual Studio 2003 first, then upgrade your project to Visual Studio 2005.

The COM Shim Wizard described in this article doesn't work in Visual Studio 2005 either. You can either upgrade a Visual Studio 2003 or create your own COM Shim manually if you want to codesign and isolate your Visio add-ins in Visual Studio 2005. The concepts in this article targeted for Office XP describes how to create a COM Add-in Shim project.

--Chris

 This posting is provide “AS IS” with no warranties, and confers no rights.

I think the Visio application environment is pretty impressive because of all the things you can do to customize the user interface. There are not very many apps out there that will let you add your own custom windows. Visio allows developers to do just that by enabling you to add Windows Forms as anchor bar windows. The Custom Properties window and the Pan & Zoom window are examples anchor bar windows. They can be docked, pinned, and resized on top of the Visio drawing surface.

 

I hope by now you have downloaded the Visio 2003 SDK. It has so many code samples for VB6, VB.NET and C#. There is even a sample that shows you how to create an anchor bar window. It also shows you how to drag and drop items from a list view control on to the Visio drawing surface as a shape. For those of you who are new to the Visio 2003 SDK, or Visio development in general, I would like to show you how to use the Code Librarian samples included with the Visio 2003 SDK.

 

The code samples in the Code Librarian are intended to be used in a variety of development scenarios. You can use them when creating a Visio add-in or add-on, when using the Visio drawing control, or even in standard Windows Applications that just launch and automate the Visio application environment. The Anchor Bar Usage sample would most commonly be used in a Visio add-in scenario, but for illustrative purposes, we will create a standard Windows Application:

 

1. First, launch Microsoft Visual Studio .NET 2003.
2. Create a New Project.
3. In the New Project dialog, select Visual Basic Projects. Then, select the Windows Application template.
4. Name the project Anchor Bar Usage, or whatever you want. Click OK.

 

Next, you will need to add a reference to the Visio Primary Interoperability Assembly (“PIA” for short). The Visio PIA gives you access to the COM-based Visio Object Model. To add a reference to the Visio 11 PIA:

 

1. From your VB.NET project, click the Project menu, and then click Add Reference.
2. In the Add Reference dialog, click the COM tab.
3. Scroll down the list and select Microsoft Visio 11.0 Type Library. Click the Select button, then click OK

 

Then you need to remove the default root namespace that is assigned when creating Visual Basic .NET projects. Note: You don’t have to do this in C# projects.

 

1. In Visual Studio .NET, click the Project menu, and then click Anchor Bar Usage Properties.
2. Under the General properties, remove the contents of the Root namespace text box. Click OK.

 

Now let’s get some code from the Code Librarian. After installing the Visio 2003 SDK, you should have a shortcut titled Microsoft Office Visio Code Librarian Viewer under the Microsoft Office Visio 2003 SDK Start Menu folder. Go ahead and start up the Code Librarian.

 

The Code Librarian has a tree in the top left-hand corner that allows you to navigate the different samples. Alternatively, you can use the search button on the toolbar. Find the Anchor Bar Usage sample for Microsoft Visual Basic .NET under User Interface.

 

The Anchor Bar Usage sample consists of two parts: a form and a module. Let’s add the module first because it’s more straightforward:

 

1. In Visual Studio .NET, click the Project menu, and then click Add New Item.
2. Select the Module template.
3. Name it AnchorBarsUsage.vb. (Note: You can find a suggested name in the comments towards the top of the sample in Code Librarian.) Click OK.
4. In Code Librarian, make sure the Anchor Bars Usage module is selected in the tree.
5. Copy the code from the code pane to the clipboard.
6. Replace the contents of AnchorBarsUsage.vb with the code in the clipboard. Save.

 

Now adding the form is a bit tricky because a form as a resource file associated with it. The resource file is not in the Code Librarian, but rather in a folder where the Code Librarian database is installed. Here’s how you add the sample Anchor Bar form.

 

1. In Visual Studio .NET, click the Project menu, and then click Add New Item.
2. Select the Windows Form template.
3. Name it AnchorBarForm.vb. Click OK.
4. In Code Librarian, select the Anchor Bars Form form sample is in the tree.
5. Copy the code from the code pane to the clipboard.
6. Replace the contents of AnchorBarForm.vb with the code in the clipboard. Save.
7. Open Windows Explorer.
8. Find the Code Librarian folder. If you selected the default options during setup, it should be under \Program Files\Microsoft Office\Visio11\SDK\Samples\Code Librarian\.
9. Copy the file AnchorBarForm.resx.
10. Paste it to the Anchor Bars Usage VB.NET solution folder. There should be one there already from step #6, but replace it with the copy from steps #8 and #9.

 

Now, we are ready to use the sample. When we first created our Windows Application project, a default Windows Form was added. It should still be named Form1.vb. Let’s add a button to it to call our code sample:

 

1. In Visual Studio .NET, open Form1.vb in design mode.
2. Add a Button control to the form.
3. Double click on the Button1 to add a click event handler.
4. We need to use some namespaces. Add the following statements to the top of the code file:

 

Imports Visio = Microsoft.Office.Interop.Visio

Imports Microsoft.Samples.Visio.VBNet

 

5. Then, add the following code to the Button1_Click procedure to demo the sample code:

 

   Dim visioApp = New Visio.Application

 

DemoAnchorBar(visioApp)

 

Finally, we are ready to run our sample project. Go ahead and compile and run the project (F5). The Windows Form with the button control should display. When you click on this button, Visio should start. When it does, an anchor bar window should be collapsed towards the bottom of Visio. Hover over it to make it expand. It is populated with a list of shape names. Try dragging-and-dropping one of these items to the page. Voila!

 

This is a fairly complex sample and you should definitely step through the DemoAnchorBar function to learn how you add an anchor bar window to Visio. You should also step through the code when a drag occurs from the list view control.

 

We had to jump over some hurdles to set up the project. This sample in particular had some extra steps because it required a resource file. However, I hope you understand how you can take code straight from the Code Librarian and use it in your Visio development projects.

 

-Chris

 

 This posting is provide “AS IS” with no warranties, and confers no rights.

 

My good buddy Bill (no, not G) ran into an oddity when trying to automate the timeline shape. After you drop a timeline master to the page and set the begin-and-end dates, the time scale markers do not get updated. The labels for the begin-and-end dates are updated correctly. When you drop a milestone marker and set its date, the timeline even positions it correctly. There just seems to be something different with the time scale markers. If you right-click on the timeline, click “Configure Timeline…”, and click OK, the time scale markers magically get refreshed.

 

So how do you do this in code? Never fear, it’s possible. I should have put this in the last entry, but it didn’t cross my mind. Thanks, Bill. All you have to do is call the Timeline solution’s add-on, ts.

 

If you inspect the Action row that corresponds with Timeline shape, you’ll notice the following formula in Action cell: RUNADDONWARGS(“ts”, “/cmd=3”).  This is what brings up the Configure Timeline dialog. If you call this add-on in code while AlertResponse is turned on, the dialog won’t appear, but rather it will refresh the time scale markers. To call the add-on in code, use the Run method of the Addon object that corresponds with the “ts” add-on.

 

Here it is in VBA:

 

Public Sub TimelineTest()

   

    Dim theTimeline As Shape

    Dim theMilestone As Shape

 

    Application.AlertResponse = 1

 

    Set theTimeline = Application.ActiveWindow.Page.Drop( _

        Application.Documents.Item("TIMELN_M.VSS").Masters.ItemU("Block timeline"), _

        5.610236, 5.511811)

       

    theTimeline.CellsU("User.visBeginDate").FormulaU = _

        Application.ConvertResult("1/1/2004", VisUnitCodes.visDate, VisUnitCodes.visInches)

       

    theTimeline.CellsU("User.visEndDate").FormulaU = _

        Application.ConvertResult("12/31/2004", VisUnitCodes.visDate, VisUnitCodes.visInches)

   

    ' Refresh the timeline, here it is...

    Application.Addons("ts").Run "/cmd=3"

   

    Set theMilestone = Application.ActiveWindow.Page.Drop( _

        Application.Documents.Item("TIMELN_M.VSS").Masters.ItemU("Line milestone"), _

        5.610236, 5.511811)

   

    theMilestone.CellsU("User.visMilestoneDate").FormulaU = _

        Application.ConvertResult("7/1/2004", VisUnitCodes.visDate, VisUnitCodes.visInches)

   

    Application.AlertResponse = 0

   

End Sub

 

-Chris

 

This posting is provide “AS IS” with no warranties, and confers no rights.

 

 

 

One of our keen partners from the UK pointed out a slight quirk with the SaveAsWeb feature. Suppose you have a shape with a numeric custom property. If you give 0 as the value and save the drawing as a web page, the custom property pane in the browser displays a blank value. If you specify any other number, then it displays the correct custom property value. In the full Visio client, it shows 0 as expected. Where'd the 0 go in the web page version?

Who knows? But, here's a quick fix:

1. Open up the ShapeSheet of your shape.
2. Go to the Custom Properties section and find the Format cell of your custom property.
3. Give the following formula: IF(Prop.Duration=0,0,"#.####")

Note: Replace "Duration" with your own custom property's name.

Basically, if the value is 0, then it uses the "whole number" format (0). This makes the zero show up in the browser somehow. If it is some other value, then it uses the "general" format ("#.####"). Voila!

-Chris

 

This posting is provided "AS IS" with no warranties, and confers no rights

 

 

Many developers are used to calling VSL or EXE add-ons from ShapeSheet cells. Many of us, however, have fallen in love with C# and VB.NET. VSL's are primarily written using VC++. You can write EXE add-ons in managed code, but you want a solution that runs in-process. So what's a Visio developer gotta do? The answer is to create a COM add-in. The puzzling question that arises when attempting this approach is, "how do you 'call' a COM add-in from the ShapeSheet?"

As you know, COM add-ins are usually loaded on startup with Visio. Because they are already loaded and running, you don't really "call" COM add-ins as we do with VSL or EXE add-ons. Instead, from the ShapeSheet cell you would raise an event and handle it in your COM add-in. Visio provides the MarkerEvent event that allows you to encode application specific information in its ContextString parameter. By convention, the data that developers pass using the ContextString parameter look a lot like command line switches (e.g. "/solution=MyAddIn /cmd=100"). When the event is raised, your COM add-in would handle it by parsing the context string, determining if the marker event belongs to you, and by executing the specified command. The MarkerEvent event is the essential device to "call" commands in your COM add-in.

There are three ways of raising a marker event from a ShapeSheet cell: by using the Application.QueueMarkerEvent method, by running the QueueMarkerEvent add-on (using the RUNADDONWARGS ShapeSheet function), or by using the new QUEUEMARKEREVENT ShapeSheet function. The first way was used in a VBA procedure in conjunction with the CALLTHIS ShapeSheet function (yuck!). The second approach was introduced in Visio 2002 SR1 and is still highly useful when combined with the Persistent Events tool. And finally, Visio 2003 provides the QUEUEMARKEREVENT ShapeSheet function. Needless to say, you should raise marker events from the ShapeSheet using this function.

Here’s a recap:

1. In your COM add-in, listen to QueueMarkerEvent events (using AddAdvise, of course).
2. In an event cell (like EventDblClick), call the QUEUEMARKEREVENT function and specify the context string (e.g. "/solution=MyAddIn /cmd=100").
3. In your MarkerEvent event handler, parse the context string.
   1. Check if you raised the marker event (by checking the solution argument). If you didn’t raise the marker event, stop there.
   2. If it is yours, then execute the appropriate command (specified by the cmd argument).

 

-Chris

 

 

This posting is provided "AS IS" with no warranties, and confers no rights