Installation Instructions

Sandcastle Tools

Collapse image Expand Image Copy image CopyHover image

[This is preliminary documentation and is subject to change.]

This topic describes the additional tools that are required to use the Sandcastle tools along with some general configuration information.

Guided Installation

Due to the number of products that need to be installed to get a working build environment, a guided installation package has been created to simplify the process. The guided installer contains most of the necessary parts and various optional components. For those parts that cannot be distributed such as the help compilers, it contains instructions on where to get them and how to install them if you need them.

Download the latest Sandcastle Help File Builder Guided Installer

When using the guided installation, you can skip the Requirements section below as it takes care of all of the required steps. See the Recommended and Optional sections for additional tools not included in the guided installation that you may find useful.

Requirements

The latest version of the Sandcastle tools can always be found at the Sandcastle Help File Builder CodePlex project site. In addition, you will need the following:

In order to use the Sandcastle tools, the following additional tools are required based on the types of help files that you want to produce. Each must be installed prior to building a help file of that particular type:

  • The HTML Help Workshop for building HTML Help 1 (.chm) help files.

  • The MS Help 2 compiler for building MS Help 2 (.HxS) help files. This must be downloaded and installed as part of the Visual Studio 2005 SDK v4.0 or the Visual Studio 2008 SDK v1.0. Note that the latest version of the Visual Studio 2008 SDK does not contain the Help 2 compiler so you must download the 1.0 version. The latest release can be installed after it if you need it.

  • The Help Library Manager and Help Library Agent for installing and viewing MS Help Viewer (.mshc) help files. These are installed as part of Visual Studio.

The tools can be installed in any order. However, be aware that if installing the Visual Studio 2005 or 2008 SDK to obtain the Help 2 compiler that both contain outdated versions of Sandcastle. This can cause the DXROOT environment variable used to locate the Sandcastle tools to be incorrect. After installing either SDK, do the following:

  1. Check the user environment variables. If you see a copy of the DXROOT environment variable there, delete it.

  2. If there is a user copy of the PATH environment variable, remove any path to the SDK version of Sandcastle that it contains. If that is all it contains, it can be deleted.

  3. Check the system environment variables to ensure that a DXROOT environment variable does exist and that it points to the correct location of the Microsoft Sandcastle tools (not the help file builder). Usually this will be C:\Program Files (x86)\Sandcastle unless you installed it in an alternate location.

Note

You may need to reboot the system in order for any environment variable changes to take effect.

Recommended Additions

The following tools are optional but you will find them useful and it is highly recommended that they be installed as well.

  • To view MS Help 2 files without registering them, you can use the H2 Viewer (free for personal use).

  • To view MS Help Viewer files with a full table of content and index support rather than in the default browser, you can use the H3 Viewer (free for personal use).

  • To register MS Help 2 files both for testing and as part of your product installation, download the shareware tool H2Reg.exe from The Helpware Group.

  • If you are going to document website projects, install the Custom Web Code Providers included as part of the Sandcastle tools installer. These make it easy to document website projects by extracting the XML comments files to a location of your choosing when the website is deployed.

Optional Items

The following items are not required to use Sandcastle or the help file builder but you may find them useful.

  • If you are documenting .NET 1.1 applications and need the Help 2 compiler tools, you can download the Visual Studio .NET Help Integration Kit 2003.

  • For a Visual Studio add-in used to create XML comments automatically, check out SubMain's GhostDoc.

  • If you need to convert HTML additional content topics to MAML, you can use the HTML to MAML Converter utility included with the Sandcastle tools installer.

See Also

Other Resources