Publishing Visio 2007 Solutions
Summary: Learn about publishing content to Microsoft Office Visio 2007 by using a Microsoft Windows Installer (.msi) file and the Visio Solution Publishing Tool. (10 printed pages)
Saul Candib, Microsoft Corporation
August 2007
Applies to: 2007 Microsoft Office system, Microsoft Office Visio 2007
Contents
Visio Content-Publishing Overview
Why Use a Windows Installer File to Publish Visio Content?
Using a Windows Installer File to Publish Content to Visio
Creating a Windows Installer File in Visual Studio 2005
Using the Visio Solution Publishing Tool
Modifying Windows Installer Files Manually
Conclusion
Additional Resources
Visio Content-Publishing Overview
In versions of Visio earlier than Microsoft Office Visio 2003, Visio discovers content installed by solution developers by using a method known as path discovery. Path discovery searches a set of folder paths that are specified on the File Paths tab of the Options dialog box, which correspond to Visio registry keys. In Microsoft Office Visio 2003 and Microsoft Office Visio 2007, path discovery is still available, although to use path discovery in these versions, you must specify the path to your solutions in the File Paths dialog box. (In Visio, on the Tools menu, click Options, click the Advanced tab, and then click File Paths.)
In Visio 2003 and Visio 2007, you can use Microsoft Windows Installer (.msi) files to publish content to Visio. This is the method that is recommended as the best practice by Microsoft, and is the method that is used to deploy Visio products.
Why Use a Windows Installer File to Publish Visio Content?
The following list describes some of the advantages of publishing Visio content by using a Windows Installer file.
By publishing content, you can better integrate it into Visio. For example, you can more easily control the location of menu commands that start your solution or open your stencils, how the commands are named, and when they are available to users.
By publishing content, you can more easily publish localized versions of your solutions together with the Windows Multilingual User Interface Pack (MUI). (The MUI is a set of language-specific resource files that allow the user interface language to be changed, according to the preferences of individual users, to one of the 33 supported languages.)
Published content offers better performance, because published information is stored in the registry, where it can be retrieved more rapidly.
The Windows Installer Setup wizard is familiar to users and easy to use.
By publishing content, you benefit from Windows Installer repair and add-and-remove software features.
Publishing your content makes it available to all users of computers with multiple users. Path discovery works only for individual users.
Using a Windows Installer File to Publish Content to Visio
The basic steps in publishing content to Visio are as follows:
Create the add-on solutions, templates, stencils, and Help files you want to publish.
Create a Windows Installer installation package (.msi file) in Microsoft Visual Studio or in a similar program. The next section explains in more detail how to do this.
Modify the .msi file to add Visio-specific information about your content to the Publish Component table contained in that file. You can use either of these methods to modify the .msi file:
Manually, by using a table-editing tool such as the Orca database editor, which is included in the Windows Software Development Kit (SDK). This method is addressed in more detail in the section Modifying Windows Installer Files Manually, later in this article.
To obtain the Orca database editor, you must install the Windows SDK. For more information, see the Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime Components.
By using the Visio Solution Publishing Tool. This method is addressed in the section Using the Visio Solution Publishing Tool, later in this article.
Distribute the modified .msi file. Users can then run Setup.exe to publish your content.
Creating a Windows Installer File in Visual Studio 2005
Whichever method you plan to use to modify your .msi file, you must first create the file in Visual Studio, by using the following general steps.
Create a Setup project.
Set the DefaultLocation property of the Application folder in the project.
The DefaultLocation property of the Application folder determines where on the user's computer your content is installed by the Windows Installer file.
Add your content to the project.
Build the project.
The following procedures describe each of these steps.
To create a Setup project in Visual Studio 2005
On the File menu, point to New, and then click Project.
In the New Project dialog box, in the Project Types list, expand the Other Project Types node, and then click Setup and Deployment.
In the Templates list, select Setup Project.
Name the project and, optionally, the solution. Specify the location where you want to save the project file, and then click OK.
To set the DefaultLocation property of the Application folder
In the Visual Studio Editor window, click the File System (your project name) tab.
Under File System on Target Machine, right-click Application Folder, and then click Properties Window.
In the Properties window, set the value of the DefaultLocation property to the path of the folder on the user's computer where you want to install your content.
To add your content to the project
- In Windows Explorer, browse to the folder or folders where you keep your content, and then drag each piece of content (add-ons, Help files, stencils, or templates) that you want to add to the project to the Application folder icon in the Visual Studio Editor window.
To build the project
- In Visual Studio, on the Build menu, click Build Project.
Completing a Windows Installer File
Building the project creates a Windows Installer (.msi) file, the multitable installation database that Windows uses to coordinate setup. The .msi file that Visual Studio creates is only partially complete, however. It contains some information about your content (for example, it contains the names of each of the content files and the location on the user's computer where the files should be installed, and it assigns a GUID to each piece of content.) But it is missing some critical information that Visio must have to discover, register, and publish your content, including the following:
The version or versions of Visio in which you want your content to be available.
The language or languages in which you want your content to be available.
For add-ons, stencils, and templates, the menu path in the Visio user interface (UI) that you want to assign to your content.
When you complete the .msi file by entering this information and then run Setup, the .msi file installs your content and then notifies Visio that installed content has changed by modifying the value of the ConfigChangeID key at the following registry setting:
HKEY_LOCAL_MACHINE\Software\Microsoft\Office\Visio
When Visio detects a modified value for this setting, it regenerates its cache of installed content and publishes the new content it discovers to the user interface, assuming you have specified that the content be visible there.
You must enter all the necessary information about your content in the PublishComponent table, one of the tables in the .msi file. To populate the PublishComponent table, you can open the .msi file in an editing program, such as Orca, that gives you direct access to this table and many others, and enter the information manually. This is a tedious and demanding method, but there might be times when it is appropriate for you to use it. For more information, see Modifying Windows Installer Files Manually later in this article.
The following figure shows what a completed PublishComponent table looks like in the Orca window.
Figure 1. A typical PublishComponent table in Orca
.gif "Orca screen shot of a typical PublishComponent tab")
An easier way to fill out the PublishComponent table is to use the Visio Solution Publishing Tool, as explained in the following section.
Using the Visio Solution Publishing Tool
The easiest way to publish Visio content is to use the Solution Publishing Tool that is included in the Microsoft Office Visio 2007 Software Development Kit (SDK). The Solution Publishing Tool is a small program that runs outside Visio and has a simple user interface, consisting of three tables on separate tabs of the main window (one each for the various kinds of content that you can publish to Visio: templates and stencils, add-ons, and Help files) and several dialog boxes. The Solution Publishing Tool fills out the PublishComponent table automatically, based on the information you supply it. The Solution Publishing Tool also includes its own context-sensitive Help system.
Files that you create in the Solution Publishing Tool are saved as Visio Solution Publishing Configuration (.vpc) files. When you create a new .vpc file, you associate it with an .msi file that you created previously, and the Solution Publishing Tool automatically populates its tables with the names of your content files, as specified in the .msi file.
To help automate your build process, after you have saved a file in .vpc format, you can run the file from the command line to update your .msi file whenever you build your application.
Installing and Running the Solution Publishing Tool
To install the Solution Publishing Tool, you must download and install the Visio 2007 SDK. For more information, see the Visio 2007: Software Development Kit.
After you install the Visio 2007 SDK, use the following procedures to run the Solution Publishing Tool in either Windows XP or Windows Vista.
To run the Solution Publishing Tool in Windows XP
Click Start, and then click All Programs.
Point to 2007 Microsoft Office System Developer Resources, point to Microsoft Office Visio 2007 SDK, and then click Microsoft Office Visio Solution Publishing Tool.
To run the Solution Publishing Tool in Windows Vista
Click Start, and then point to All Programs.
Click 2007 Microsoft Office System Developer Resources, click Microsoft Office Visio 2007 SDK, and then click Microsoft Office Visio Solution Publishing Tool.
Creating a Visio Solution Publishing Configuration File
After you have started the Solution Publishing Tool, the next step is to create a Visio Solution Publishing Configuration (.vpc) file and associate it with the .msi file for your application that you created in Visual Studio.
To create a new .vpc file and associate it with an .msi file
In the Solution Publishing tool, click New.
In the dialog box that appears, browse to the folder that contains the .msi file that will install your solution, select the file, and then click Open.
The Solution Publishing tool automatically detects all publishable content in your .msi file and lists it on the appropriate tab of the main window.
Setting Publishing Options in the Solution Publishing Tool
You can customize how the content listed in the .msi file is published by setting options in the Solution Publishing Tool interface. To set options, double-click an individual content item in the main window to open a dialog box specific to that kind of content. For example, when you double-click a stencil file, the Stencil File Information dialog box opens, where you can set publishing options specific to stencil files.
Table 1 describes the options you can set for the various content types: add-ons, stencils, templates, and Help (.chm) files.
Table 1. Publishing options available for various content types
Content Type |
Available Publishing Options |
|---|---|
Add-ons |
|
Stencils |
|
Templates |
|
Help (.chm) files |
|
The options listed in Table 1 are addressed in more detail in the later sections of this article.
In addition, for Visio add-ons, you can specify the following:
The ordinal position of the add-on.
The localized and universal names of the add-on.
Whether the add-on performs any actions when the automation Run method is called on the add-on.
Whether a message box or dialog box appears when the user clicks About in the Run Add-On dialog box. (On the Tools menu, point to Add-Ons, and then click Run Add-On.)
Whether Visio displays the "working in background" cursor (usually an hourglass) whenever the add-on is called.
Whether the add-on name appears on Visio menus, on the list of add-ons in the Run Add-On dialog box, and in the Run macro list on the Double-Click tab of the Behavior dialog box (Format menu).
Whether add-on–specific Help appears when the user presses the CTRL key and clicks Help in the Run Add-On dialog box.
Whether the add-on starts when Visio starts.
The enabling policy for the add-on.
For more information about these add-on settings, see the Help available in the Solution Publishing Tool.
Publishing Content in One or More Languages
You can determine whether an individual stencil or template file should be made available in a single language or in multiple languages. To do so, you specify the locale identifier—for example, 1033 for US English—of the country or region in which your stencil or template file should be made available.
To publish your content in a single language, in the LCID box, specify the Visio locale ID. Clear the All LCIDs box.
To publish your content in multiple languages, select the All LCIDs box.
The entry you make for LCID determines the first half (before the backslash) of the entry in the Qualifier column for the record for this stencil or template file in the .msi PublishComponent table.
Setting the Menu Path for Stencils
In the Menu Path box for a stencil, you can specify where in the stencil menu tree and the stencil preview window to list the stencil. If you leave this box empty, the published stencil will not appear in the menus. Also, if an underscore (_) precedes any name in the menu path, the stencil will not appear in the menus.
To separate menu levels, use the backslash symbol: "\". For example, you might enter the following menu path for a stencil:
MyStencils\MyStencil.vss
Entries that you make in this box determine the first part (before the vertical separator) of the entry in the AppData column for the record for this stencil file in the PublishComponent table in the .msi file.
Setting the Menu Path for Templates
In the Menu Path box for a stencil, you can specify where in the template menu tree and template preview window to list the template, and the name for the template that will appear in these contexts. If you leave this box empty, the template will not appear in the menus.
To separate levels in the template hierarchy, use the backslash symbol: "\". For example, you might enter the following menu path for a template:
MyTemplateCategory\MyTemplateSub-Category\MyTemplateName.vst
Entries that you make in this box determine the first part (before the first vertical separator) of the entry in the AppData column for the record for this template file in the PublishComponent table in the .msi file.
Setting the Menu Path for Add-Ons
In the Menu Path box for an add-on, you can specify the path to the add-on on the Add-Ons submenu of the Visio Tools menu.
To separate menu levels, use the backslash symbol: "\". For example, you might enter the following menu path for an add-on:
MyAddons\MyAdd-on.vsl
Entries that you make in this box determine the first part (before the first vertical separator) of the entry in the AppData column for the record for this add-on file in the PublishComponent table in the .msi file.
Publishing Featured Templates
To publish a template to Visio 2007 as a featured template, in the Template Information dialog box, select the Featured Template box.
When you specify that a template is featured, the Solution Publishing Tool places the value "1" in the row for this template in the Featured Template column in the PublishComponent table in the .msi file.
This setting functions only with Visio 2007; it does not affect solutions published to Visio 2003.
Setting Alternate Names for Stencils and Templates
In the Alternate Names box, you can specify a semicolon-delimited list of alternate names for a stencil or template. Entries you make in this box determine the second part (after the vertical separator) of the entry in the AppData column for the record for this stencil or template file in the PublishComponent table in the associated .msi file.
This list overrides any existing list of alternate names in the stencil or template file that you previously specified by using the AlternateNames property of the Microsoft Office Visio Document automation object. When a stencil or template is published to Visio as an entry in the PublishComponent table in an .msi file, Visio ignores the list of alternate template names stored in the stencil or template document file and instead uses the list of alternate names in the PublishComponent table to find and open stencil and template files. The Document.AlternateNames property returns the list that is stored in the stencil or template document file, not the list of alternate names from the PublishComponent table.
Publishing Content to Different Versions of Visio
To publish content to both Visio 2003 and Visio 2007, select Visio 2003 or later in the Visio Version list in the Template Information, Stencil Information, Add-on Information, or Help File Information dialog box in the Solution Publishing Tool user interface. To publish content to Visio 2007 only, select Visio 2007 in the Visio Version list.
Running the Solution Publishing Tool from the Command Line
If you are in the development phase of your add-on project and you create frequent or daily builds, you might want to automate building your project. This is especially useful if your build process recreates your .msi file regularly. Instead of having to open the user interface of the Solution Publishing Tool to generate the PublishComponent table each time you build, once you have created a .vpc file that incorporates the settings you want for your add-on, you can use the command-line interface of the tool to generate the table as part of your build process.
To run the tool and apply your settings from the command line, use the following syntax:
your path to the Solution Publishing tool /apply config file [msi file]
where config file is the path to and name of the .vpc file you created, and msi file is the path to and name of the .msi file you are using to publish your add-on. Including the .msi file is optional—if you do not include it, the tool uses the .msi file you specified when you created the .vpc file.
For more information about correct usage when you run the Solution Publishing Tool from the command line, add the /? switch at the command prompt, as shown here:
your path to the Solution Publishing tool /?
Special Considerations for Windows Vista
For more information about publishing content on a computer that is running Windows Vista, see the Microsoft Knowledge Base article Error message when you try to run an .msi file to install an add-in for Visio 2007 on a Windows Vista-based computer: "Error 1720. There is a problem with this Windows Installer package".
The following procedure is a variant of Method 2 in this knowledge base article, which explains how to add a custom action to notify Visio of new published content to an .msi file.
To notify Visio of new published content manually by adding a custom action to an .msi file
Open the .msi file in Orca.
Locate the Custom Action table.
Right-click in the table, and click Add Row.
In the Add Row dialog box, in the Action box, type VisSolPublish_BumpVisioChangeId.
Click in the Value column for Type, and then in the Type box, type 3622.
This makes the custom action a deferred commit custom action of type "noimpersonate," which allows the .msi file to run at the administrator privilege level.
Leave the Source line blank.
Click in the Target line, and in the Target box, paste the following code.
Dim WshShell, visChangeId Set WshShell = CreateObject("WScript.Shell") try{ visChangeId = WshShell.RegRead ("HKLM\Software\Microsoft\Office\Visio\ConfigChangeID") WshShell.RegWrite "HKLM\Software\Microsoft\Office\Visio\ConfigChangeID", visChangeId + 1, "REG_DWORD" } catch(e) { // log or display a warning }Click OK to close the Add Row dialog box.
Save and then close the .msi file.
Modifying Windows Installer Files Manually
This section provides some of the information that you need if you want to modify an .msi file to populate the Windows Installer PublishComponent table manually, instead of by using the Visio Solution Publishing Tool.
For information about filling out the PublishComponent table to publish content to Visio 2003 only, see the Microsoft Knowledge Base article #832029, Description of the Windows Installer PublishComponent table for Visio 2007 and for Visio 2003.
If you are publishing content to Visio 2007 or to both Visio 2003 and Visio 2007, you must use the information in this section in addition to, or instead of, the corresponding information in the article. That is because Visio 2007 offers two new options for publishing template content: support for featured templates, and support for templates that let you specify either metric or U.S. units. However, you can only take advantage of these options if you use the component IDs that are specific to Visio 2007. See the next section for more information about these component IDs.
In addition, for Visio 2007 only, or for both Visio 2003 and Visio 2007, you can specify each language in which a content item should be published. Finally, you must use the new component IDs (GUIDs) listed in the next section that are specific to Visio 2007 when you populate the PublishComponent table to publish content to Visio 2007 only. In other respects, however, the information and examples in the article are valid. Refer to the article for more detailed instructions about other aspects of populating the PublishComponent table.
New Component IDs for Visio 2007 Only
The following table lists the component IDs you should use for the four different types of publishable content (templates, stencils, add-ons, and Help files) for publishing content to both Visio 2003 and Visio 2007, or to Visio 2007 only. Enter these component IDs in the ComponentId column in the PublishComponent table, in the appropriate row for each item of content in the .msi file.
If you intend to publish content that takes advantage of the Visio 2007-only options, such as featured templates and support for templates that let you specify either metric or U.S. units, use the component IDs in the Visio 2007 Only column. Using these Visio 2007-only IDs also prevents your content from appearing in Visio 2003 in a side-by-side installation of both versions.
The component IDs in the last column, for content to be published to both Visio 2003 and Visio 2007, are intended to be version-neutral, not only for these two versions of Visio, but also for later versions of Visio.
Content Type |
Visio 2007 Only |
Visio 2003 and Visio 2007 |
|---|---|---|
Templates |
{6D9D8B6F-D0EF-4BC0-8DD4-09DD6CE2B000} |
{CF1F488D-8D6F-499C-A78D-026E1DF38100} |
Stencils |
{6D9D8B6F-D0EF-4BC0-8DD4-09DD6CE2B001} |
{CF1F488D-8D6F-499C-A78D-026E1DF38101} |
Add-ons |
{6D9D8B6F-D0EF-4BC0-8DD4-09DD6CE2B003} |
{CF1F488D-8D6F-499C-A78D-026E1DF38103} |
Help Files |
{6D9D8B6F-D0EF-4BC0-8DD4-09DD6CE2B002} |
{CF1F488D-8D6F-499C-A78D-026E1DF38102} |
If you want to publish a file to both Visio 2003 and Visio 2007, assign the files different names. If you assign the same name to both files, Visio uses only the Visio 2007 version.
.gif "Note") Note |
|---|
If you use a tool other than Visual Studio to create your .msi file, you might have to set the value in the KeyPath column in the Component table in the .msi file. Set the KeyPath value for each row to the same value as that in the Component column, but without the letter "C" at the beginning of the value. So, for example, if the Component value is C__3A31362222AA4A5DB64B3C8515A2A9CC, set the KeyPath value to __3A31362222AA4A5DB64B3C8515A2A9CC. For more information, see the Microsoft Knowledge Base article #290997, Description of Resiliency in Windows Installer. |
Designating a Template as Featured in Visio 2007
To designate a template as a featured template in Visio 2007, add the number "1" after the final vertical separator in the AppData column for the template in the PublishComponent table. The input mask for the AppData column should then be of the following form:
Menu-Path|Alt-Names|Featured Template
For example, to publish a featured template that has the menu path "My Templates" and the alternate names "Business Flowchart" and "busflowchart.vst," use the following entry in the AppData column:
My Templates|Business Flowchart;busflowchart.vst|1
To publish a non-featured template, add a zero after the final vertical separator or add nothing after the separator. Zero is the default.
Visio 2003 ignores this distinction.
Specifying the Units for a Published Template
You can specify whether a published template uses metric or U.S. units by appending an underline symbol and either the letter m (for metric units) or u (for U.S. units) to the end of the file name for the template. So, for example, to publish the Business Flowchart template in metric units, enter it as busflowchart_m.vst in the Qualifier column in the PublishComponent table. For a template published in U.S. English, the entry in that column for the template would look like this:
1033\busflowchart_m.vst
If you publish two like-named templates that end in "_u" and "_m" respectively, Visio displays radio buttons in the Getting Started window that enable the user to select the measurement units for the template.
Visio uses this naming convention for templates it supplies in both Visio 2003 and Visio 2007. However, the option to select template units in the user interface is available only for Visio 2007.
Specifying the Languages in Which to Publish Your Content
In both Visio 2003 and Visio 2007, you can specify one or more languages in which to publish your content. For each language, add a row to the PublishComponent table and in the Qualifier column of the table, list the locale ID (LCID) of the language in which you want to publish the content, followed by a backslash and the file name. In each row for the same content item, enter identical information in all the other columns of the table.
For example, to publish a template in both German and U.S. English, enter the following information in separate rows in the Qualifier column:
1031\busflowchart.vst
1033\busflowchart.vst
To publish an add-on in two languages that are the same, add the ordinal position of the add-on to the entry, as shown in this example:
1031\0\myadd-on.vsl
1033\0\myadd-on.vsl
When you publish your content to Visio 2007 only, you automatically specify that your content is published in a language-neutral version.
If you publish the same file in both language-neutral and language-specific versions in Visio 2007, Visio uses the language-specific version of the file only if it matches the language version of the Visio application in use; otherwise, Visio uses the language-neutral version of the file.
| Note |
|---|
Non-English–language text that you enter into a Setup project in Visual Studio and thereby into the Solution Publishing Tool might not appear correctly when it is published to Visio. To overcome this problem, see the following procedure. |
To display non-English characters in your Visio content
In Visual Studio, close your Setup project.
Open the .vdproj file associated with the project in a text editor, and change the CodePage value in the file to one that reflects the LCID of the language in which you want your content to appear.
Save the .vdproj file, reopen the Setup project, and continue as to create the .msi file.
Conclusion
This article explains the benefits of using Windows Installer (.msi) files to publish your content, including add-ons, templates, stencils, and Help (.chm) files to Visio. It also shows you how to use an .msi-file editor (Orca) to edit .msi files manually and how to use the Visio Solution Publishing Tool, which is part of the Visio 2007 SDK, to edit them automatically.
Additional Resources
For more information, see the following resources: