Walkthrough: Registering and Integrating Your Help Collection Using Windows Installer
This walkthrough presents an end-to-end tutorial for creating a deployment setup project, adding the proper .msi files, and registering your Help collection to integrate it with the Visual Studio 2008 combined collection (VSCC).
Prerequisites
Before you complete this walkthrough, you must have:
A compiled Microsoft Help workshop project with a table of contents (TOC), index files, and so on.
For more information, see HelpStudio Lite documentation.
Collection level files.
Creating a Deployment Setup Project
After your Help files are built and tested, you must distribute them to your users. Compiled Help (.HxS) files must be copied to the user's computer and registered there before they can be used.
Creating a setup project
Start Visual Studio 2008.
On the File menu, point to New, and then click Project.
The New Project dialog box appears.
In the Project Types pane, expand Other Project Types, and then click Setup and Deployment.
In the Templates pane, click Setup Project.
Type helpdemo_setup in the Name box.
In the Location text box, type a path or accept the default location (<drive>:\Documents and Settings\<User Name>\My Documents\Visual Studio 9.0\Projects).
Helpdemo_setup project appears in Solution Explorer.
On the Build menu, click Configuration Manager.
The Configuration Manager dialog box appears.
Verify that the Build check box is selected for both the Release and Debug configurations of your setup project and click Close.
Adding Files to the Setup (msi) Project
After you have created your setup project, you must add the appropriate files to the project .msi.
The procedures below illustrate how to add the following categories of files:
Help (.HxS) files from your Help project
Required collection-level files
Required merge module (.msm) files
To add Help files from your Help project to the setup project
On the Project menu, point to Add, and then click File.
The Add Files dialog box appears.
Browse to the location of your HxS-file. Select the file and click OK.
Nota
For more information, see Adding Help Files to a Windows Installer package.
To add collection-level files to the setup project
On the Project menu, point to Add, and then click File.
The Add Files dialog box appears.
Browse to the location of your HxC-file. Select the file and click OK.
The collection-level files are added to the Setup project and appear in Solution Explorer.
To add Help merge modules
On the Project menu, point to Add, and then click Merge Module.
The Add Modules dialog box appears.
Browse to <drive>:\Program Files\Common Files\Microsoft Shared\Help 2.0 Compiler\Redist.
Click HTML_Help_Registration__RTL_---_---.msm and click Open.
On the Project menu, click Add, and then Merge Module.
The Add Modules dialog box appears.
Browse to <drive>:\Program Files\Microsoft Visual Studio 2008 SDK\HelpIntegration.
Click VSIPCC_Collection_Files_RTL_---_---.msm and then click Open.
Copy MSHelp2_RegTables__RTL_---_---.msm from <drive>:\Program Files\Common Files\Microsoft Shared\Help 2.0 Compiler\Redist to your setup project directory (Helpdemo_setup).
On the Project menu, point to Add, and then click Merge Module.
The Add Modules dialog box appears.
Click MSHelp2_RegTables__RTL_---_---.msm copied in step seven (7), and click Open.
Registering Your Help Collection
Help collections must be registered before users can view them. The following steps describe how to add Help registration to a product installation for deployment on end-user machines.
Nota
Registration uses a merge module editing utility named Orca (Orca.exe), which is available as part of the Microsoft Windows Installer SDK. The Windows Installer SDK can be installed from the MSDN Download Center https://msdn.microsoft.com/downloads. Search for "Orca" on the site to locate the latest download of the Windows Installer SDK.
To customize the Help Registration merge module
On the Build menu, click Build Solution to build your Help project .HxS and the HelpDemo_Setup.msi files.
Nota
"Unable to find module dependency" warnings can be ignored if the build completes successfully. These warnings are a relic of the process used to create the redistributable merge modules.
When the build is complete, open HelpDemo_Setup.msi with Orca. The HelpDemo_Setup.msi will be built in a Release subdirectory of your setup project directory.
Open MSHelp2_RegTables__RTL_---_---.msm with Orca.
Select the HelpNamespace table in MSHelp2_RegTables__RTL_---_---.msm and add a new row with the following data for your namespace.
Column
Data
NamespaceKey
<MS.HyHelp.1033>
NamespaceName
<MS.HyHelp.1033>
File_Collection
<.HxC File Table entry>
Description
My Help Integration Demo Collection
The NamespaceKey and NamespaceName entries take the form: <company prefix>.<collection>.<language ID>.
The File_Collection entry is obtained from the HelpDemo_Setup.msi File table. Find the File table entry for your .HxC file. Copy the File column value and paste it into the File_Collection column in the HelpNamespace table of MSHelp2_RegTables__RTL_---_---.msm.
Populate the HelpFile table with a row for each .HxS file in the collection.
Select the HelpFile table in MSHelp2_RegTables__RTL_---_---.msm and add a new row with the following data for each .HxS file in the collection.
Column
Data
HelpFileKey
<MyHelpProject>
HelpFileName
<MyHelpProject>
LangID
1033
File_HxS
<.HxS File table entry>
File_HxI
<.HxI File table entry>
File_HxQ
N/A
File_HxR
N/A
File_Samples
N/A
The File_HxS entry is obtained from the HelpDemo_Setup.msi File table. Find the File table entry for helpdemoproject.HxS. Copy the File column value and paste it into the File_HxS column in the HelpFile table of MSHelp2_RegTables__RTL_---_---.msm.
If the compile output type of your Help project is an .HxS file with a separate .HxI file, you must include a File_HxI entry. The File_HxI entry is obtained from your HelpDemo_Setup.msi File table. Find the File table entry for your .HxI file. Copy the File column value and paste it into the File_HxI column in the HelpFile table of MSHelp2_TegTables__RTL_---_---.msm.
Select the HelpFileToNamespace table in MSHelp2_RegTables__RTL_---_---.msm and add a new row with the following data for each .HxS file in the collection. This table maps the Help files defined in the HelpFile table to the Help namespace defined in the HelpNamespace table.
Column
Data
HelpFile_
<MyHelpProject>
HelpNamespace_
<MS.HyHelp.1033>
The HelpFile_ entry is obtained from MSHelp2_RegTables__RTL_---_---.msm HelpFile table. Find the HelpFile entry for the .HxS file. Copy the HelpFileKey column value and paste it into the HelpFile_ column in the HelpFileToNamespace table of MSHelp2_RegTables__RTL_---_---.msm.
The HelpNamespace_ entry is obtained from the MSHelp2_RegTables__RTL_---_---.msm HelpNamespace table. Find the HelpNamespace entry for the child namespace. Copy the NamespaceKey column value and paste it into the HelpNamespace_ column in the HelpFileToNamespace table of MSHelp2_RegTables__RTL_---_---.msm.
Select the HelpPlugin table in MSHelp2_RegTables__RTL_---_---.msm and add a new row with the following data for the child namespace to be plugged into VSCC.
Column
Data
HelpNamespace_
<MS.HyHelp.1033>
HelpNamespace_Parent
MS_VSIPCC_v80
File_HxT
<.HxT File table entry>
File_HxA
<.HxA File table entry>
File_ParentHxT
<.HxT parent File table entry>
The HelpNamespace_ entry is obtained from the MSHelp2_RegTables__RTL_---_---.msm HelpNamespace table. Find the HelpNamespace entry for the child namespace. Copy the NamespaceKey column value and paste it into the HelpNamespace_ column of the HelpPlugin table of MSHelp2_RegTables__RTL_---_---.msm.
The File_HxT entry is obtained from the HelpDemo_Setup.msi File table. Find the File table entry for .HxT file. Copy the File column value and paste it into the File_HxT column of the HelpPlugin table of MSHelp2_RegTables__RTL_---_---.msm.
The File_HxA entry is obtained from the HelpDemo_Setup.msi File table. Find the File table entry for .HxA file. Copy the File column value and paste it into the File_HxA column of the HelpPlugin table of MSHelp2_RegTables__RTL_---_---.msm.
The File_ParentHxT is obtained from the HelpDemo_Setup.msi. Find the File table entry for the parent .HxT file. Copy the File column value and paste it into the File_HxA column of the HelpPlugin table of MSHelp2_RegTables__RTL_---_---.msm.
For more information about editing the tables, see Editing the Help Registration Merge Module.
Save and close MSHelp2_RegTables__RTL_---_---.msm.
On the Build menu, click Build Solution.
The final .msi file, which includes all Help registration work completed in the previous steps, is created.
Nota
"Unable to find module dependency" warnings can be ignored if the build completes successfully. These warnings are a relic of the process used to create the redistributable merge modules.
Run HelpDemo_Setup.msi to install your Help collection and plug into VSCC. When the installation is complete, view the Visual Studio documentation and observe your Help collection by means of the Contents, Index, and Search windows.
See Also
Concepts
Getting Started with Help Content and Integration
Deploying Your Help Collection