Click or drag to resize
Sandcastle Help File BuilderBuild Category Properties
Help file formats (HelpFileFormats)

This property lets you specify the type of help file to build (HTML Help 1, MS Help 2, MS Help Viewer, a website, an Open XML document, or various combinations of these options when supported by the selected presentation style). The default is to produce an HTML Help 1 format file. To build multiple formats at the same time, put a check next to each type that you want to build concurrently.

Caution note Caution

Be aware that if an option is selected that produces a website, the output folder specified by the Output Path property will be cleared of all of its current content without any prompting before the web site content is copied to it. In other words, don't do something stupid like set it to the root of your C: drive or your desktop folder. The help file builder will take steps to try and prevent this from happening. When producing a help file alone, the output folder is not cleared.

Note Note

The Open XML format has certain requirements that must be met in order to produce a valid document. See the Open XML Document Help File Format topic for details.

When producing a website, various additional files will be copied to the root of the output folder based upon the presentation style selected. These files are used to provide a default index page, search features, etc. The following files will also appear:

  • WebTOC.xml - This is the XML file used to contain the table of contents information. This file is generated during the build and will contain the same entries as the help file's table of contents in a matching layout.

  • WebKI.xml - This is the XML file used to contain the keywords found in the topics. This file is generated during the build.

  • .\FTI\*.bin - This folder contains the serialized full-text index data files. The data is split up into multiple files to improve the performance and reduce the amount of information needed when doing a search.

Framework version (FrameworkVersion)

This property allows you to specify against which .NET Framework version the documentation assemblies where compiled. This affects how the MRefBuilder tool produces the reflection information file. The default is to use the .NET Framework version used to build the help file builder itself. This will also affect which set of .NET Framework comments are included in the build to document all inherited members of your classes. Set this property according to your assemblies' framework version requirements to ensure that the correct reflection information is generated.

It is also possible to select a Silverlight Framework version for Silverlight projects, a portable framework version for .NET Portable Framework projects, or the Windows Store App framework for Windows Store applications. The selected framework must be present on the system for the build to succeed. One exception is for earlier versions of the selected framework. They are set up to automatically redirect to later versions of the framework until a version is found on the current system.

Note Note

Because Silverlight, portable framework, and Windows Store app projects each use an entirely different framework, it is not possible to build a help project containing assemblies and/or Visual Studio projects that target a combination of the Silverlight framework, portable framework, Windows Store App framework, and/or the normal .NET Framework. Each must be built in their own separate help project. You can use the Version Builder Plug-In to merge the information from each help project into one help file if necessary.

Build log filename (BuildLogFile)

This property is used to specify the location and name of the build log file. If not specified, a default name of LastBuild.log is used and the log file is stored in the same folder as the help file (the location specified by the Output Path property).

Clean intermediate files after a successful build (CleanIntermediates)

This property is used to specify whether or not intermediate files created during the build are kept after a successful build or are purged. The default is True to purge the files. If not purged, you will find the files in a .\Working folder under the project's output path folder. Files that are placed there include the build scripts, configuration files, and the HTML help compiler project output files (scripts, art, HTML pages, the HTML help project, etc). The intermediate files are always retained if the build fails so that you can examine them to find the cause if necessary.

Keep the log file after a successful build (KeepLogFile)

This property is used to specify whether or not the log file is kept after a successful build. It is true by default to keep the log file. If set to false, the log file is deleted after a successful build. The log file is always kept after a failed build.

Disable the custom code block component (DisableCodeBlockComponent)

This property allows the custom Code Block Component to be disabled so that the <code> elements are rendered in their default format by the Sandcastle XSL transformations with no colorization. The only thing it will do is import external code and normalize the leading whitespace.

Fix up method signatures in C++ XML comments files (CppCommentsFixup)

This option is used to fix some issues with C++ XML comments. The C++ compiler generates non-standard method signatures in the XML comments files in certain situations. The methods affected usually involve generics. The C++ compiler also has problems resolving references to some members if it has not seen them yet. These are prefixed with "!:" which is removed by the fix-up code. If you find some C++ methods that fail to get documented, set this project property to true to have the help file builder attempt to fix them up so that they can be documented.

Indent rendered HTML (IndentHtml)

This is used to indicate whether or not the HTML rendered by BuildAssembler is indented. This is mainly a debugging aid. When set to True, the HTML is indented to make it more readable. Leave it set to False to produce more compact HTML.

Note Note

Setting this property to true will cause the first line of code element content to be indented. Set the property to false to correct the issue. This property is for testing only and should not be used in production help files.

BuildAssembler Verbosity (BuildAssemblerVerbosity)

This property is used to specify the minimum message level that the BuildAssembler tool will output. The default is All messages to log all messages. Setting it to Only warnings and errors will cause it to only output warning and error messages. Setting it to Only errors will cause it to only output errors. Using one of the warning or error settings can significantly reduce the size of the build log for large projects.

If a warning or error message does not provide enough context to diagnose the cause, resetting this property to All messages and rebuilding the project will let you see the informational messages before the warning or error to help in diagnosing the issue.

See Also