Click or drag to resize
Sandcastle Help File BuilderHelp Library Manager Launcher Utility

In order to install an MS Help Viewer file, several conditions must be met. To hide the details and save you from having to perform all of the necessary checks, the Help Library Manager Launcher utility was created. It is copied as part of the output of an MS Help Viewer build and is freely distributable and can be used as part of your product's installer. The utility was created based on information found on the HelpWare MSHC Migrate Utility FAQ and MSHC Migrate Utility How to Install Help pages.

This topic contains the following sections.

Overview

The launcher utility takes care of the following tasks before launching the Help Library Manager:

  • It checks to be sure that the Help Library Manager has been installed. If not, it exits with an error message requesting that it be installed first.

  • It checks to see if an instance of the Help Library Manager is already running. If so, the install or remove operation would fail so the launcher exits with an error message telling the user to close the currently open instance.

  • It checks to make sure that the local store has been initialized. If not, the launcher exits with an error message stating that you need to run the Help Library Manager to initialize it for the first time.

  • It checks for the required product and version or catalogName command line options. If not specified, it exits with an error message stating which one was missing.

  • If no locale command line option was supplied, it tries to determine the default locale based on the specified product and version. If a locale cannot be determined, it exits with an error message.

If the requirements are met, the Help Library Manager will be launched with the command line options passed to the launcher. If installation is requested via the sourceMedia command line option, the Help Library Manager is ran with a request for administrator privileges. For all other tasks such as removal of content, it is ran with normal privileges.

Note Note

If you are installing unsigned help content, the Help Library Manager cannot be ran in silent mode using the /silent option. It must be ran interactively so that it can confirm the installation. Removal of content, whether signed or unsigned, can be performed silently.

Installing Content

Below are a sample HelpContentSetup.msha file and an example command line for running the Help Library Manager launcher to install content. The command line is wrapped for display purposes.

Sample HelpContentSetup.msha File
Copy
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Sandcastle Test Case Library</title>
</head>
<body class="vendor-book">
    <div class="details">
        <span class="vendor">EWSoftware</span>
        <span class="locale">en-us</span>
        <span class="product">Sandcastle Help File Builder Example Project</span>
        <span class="name">Sandcastle Test Case Library</span>
    </div>
    <div class="package-list">
        <div class="package">
            <!-- NOTE: The "name" span value cannot contain any periods! -->
            <span class="name">TestCaseProject</span>
            <a class="current-link" href="TestCaseProject.mshc">TestCaseProject.mshc</a>
        </div>
    </div>
</body>
</html>
Install a Help File
Copy
REM Help Viewer 1.0
HelpLibraryManagerLauncher.exe /product "VS" /version "100" /locale en-us
        /sourceMedia "C:\FullPathToFile\HelpContentSetup.msha"

REM Help Viewer 2.0
HelpLibraryManagerLauncher.exe /viewerVersion 2.0 /catalogName VisualStudio11
        /locale en-us /wait 0 /operation install
        /sourceUri "C:\FullPathToFile\TestCaseProject.msha"

The product, version, locale, and catalogName options uniquely identify the catalog into which your help file will be installed. By default, the help file builder project properties are set to install it in the Visual Studio catalog. The sourceMedia/sourceUri option tells it to install the content based on the settings in the specified HelpContentSetup.msha file. For more information on the available command line options, see the Help Library Manager Administrator's Guide.

Tip Tip

If the product and/or version values contain spaces, they should be enclosed in quote marks.

Tip Tip

To have the launcher determine the installed locale and use it, omit the /locale and locale name parameters.

When installing unsigned content, the Help Library Manager's user interface will always appear. Follow these steps to install the content:

  1. You will be presented with a list of content that has already been installed along with content waiting to be installed. Scroll through the list to find your help content.

  2. Click the Add link next to your content to select it for installation.

  3. Next, click the Update button to install it.

  4. A security alert will appear. Click Yes to confirm the installation of the unsigned content.

  5. Once confirmed, the content is installed and the indexes are merged. This may take several minutes.

  6. Once it has finished installing the content, you an exit the Help Library Manager.

Important note Important

If you attempt to install a newer version of an already installed package, the install request will have no effect. As such, it is recommended that you always execute a request to remove the content before installing it. You can ignore any errors returned from the remove request if the content is not there.

Removing Content

Below is an example command line for running the Help Library Manager launcher to remove content. The command line is wrapped for display purposes.

Install a Help File
Copy
REM Help Viewer 1.0
HelpLibraryManagerLauncher.exe /product "VS" /version "100" /locale en-us
        /uninstall /silent /vendor "EWSoftware"
        /productName "Sandcastle Help File Builder Example Project"
        /mediaBookList "Sandcastle Test Case Library"

REM Help Viewer 2.0
HelpLibraryManagerLauncher.exe /viewerVersion 2.0 /catalogName VisualStudio11
        /locale en-us /wait 0 /operation uninstall /vendor "EWSoftware"
        /productName "Sandcastle Help File Builder Example Project"
        /bookList "Sandcastle Test Case Library"

The product, version, locale, and catalogName parameters identify the catalog from which to remove the content. The vendor, mediaBookList/bookList, and productName values should match the values from the HelpContentSetup.msha file. The uninstall and silent options tell it to uninstall the content without any interaction on the user's part.

Exit Codes

The Help Library Manager launcher will return one of the following exit code values:

Value

Description

0

The operation completed successfully.

1

The Help Library Manager was not found. It probably needs to be installed.

2

The Help Library Manager is already running. It needs to be closed first.

3

The local store is not initialized. Run the Help Library Manager to initialize it on first time use.

4

A required command line argument is missing.

5

The catalog identified by the product and version values is not installed and there wasn't enough information to create it.

6

An unknown error occurred in the Help Library Manager launcher. Post a message on the Sandcastle Help File Builder Discussion page requesting help.

100-9999

A Help Library Manager exit code. See the Help Library Manager Administrator's Guide for a list of possible exit codes and their meaning.

See Also