Description of the Windows Installer PublishComponent table for Visio 2003 (832029)


The information in this article applies to:

  • Microsoft Office Visio Professional 2003
  • Microsoft Office Visio Standard 2003

IN THIS TASK

SUMMARY

This article discusses the Microsoft Windows Installer PublishComponent table and contains information about how third-party developers can use the PublishComponent table in a Microsoft Installer file (.msi) to publish content (templates, stencils, add-ons, and Help files) to Microsoft Office Visio 2003.

There are two methods that you can use to publish content to Visio 2003. In versions of Microsoft Visio that are earlier than Visio 2003, Visio discovers installed content by searching a specific set of folder paths. In Visio 2003, Visio provides a new method that can be integrated in the Setup programs that install Visio content. Setup programs that are created by third-party developers who use Windows Installer technology can publish descriptions of their Visio content to a special location on a user's computer by using the Windows Installer PublishComponent table in .msi files. This new method is somewhat more complicated. However, it is more powerful. All content that is native to Visio is published by using the published component method.

The path-discovered method that is used by versions of Visio that are earlier than Visio 2003, is supported in Visio 2003. However, because no actual Visio 2003 program content is published by using this method, by default, the paths of templates, stencils, add-ons, startup add-ons, and Help files are blank. You can set these paths for your content when you specify a semicolon-delimited list for the content that you want Visio to discover. Make sure that you do not change the file paths to point to content that is native to Visio. .

To view and to edit the PublishComponent table in an .msi file, use a table-editing tool such as the Orca database editor. Orca is included in the Windows Installer Software Development Kit (SDK). To obtain the Orca database editor, you must install the Core Software Development Kit (SDK) and the Windows Installer SDK. For more information about how to do so, visit the following Microsoft Web site:

http://www.microsoft.com/msdownload/platformsdk/sdkupdate/default.htm?p=/msdownload/platformsdk/sdkupdate/SDKInfo.htm

The advantages of using published content by using the PublishedComponent table when compared to content that is path-discovered include the following:
  • Only add-ons that are installed by the PublishComponent table are considered as installed in the Trust Installed check box on the Trusted Sources tab of the Security dialog box (on the Tools menu, point to Macros, and then click Security).
  • A higher degree of integration is available to third-party solutions. You can use add-ons, templates and stencils like "In the box" content and have more control of naming menu items that access your stencils, templates, and add-ons.
  • Increased performance for the discovery of add-ons. Enumerating published component is much faster than discovering content by searching folders on the hard disk, especially over a network.
  • More robust language-switching functionality.
  • Language fall-back support for localized solutions.
  • Support for both run-from-source and installed-locally configurations in content in the same product.
  • A cleaner solution for Web downloads that have to plug-in to the Visio interface.
back to the top

Notification That Published Content Changed

An .msi file that publishes Visio content must indicate to Visio that the content changed after the third-party program is either installed or removed. By doing so, the Setup program makes sure that the new content appears in the interface when the program is installed and is removed from the interface when the program is removed. For performance reasons, Visio caches PublishComponent data. Visio does not regenerate the cache unless it is instructed to do so, or unless the cache is not present.

To instruct Visio to regenerate its cache, Setup programs must modify the current value of the Visio content update REG_DWORD registry value, ConfigChangeID, to a random, non-zero value:
  • HKEY_LOCAL_MACHINE\Software\Microsoft\Office\Visio
Note Each time that the Setup program changes installed Visio content by either installing or removing templates, stencils, add-ons, or Help files, the registry value must be modified to use a different non-zero value.

back to the top

Localization of Published Components

To publish localized versions of components, the locale ID in the Qualifier field must match the target language. Additionally, any data that is displayed in the Visio interface may also require localization.

In Visio 2003, you do not have to localize file names because all files are displayed in the interface with a name that is extracted from the AppData field.

back to the top

Visio PublishComponent Table Reference

Windows Installer PublishComponent Table

ColumnTypeKeyNullableInformation for Publishing Visio Content
ComponentIDGUIDYesNoOne of the predefined IDs that correspond to the type of Visio content (template, stencil, add-on, or Help file) that is published.
QualifierTextYesNoThe locale and file name of the component.
ComponentIdentifierYesNoExternal key to the Component table.
AppDataText--YesData that describes how a component is published.
FeatureIdentifier--NoExternal key to the Feature table.


Note For Visio-specific data in the Qualifier and the AppData columns, the pipe character ("|") is used to delimit sub-fields. The backslash character ("\") can be used as a literal escape character. To insert a pipe character into the data as a non-delimiting character, insert a backslash character before the pipe character--for example, use " \|". To insert a backslash character, use consecutive backslashes--for example, use "\\").

back to the top

Publish Visio Templates and Stencils

Published templates (.vst and .vtx files) appear in the following locations in Visio:
  • On the submenu menu that appears when you point to New on the File menu.
  • On the Choose Drawing Type task pane
  • In automation. Use references to published templates to install-by-demand or repair templates as necessary. Documents.Add("Basic Shapes.vst") is an example of a reference to a published template.
Published stencils (.vss and .vsx files) appear in the following locations in Visio:
  • On the submenu that appears when you point to Shapes on the File menu.
  • In automation. Use references to published stencils to install-by-demand or repair stencils as necessary. Documents.Add("Backgrounds.vss") is an example of a reference to a published stencil.
back to the top

Column Values in the PublishComponent Table

ColumnValueExample
Component IDContent-TypeFor templates: {CF1F488D-8D6F-499C-A78D-026E1DF38100}
For stencils: {CF1F488D-8D6F-499C-A78D-026E1DF38101}
QualifierLocale-ID\FileName1033\flowchart.vst

Note You cannot use multiples of the same file name in one Visio environment. Locale-ID\FileName must be unique so that Visio can recognize it. Therefore, use a unique file name in one Visio environment.
AppDataMenu-Path|Alt-NamesFlowchart\Work Flow Diagram Shapes|Work Flow Diagram Shapes.vss;workflow.vss
back to the top

Description of Values in the PublishComponent Table

ValueDescriptionExample
ComponentIDA predefined value for the content type.
For templates: {CF1F488D-8D6F-499C-A78D-026E1DF38100}
For stencils: {CF1F488D-8D6F-499C-A78D-026E1DF38101}		For templates: {CF1F488D-8D6F-499C-A78D-026E1DF38100}
For stencils: {CF1F488D-8D6F-499C-A78D-026E1DF38101}
Locale-IDThe decimal locale ID of the component. Common values include the following: 

Chinese (Traditional)	1028
German		        1031
English (U.S.) 	        1033
French			1036
Japanese		1041
Korean			1042	
Chinese (Simplified)	2052

1033
FileNameThe file name (without the path) of the template or stencil.flowchart.vst
Menu-PathFor templates, the Menu-Path specifies where the template is displayed in the templates menu tree and in the Choose Drawing Type task pane. For stencils, the Menu-Path specifies where the stencil is displayed in the stencils menu tree.
If this value is an empty string, the template or stencil is not displayed in the menus.
If an underscore character (_) comes before any name in the menu path, the template is not displayed in the menus.

The last portion of the menu path is also used in the file name in the Visio user interface. For templates, the file name is displayed in the most-recently used templates list. For stencils, the file name is displayed in the title bar of the stencil. 		Flowchart\Work Flow Diagram Shapes.
Alt-NamesA semicolon-delimited list of alternate names for the file. If this value is specified, the value overrides any alternate names that are stored in the file by the AlternateNames property of the Document object.Work Flow Diagram Shapes.vss;workflow.vss
back to the top

Publish Add-ons

Published add-ons that are implemented in .vsl and .exe files appear in the following locations in Visio:
  • On the submenu that menu that appears when you point to Add-Ons on the Tools menu, and then click Run Add-On, or when you click the add-on from the Add-ons submenu.
  • On the Double-Click tab of the Behavior dialog box for a shape (select a shape, and then on the Format menu, click Behavior).
  • In a shape's ShapeSheet.
  • In automation.
back to the top

Column Values in the PublishComponent Table

ColumnValueExample
Component IDContent-Type{CF1F488D-8D6F-499C-A78D-026E1DF38103}
QualifierLocale-ID\Number\FileName1033\0\add-on.vsl
AppDataMenu-Path|Localized-Name|Universal-Name|Ordinal|Attrs|Enable-Rule|Invoke-OnVisio Extras\&Database Wizard...|Database Wizard|DBWiz|1|1|65535|0
back to the top

Description of Values in the PublishComponent Table



ValueDescriptionExample
ComponentIDA predefined value for the content type. For add-ons:
{CF1F488D-8D6F-499c-A78D-026E1DF38103} 		{CF1F488D-8D6F-499C-A78D-026E1DF38103}
Locale-IDThe decimal locale ID of the component. Common values include the following: 

Chinese (Traditional)	1028
German		        1031
English (U.S.) 	        1033
French			1036
Japanese		1041
Korean			1042	
Chinese (Simplified)	2052

1033
NumberYou must use consecutive numerals, starting from 0 (zero), to number add-ons that are implemented in a single Visio library file (.vsl). However, you do not have to do so in any particular order. For each .vsl file, there must be at least one published add-on with its number set to 0 (zero). For add-ons that have an .exe extension, the number value must be set to '0' because there can only be one add-on in a single .exe file.0
FileNameThe file name (without the path) of the add-on. add-on.vsl
Menu-PathThe Menu-Path describes where the add-on is displayed in the add-ons menu tree.

If this value is an empty string, the add-on is not displayed in the menus.
If an underscore (_) comes before any name in the menu path, the add-on is not displayed in the menus.		Visio Extras\&Database Wizard...
Localized-NameThe localized name of the add-on. This name is displayed in locations in the Visio interface that lists add-ons.Database Wizard
Universal-NameThe non-localized name of the add-on. This name is not displayed in the Visio interface but may appear in the ShapeSheet when used with the RUNADDON() and RUNADDONWARGS ShapeSheet functions. This name is used to call an add-on from code. Executable add-ons must be published to use this field because they cannot be queried at runtime.DBWiz
OrdinalThe 1-based ordinal position of an add-on in a .vsl or .exe file.


For add-ons in a Visio Library File (.vsl), this value must match the value that is returned by the add-on in response to the following message: V2LMSG_ENUMADDONS

For executable add-ons, this value is always set to 1. 		1
Attrs This value defines the attributes of the add-on. It is a decimal representation of a bit mask that describes the attributes of the add-on. This value is a bitwise OR value of one or more of the following constants that are defined in the VAO.h in the Visio SDK: 

Performs actions			1
Has an About dialog box			2
Provides help				4
Display the wait cursor when running	8
Do not display add-on in the interface	16

Executable add-ons must be published to support attributes because they cannot be queried at runtime.

For add-ons that are implemented in a .vsl file, this value overrides the value that is specified in the add-on. 		1
Enable-RuleThis value specifies the enable rule of the add-on. The value for the enable rule in must be a decimal value. Generally, it may be easier to first determine the equivalent hexadecimal value for the enable rule, and then convert the hexadecimal value to a decimal value before you add it to the PublishComponent table.

An add-on can be always enabled. When an add-on is always enabled, the enable rule is 65535. This is the default enable rule for an executable add-on. The equivalent hexadecimal value of 65535 is 0xffff.

An add-on that is implemented in a Visio library file (.vsl) can be dynamically enabled. When an add-on is dynamically enabled, Visio queries the add-on to determine its enable state. Because this query is performed each time the add-on is called, dynamically-enabled add-ons can result in significant performance decreases. Microsoft does not recommend using dynamically-enabled add-ons unless you require it. The enable rule for dynamically-enabled add-ons is 0. Executable add-ons cannot be dynamically-enabled.

Add-ons can also be conditionally enabled. Conditionally-enabled add-ons have certain enable conditions that must be met and that are first verified by Visio before the add-on is enabled. For example, an add-on may require that the active window is a drawing window. Add-ons that are enabled based completely on enable conditions are frequently referred to as "statically-enabled" add-ons. In versions of Visio that are earlier than Visio 2003, only add-ons that are implemented in a .vsl file can be statically-enabled. In Visio 2003, executable add-ons that are published by using the PublishedComponent table can be statically-enabled. For statically-enabled add-ons, the enable rule must be a bitwise OR combination of the following low-level enable-condition flags: 

                                                      Decimal Hexadecimal
--------------------------------------------------------------------------
Document is active (required for all enable-rules) 	1 	0x0001
Window is active (required for all window types) 	2 	0x0002
Active window is a drawing window 			4  	0x0004
Active window is a stencil window 			8  	0x0008
Active window is a ShapeSheet window 			16 	0x0010
Active window is an icon window 			32 	0x0020
Command target active (required for all target types) 	64 	0x0040 
Command target is a page 				128  	0x0080
Command target is a master 				256  	0x0100
Selection                                               512     0x0200

Note For a list of some common enable conditions values for statically enabled add-ons, see the "Appendix" section later in this article.

Visio also supports add-ons that are partially-dynamically enabled. These add-ons are referred to as "statically-then-dynamically-enabled" add-ons. Visio queries the add-on for its enable state when its static enable conditions are satisfied. This combination of static and dynamic enabling does not affect performance as much as dynamically-enabled add-ons. However, this combination may result in some performance decreases. Only add-ons that are implemented in .vsl files can be statically-then-dynamically enabled. The enable rule of statically-then-dynamically-enabled add-ons must be a bitwise OR combination of the flags that are listed earlier in this article and the dynamic-extended value of 32768. The equivalent hexadecimal value of 32768 is 0x8000).		To specify that the add-on is enabled only if a drawing window is active, set the enable rule to a value of 7 (0+1+2+4).

To specify that Visio queries the add-on for the enable status only when the active command target is a page, set the enable rule to a value of 33089 (32768+1+64+256.
Invoke-OnThis value specifies whether the add-on starts when you start Visio. The value can be set to either 0 (zero) or 1 as follows: 
Do not start the add-on when Visio starts  0 
Start the add-on when  Visio starts        1
For add-ons that are implemented in a .vsl file and that are published by using the PublishedComponent table, this value overrides the Invoke-on attribute that is defined in the add-on. 		1
back to the top

Publish Visio Help Files

Published Help files (.chm ) appear in the following locations in Visio:
  • In automation. Use references to published Help files to install-by demand or repair Help files as necessary. Application.InvokeHelp("myhelp.chm" , 15, 0) is an example of a reference to a published Help file.
  • In Shape Help. The Help file that is specified when you click Special on the Format menu, and then click Help is installed-by-demand and repaired as necessary.
back to the top

Column Values in the PublishComponent Table

ColumnValueExample
Component IDContent-TypeFor Help files:
{CF1F488D-8D6F-499C-A78D-026E1DF38102}
QualifierLocale-ID\FileName1033\flowchart.vst
back to the top

Description of Values in the PublishComponent Table

ValueDescriptionExample
ComponentIDA predefined value for the content type.
For Help files: {CF1F488D-8D6F-499C-A78D-026E1DF38102} 		For Help files: {CF1F488D-8D6F-499c-A78D-026E1DF38102}
Locale-IDThe decimal locale ID of the component. Common values include the following: 

Chinese (Traditional)	1028
German		        1031
English (U.S.) 	        1033
French			1036
Japanese		1041
Korean			1042	
Chinese (Simplified)	2052

1033
FileNameThe file name (without the path) of the Help file or answer wizard file. myhelp.chm
back to the top

REFERENCES

For more information about the PublishComponent table, visit the following Microsoft Web site:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/publishcomponent_table.asp

For more information about Visio, visit the following Microsoft Web site:

http://www.microsoft.com/office/visio

back to the top

Appendix

List of Common Enable-Conditions Values Of Statically-Enabled Add-ons

The following is a list of some common enable-conditions values of statically-enabled add-ons:

Needs document			1
Needs window			3
Needs drawing window		7
Needs page window		135
Needs master window		263
Needs stencil window		11
Needs ShapeSheet window		19
Needs icon window		35
Needs target			65
Needs page target		193
Needs master target		321
Needs selection target		577

back to the top
Modification Type:MinorLast Reviewed:3/9/2005
Keywords:kbtemplate kbinfo KB832029 kbAudDeveloper kbAudITPRO
©2004 Microsoft Corporation. All rights reserved.