Build Category Properties
The Build category properties control the build process.
This property lets you specify the type of help file to build (HTML Help 1, MS Help Viewer, a
website, an Open XML document, markdown content, 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. The Open XML and Markdown
formats cannot be combined with other formats as they produce such drastically different output.
Be aware that if an option is selected that produces a website or markdown content, 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.
The Open XML format has certain limitations and requirements that must be met in order to produce
a valid document. See the Open XML Document Help File Format topic for details.
The Markdown format has certain limitations. See the
Markdown Content 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.
This property lets you specify which languages appear in the Syntax
section of the help topics and the languages that will appear in the code examples. It can be set to one
language, a combination of languages, All to include them all, Standard
(the default) for C#, VB.NET, and C++ only, or None to remove the Syntax
section entirely. In the property page, put a checkmark next to each syntax filter that you wanted included in
the API topics.
If you want to change the order of the languages in the syntax section and code examples, add the
Syntax Component to the project on the Components category property page. Its configuration lets you modify the
order of the languages in the syntax sections and code examples.
The selected languages also control code snippet grouping or connecting them to the language
filter depending on the presentation style. As different tabs are selected or the language filter selection
changes, all related code snippets for the selected tab/language will be shown to keep them all in sync.
Adding Third-Party Syntax Filter Generators
Custom language syntax filter generators can be made available via the project's
Syntax Filters property by creating a syntax filter generator Managed Extensibility
Framework (MEF) component. Copy the syntax filter generator's assembly and any supporting files to the
.\Components and Plug-Ins folder or a subfolder beneath it in the help file builder's
Common Application Data folder. If available as a NuGet package, add it to the
project's Component Packages node. If project specific, the components can be located in the help file builder
project's folder or in a folder referred to in its Component Path property. See the
Special Folder Locations topic for more information. Refer to
the component's documentation for information about its features and configuration options. See the
Creating a Syntax Filter Generator Component topic for information on creating a
third-party syntax generator. For a list of current third-party build components, see the
Links to Resources topic.
This property is used to choose the presentation style that determines the layout and appearance of
the help topics. Several styles are provided: Default2022 (the default),
VS2013 (legacy support for Help 1 and Microsoft Help Viewer), Open XML
Document, and Markdown Content. The files for each style are located in
the .\Components folder under the main help file builder installation folder.
Adding Third-Party Presentation Styles
Custom presentation styles can be made available via the project's Presentation Style
property by creating a presentation style Managed Extensibility Framework (MEF) component. Copy the
presentation style's assembly and all supporting files to the .\Components and Plug-Ins
folder or a subfolder beneath it in the help file builder's Common Application Data
folder. If available as a NuGet package, add it to the project's Component Packages node. If project specific,
the components can be located in the help file builder project's folder or in a folder referred to in its
Component Path property. See the
Special Folder Locations topic for more information. Refer
to the presentation style's documentation for information about its features and configuration options. See the
Creating a Presentation Style Component topic for information on creating a third-party
presentation style. For a list of current third-party build components, see the
Links to Resources topic.
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.
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.
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).
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.
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.
This property allows the custom Code Block Component to be
disabled so that the <code> elements are rendered in their default format by the
transformations with no colorization. The only thing it will do is import external code and normalize the
leading whitespace.
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.
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.
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.
The BuildAssembler Save Component uses a pipeline to generate and save topic content in parallel to
improve performance. This property controls how many topics can accumulate in the writer task's cache before
blocking any further topics from being built until the cache empties out. The default is 100 topics. Decrease
this value to conserve memory or increase it to improve performance. Set it to zero for an unbounded cache size
which gives the best performance at the expense of memory. The number of topics remaining to be written is
reported at the end of the build. You can use that value to determine whether to increase or decrease this
property value for each project.
