Share via

Walkthrough: Registering and Integrating a Help Collection By Using Windows Installer

  • Article

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

  1. Start Visual Studio 2008.

  2. On the File menu, point to New, and then click Project.

    The New Project dialog box appears.

  3. In the Project Types pane, expand Other Project Types, and then click Setup and Deployment.

  4. In the Templates pane, click Setup Project.

  5. Type helpdemo_setup in the Name box.

  6. 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.

  7. On the Build menu, click Configuration Manager.

    The Configuration Manager dialog box appears.

  8. 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

  1. On the Project menu, point to Add, and then click File.

    The Add Files dialog box appears.

  2. Browse to the location of your HxS-file. Select the file and click OK.

    Note

    For more information, see Adding Help Files to a Windows Installer Package.

To add collection-level files to the setup project

  1. On the Project menu, point to Add, and then click File.

    The Add Files dialog box appears.

  2. 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

  1. On the Project menu, point to Add, and then click Merge Module.

    The Add Modules dialog box appears.

  2. Browse to <drive>:\Program Files\Common Files\Microsoft Shared\Help 2.0 Compiler\Redist.

  3. Click HTML_Help_Registration__RTL_---_---.msm and click Open.

  4. On the Project menu, click Add, and then Merge Module.

    The Add Modules dialog box appears.

  5. Browse to <drive>:\Program Files\Microsoft Visual Studio 2008 SDK\HelpIntegration.

  6. Click VSIPCC_Collection_Files_RTL_---_---.msm and then click Open.

  7. 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).

  8. On the Project menu, point to Add, and then click Merge Module.

    The Add Modules dialog box appears.

  9. 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.

Note

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

  1. On the Build menu, click Build Solution to build your Help project .HxS and the HelpDemo_Setup.msi files.

    Note

    "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.

  2. 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.

  3. Open MSHelp2_RegTables__RTL_---_---.msm with Orca.

  4. 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.

  5. Populate the HelpFile table with a row for each .HxS file in the collection.

  6. 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.

  7. 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.

  8. 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.

  9. Save and close MSHelp2_RegTables__RTL_---_---.msm.

  10. On the Build menu, click Build Solution.

    The final .msi file, which includes all Help registration work completed in the previous steps, is created.

    Note

    "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.

  11. 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

Editing the Help Registration Merge Module

Consuming Help Registration Merge Modules

Other Resources

Getting Started with Help Content and Integration

Deploying a Help Collection