How To Build Compiled Help With DocProject
Instructions
The following steps apply to building compiled help for both
DocProjects and
DocSites:
- Open Visual Studio and load a solution that contains a DocProject or DocSite. If you would like to create a new one instead, see Creating a DocProject for a new solution or Creating a DocSite (Quick Start).
- Configure DocProject using the DocProject Properties window or the DocProject External UI, the latter being the only option for Express users. For more information, see How To Configure DocProject.
- Build the DocProject or DocSite as you would normally build a project in Visual Studio: either stand-alone by building only the project or as part of a solution build. You may also build a DocProject or DocSite on the command-line using MSBuild. For more information, see How To Build Compiled Help With MSBuild.
- When building in Visual Studio or the External UI, the Include Project Output Dialog will be shown after the build. Choose the output that you want to include as project items. (See below for more information.)
Note: Building a
DocProject or
DocSite may cause certain project items to be replaced. For instance, the
Sandcastle build engine will remove the four
Html Help Workshop files from the project before it begins to build their replacements. For more information, see
Build Process.
Build Steps
The build process uses a set of predefined steps that are provided by the particular build engine used by your
DocProject or
DocSite.
Open Visual Studio's
Output window to view the progress while compiled help is being built for your
DocProject or
DocSite. Build step errors are added to Visual Studio's Error List, which is automatically shown when a help build fails with one or more errors. For certain build steps, warnings are also added to Visual Studio's error list.
If you do not see any build information in the output window then you must change the following setting to
Normal or higher:
Tools >
Options >
Projects and Solutions >
Build and Run >
MSBuild project build output verbosity.
Sandcastle Build Steps
The build steps that are used vary depending upon the current project settings.
Compiled HelpIf included, Help 1.x is always compiled before Help 2.x. If no compiled help is configured to be built then Help 1.x HTML output is produced by Sandcastle without compiling a .chm file.
DocSites require Help 1.x HTML files, which are configured to use
local framework reference links instead of
index links, by default. The
sandcastle.help1x.config file controls this setting. If Help 1.x is not configured then it will be built anyway so that the
DocSite functions properly; although, a .chm file is not compiled unless the project is configured to do so.
Conceptual and Auto-Generated Reference DocumentationDocProject requires at least one conceptual topic
or at least one source (
project reference or
external) in order to build documentation. Conceptual documentation is always built before auto-generated reference documentation. If both are built, they are automatically merged together to form one physical documentation set.
If a
topics.xml file exists in the project's
Help\Settings folder and it contains at least one
conceptual topic then conceptual documentation will be built. Use the
Topic Explorer tool window to add new conceptual topics to the project and to manage the table of contents (TOC). For more information about
Topic Explorer, see
How To Use The Topic Management Dialog.
Build Items
Build items are special files or folders that are important to a particular build engine, such as Sandcastle. They are specified by the build engine and DocProject uses them in various aspects of the build process, such as determining whether project output must be rebuilt, what kind of build is required (e.g.,
partial or
full), for verifying input and output, and for making build output visible in Solution Explorer.
For more information, see
Build Process, Build Items.
Include Project Output Dialog
In Visual Studio Standard edition or higher and the
DocProject External UI, the
Include Project Output Dialog will be shown after the build has completed, asking if you want to include one of the output files as a project item in your
DocProject or
DocSite. For each item you may choose to either include the item or not, with the option of applying your choice to the remaining files or configuring that particular
DocProject or
DocSite to never ask you this again.
In some cases you'll want to just check
Apply To All and then click
Yes. In certain circumstances, however, you may not want to include one or more project items. For example, the
Html directory that is created by the Sandcastle build engine, when it's very large, may be excluded from a
DocProject since it doesn't have any use for the HTML files, unlike a
DocSite. In that case you must review each item, one at a time, and choose the appropriate action without checking
Apply To All or
Don't ask me this again.
If your project is under source control, you may want to check
Don't ask me this again and click
No. To view the build output you must then use the
Show all files command in
Solution Explorer's toolbar.
General Build Items
The following project items apply to all build engines:
File Name | Description |
AppData\DocSiteContents.xml | DocSite table of contents data file (does not apply to DocProjects_) |
AppData\DocSiteIndex.xml | DocSite index data file (does not apply to DocProjects_) |
Sandcastle Build Items
A total of 14 files and 2 folders may be offered for inclusion as project items by the Sandcastle build engine; however, you are only prompted to include files for the versions of compiled help that the project has built:
File Name | Help Version | Description |
{Project output dir}\{Project Name}.chm | 1.x | Compiled help file |
{Project output dir}\{Project Name}.HxS | 2.x | Compiled help file |
Help\Html\ | 1.x | Directory that contains the HTML files generated by Sandcastle for help 1.x only. |
Help\Html2\ | 2.x | Directory that contains the HTML files generated by Sandcastle for help 2.x only. |
Help\{Project Name}.hhp | 1.x | Html Help Workshop project |
Help\{Project Name}.hhc | 1.x | Html Help Workshop table of contents |
Help\{Project Name}.hhk | 1.x | Html Help Workshop index |
Help\{Project Name}.HxC | 2.x | Collection definition |
Help\{Project Name}.HxT | 2.x | Table of contents |
Help\files.HxF | 2.x | Included file list |
Help\index_a.HxK | 2.x | Associative index |
Help\index_b.HxK | 2.x | Dynamic link index |
Help\index_s.HxK | 2.x | Search window index |
Help\index_k.HxK | 2.x | Keyword index |
Help\index_n.HxK | 2.x | Named URL index |
Help\index_f.HxK | 2.x | Context-sensitive index |
Note: In the
DocSite templates the compiled help files (.chm and .HxS) are copied to the
Help\bin\ folder instead of the project's output directory, which is commonly
bin\Debug\ or
bin\Release.
Viewing the Output Files
After a
DocProject or
DocSite is built, all of the project items that you have selected to include will be visible in
Solution Explorer. Hidden output can be viewed in the
Solution Explorer by selecting the project and clicking the
Show All Files tool button or by selecting
Show All Files from the
Project menu.
Viewing Sandcastle's Output
Sandcastle's HTML output is copied into the
Html and
Html2 folders, which you may have already included as project items. More output is located in a directory named
buildhelp, such as the reflection files that were generated by Sandcastle and the XML documentation files (code comments) of the source projects.
Help 1.xTo view the Help 1.x output in Visual Studio Standard edition or higher, click the
Invoke Help 1.x Output tool bar button

.
Alternatively, and for
Express users, double-click the
{Project Name}.chm file in
Solution Explorer. If you haven't included the compiled help file as a project item then click the
Show All Files button to see it in
Solution Explorer and then double-click it.
Help 2.xTo view the Help 2.x output in Visual Studio Standard edition or higher, click the
Invoke Help 2.x Output tool bar button

.
Note that .HxS files are not associated with any program by default, so clicking this button will typically result in a prompt that reports this very issue. You can download a viewer, such as
Namespace# or
H2Viewer and associate it with the .HxS extension:
- Browse to the .HxS file in Windows Explorer and double-click it.
- When Windows asks you to locate a program for this file extension browse to a tool that can view the file, such as Namespace# or H2Viewer.
- Make sure to check, Always use the selected program to open this kind of file and click OK.
You can integrate the collection into Visual Studio using the
Help Integration Wizard, which is also useful for distributing the compiled help file to other developers. For more information, see
How to: Use the Help Integration Wizard to Add a Help Collection to Visual StudioNote: The Help Integration Wizard (HIW) is sensitive to things like spaces in the names of certain files and settings, but it doesn't provide any warnings or diagnostic information when it's configured improperly. Instead, your collection will simply not show up in
Document Explorer after it's installed. Therefore, it's imperative that you follow the instructions closely and only change other settings if you are fully aware of the potential consequences. And when in doubt, do not enter spaces or symbols that may cause the installer to not function properly.
Viewing DocSites
With
DocSites you can also run the solution as you would a normal ASP.NET Web Application project to view the help in your
DocSite web interface. Press
Ctrl+F5 to build the project and have it start in a web browser or press
F5 alone to build and attach the debugger.
For more information about
DocSites, see
DocSite Templates.
For more information about templates in general, see
DocProject Templates.