Build Category Properties

The Build category properties control the build process.

Help file formats (HelpFileFormats)

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.

  Caution

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.

  Note

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.

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.

Syntax filters (SyntaxFilters)

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.

  Tip

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.

Presentation style (PresentationStyle)

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.

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

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 transformations with no colorization. The only thing it will do is import external code and normalize the leading whitespace.

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

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.

Maximum Save Component writer task cache capacity

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.

See Also