Use MSBuild.exe to build help file builder projects from the command line. It can be found in the %SystemRoot%\Microsoft.NET\Framework\v[version] folder where "[version]" is an appropriate version of the .NET Framework (currently 4.0.30319). All of the usual MSBuild command line options can be used. You can use the /property:n=v option (short form: /p:n=v) to override project property values where "n" is a property name and "v" is the value to use. Below are some common command line option and property overrides not directly represented by a matching help file builder project property. For a full list of MSBuild command line options, see the MSBuild Command Line Reference

Note
Regardless of any verbosity level setting, full output from the build is always saved to the log file. As with the GUI builder, the help file and the log file can be found in the folder specified in the project's OutputPath property after a build.

Prefix options with '-' or '/'. Property values should be enclosed in double quotes if they contain spaces, commas, or other special characters. All relative paths specified on the command line and those in a response file (see below) are relative to the project's path as usual. Below are a couple of example command lines:

%SystemRoot%\Microsoft.NET\Framework\v4.0.30319\MSBuild.exe
  /p:Configuration=Release HelpFile.shfbproj

%SystemRoot%\Microsoft.NET\Framework\v4.0.30319\MSBuild.exe
        /p:CopyrightText="Copyright \xa9 2006-2011"
        /p:FeedbackEMailAdress="Eric@EWoodruff.us"
        HelpFile.shfbproj

Note
Property names specified on the command line or in response files are case-insensitive as are simple property values. However, XML-based property values (the collection-based ones) are case-sensitive with regard to the element names. The values of the elements themselves are case-insensitive.

In addition to specifying project option overrides on the command line, MSBuild supports response (.rsp) files that contain a complex list of command line options used to build help file projects. Each option can be on a separate line or all options can be on one line. Comment lines are prefaced with a # symbol. The @ switch is used to pass another response file to MSBuild.exe.

%SystemRoot%\Microsoft.NET\Framework\v4.0.30319\MSBuild.exe @ResponseFile.rsp

As noted above, the CustomBeforeSHFBTargets and CustomAfterSHFBTargets properties can be set to the names of MSBuild project files containing property and/or target definition overrides. The CustomBeforeSHFBTargets property is useful for specifying overrides for complex properties such as those for build component configurations, plug-in configurations, and API filter settings as you can specify them using normal XML that spans multiple lines. An example override file is shown below:

Important
The paths to the target override files should be fully qualified as relative paths on them are evaluated by MSBuild based on the help file builder's target file location. Do not enclose the project filename in single quotes or it will be ignored. If necessary, enclose the entire command line parameter in double quotes.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <HtmlHelpName>TestDoc</HtmlHelpName>
    <CleanIntermediates>True</CleanIntermediates>
    <RootNamespaceTitle>Root Namespace Container</RootNamespaceTitle>
    <PresentationStyle>Hana</PresentationStyle>
    <HelpTitle>Test Help File</HelpTitle>
  </PropertyGroup>
</Project>

The help file builder target definition file contains several targets that can be overridden to define custom behavior that occurs before and after the help file builder build targets. These can be defined in a custom project file specified with the CustomAfterSHFBTargets property.

Note
These targets are not executed when built from within the standalone help file builder GUI. These are only executed when built using MSBuild.

Help file builder projects are supported in Visual Studio if you install the Visual Studio extension package. In addition, a post-build event in a Visual Studio project can be used to build them. To do so, right click on a project name in the Solution Explorer, select Properties, and select the Build Events sub-item. Click in the Post-build Event Command Line option to enter the command line to run. You can click the Edit Post-build button to open a dialog with a larger editor and a list of available macros. Below is an example of a common command line script that can be used (lines wrapped for display purposes). Replace the path to the tool with the path where you installed it on your PC. The IF statement prevents building the help file in debug builds where it may not be needed.

IF "$(ConfigurationName)"=="Debug" Goto Exit

ECHO Building SHFB help file via MSBuild
"$(SystemRoot)\Microsoft.NET\Framework\v4.0.30319\MSBuild.exe"
    /p:CleanIntermediates=True /p:Configuration=Release
    "$(SolutionDir)Doc\SandcastleBuilder.shfbproj"

:Exit

In a solution with multiple projects that are documented by the same help file builder project, the post-build event should be defined on the last project built by Visual Studio. If the projects are documented individually, you can place a post-build event on each one.

Other automated build tools also exist. As long as the build tool supports execution of command line based executables with parameters such as MSBuild.exe, you should be able to integrate it with the build process in a similar fashion.

Other Resources