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 OutputPath 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 option allows you to select, add, and configure build components for the project that support the help file builder's component configuration method to interactively set their options. See the Custom Build Components topic for information on the ones supplied with the help file builder.

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.

This property allows for the removal of the custom Code Block Component so that the <code> elements are rendered in their default format by the Sandcastle XSL transformations. This completely disables code colorization and the other extensions provided by the component.

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 most recent .NET Framework version available on the system (currently 4.0.30319). 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 or a portable framework version for .NET Portable Framework projects. When a Silverlight or portable framework version is chosen, the generation of reflection information is altered so that the correct reference assemblies are included.

Note

Because Silverlight and portable framework 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, 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 lets you specify the type of help file to build (HTML Help 1, MS Help 2, MS Help Viewer, a website, or various combinations of these options). The default is to produce an HTML Help 1 format file.

Caution

Be aware that if an option is selected that produces a website, the output folder specified by the OutputPath 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. When producing a help file alone, the output folder is not cleared.

When producing a website, the following additional files are copied to the root of the output folder.

• Index.aspx - This page is used to contain the table of contents and the currently selected content page. It uses Ajax to dynamically load child nodes when first expanded and should be more efficient for large help files. It also contains a search option that lets you search for keywords in the help topics and a keyword index. A topic query string parameter can be specified. If set to the path of a page in the website, it will display that page instead of the normal default topic page.
• FillNode.aspx - This is used by the Ajax calls to dynamically load child nodes for the table of contents.
• SearchHelp.aspx - This is used by the Ajax calls to search for keywords using the full-text index.
• Web.config - This contains some necessary namespace declarations for the ASP.NET pages above.
• Index.html - This page is used to contain the table of contents and the currently selected content page. The table of contents is contained entirely within the page and may not be as efficient for large help files.
• TOC.css - This is the style sheet used for the index pages.
• TOC.js - This JavaScript file is used by the index pages. It contains the code used to implement a basic tree view with collapsible and expandable nodes, a splitter bar, and Ajax calls to load child table of contents nodes dynamically and perform keyword searches.
• 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.
• favicon.ico - This is used as the Favorites icon for the help website. You can override it with your own icon by including a file called favicon.ico in the root folder of your project.
• *.gif, *.png, *.bmp - Several image files are copied that represent the collapsed, expanded, and item nodes in the table of contents tree view and the Expand All, Collapse All, and Synch to Content options.
• .\FTI\*.bin - The FTI 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 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.

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 option allows you to select, add, and configure plug-ins for the project that are used to alter or extend the build process in various ways. See the Build Process Plug-Ins topic for information on the ones supplied with the help file builder.

This property allows you to add or edit user-defined project properties. These are custom properties that you can create to hold additional information or for use in substitution tags within other help file builder project properties. User-defined project properties themselves consist of three property values:

• Name - The name of the project propety. This cannot match the name of an existing help file builder project property, certain reserved MSBuild property names, or the name of an existing user-defined property.

• Condition - An optional condition that defines when the property will be evaluated and the given value used. This is useful if you have environment variables or other command-line defined properties in your build environment that do not exist on your development PC. In such cases, you can add a condition to define a default value while you test the project. For example, assume you define a property called MyCustomProperty with a value of "Test" and set the condition to '$(MyCustomProperty)' == ''. This is stored in the project file as:

  Copy 

  <MyCustomProperty Condition=" '$(MyCustomProperty)' == '' ">Test</MyCustomProperty>

  The property will only be defined in the project using the given value if it does not already have a value defined elsewhere (i.e. from a command line property definition, an environment variable, etc.).

  Caution
  Entering an invalid Condition value can cause the project to become unloadable. If this occurs, you will need to edit the project file by hand with a text editor to delete the invalid property.

• Value - This defines the value to use for the property. User-defined property values are not escaped and thus can contain references to other project or MSBuild properties.

Note
The MSBuild project object does not provide a way to delete or rename project properties. As such, if you need to delete or rename a user-defined property, open the help file builder project in a text editor, locate the element and delete or rename it by hand.

Other Resources