Customizing the Build Process

{@AppDataFolder} and {@LocalDataFolder}

{@AppDataFolder} is replaced with the common application data folder for the help file builder. This is used to store third-party build components and plug-ins. {@LocalDataFolder} is replaced with the local application data folder for the help file builder. This is used to store cache files and other user settings. See the Special Folder Locations topic for more information.

{@BuildDate} or {@BuildDate:[date-format]} or {@BuildDateUtc} or {@BuildDateUtc:[date-format]}

This tag allows you to insert a build date/time into a project file or a text project property such as HeaderText or FooterText. If {@BuildDate} is used, the full date time is inserted using the default format. You can also specify a custom date format. For example: {@BuildDate:MMMM d, yyyy a\t hh:mm tt}. If the BuildDateUtc tag is used, it inserts the date in Universal Coordinated Time (UTC) instead of local time.

{@CodeSnippetsFiles}

This tag expands to a list of the conceptual content code snippets files that will be used by the Example Component in conceptual content builds. To be included, the project file must have its BuildAction set to CodeSnippets.

{@CommentFileList}

This tag expands to a list of the XML comment files that will be used to produce the help file. This tag is placed in the Sandcastle configuration file.

{@Comments}

If a FeedbackEMailAddress is specified in the project, this tag expands to the include directive that adds the "send e-mail" note to the page footers.

{@ComponentsFolder}

This tag expands to the path where the custom build components can be found. This will be the Build Components\ folder under common application data folder ({@AppDataFolder}).

{@CopyrightInfo} and {@HtmlEncCopyrightInfo}

These tags expand to an empty string if neither the CopyrightHref nor the CopyrightText project options are specified. If only one or the other is specified, then it results in the value of the project option that is present. If both are specified, it results in a link to the specified URL with the specified copyright text. The first version is plain text, the second version is HTML encoded.

{@CopyrightText} and {@HtmlEncCopyrightText}

These tags expand to the CopyrightText project option (plain text and HTML encoded).

{@Copyright}

If either or both of the copyright project options are specified, this tag will expand to the include directive necessary to place the text in the page footers.

{@DefaultTopic} and {@WebDefaultTopic}

These tags appear in the help file project template and the website index page respectively and expand to the filename of the default topic.

{@DocInternals}

This tag expands to "true" if either the DocumentInternals or DocumentPrivates project property is set to true. If both are set to false, this expands to "false".

{@ExtractFlags}

This tag expands to the flags that tell the HTML extract tool what files to create. It will generate files for the HTML Help 1 and website builds as needed.

{@FeedbackEMailAddress}, {@HtmlEncFeedbackEMailAddress}, {UrlEncFeedbackEMailAddress}, {@FeedbackEMailLinkText}

These tags expand to the FeedbackEMailAddress project option if it is specified (plain text, HTML encoded, and URL encoded) and the FeedbackEMailLinkText project option if specified (plain text). Note that if FeedbackEMailLinkText is specified, it will be used in place of the e-mail address for the {@HtmlEncFeedbackEMailAddress} tag's value.

{@FrameworkVersion}, {@FrameworkVersionShort}

These tags expand to the selected FrameworkVersion project option (full and "major.minor" respectively) and are placed in the sandcastle.config and MRefBuilder.config configuration files.

{@H2RegPlugInEntries} and {@H2RegMergeNamespaces}

These two tags expand to the plug-in and merge namespace entries in the H2Reg.ini file.

{@HHCPath}

This tag expands to the path to the HTML Help 1 compiler. This will be the path that the help builder found or the HtmlHelp1xCompilerPath project option if it is specified instead.

{@HTMLHelpName} and {@HTMLEncHelpName}

These expand to the value of the HtmlHelpName project option (plain text and HTML encoded).

{@Help1xProjectFiles}

This tag appears in the help file project templates and is used to return a list of all files that should be compiled into the help file.

{@HelpTitle}, {@HtmlEncHelpTitle}, {@UrlEncHelpTitle}, and {@ScriptHelpTitle}

These tags expand to the HelpTitle project option (plain text, HTML encoded, URL encoded, and quote-escaped for JavaScript).

{@InheritedCommentFileList}

This tag expands to a list of the XML comment files that will be used to produce the inherited documentation. This tag is placed in the Generate Inherited Documentation tool's configuration file.

{@LanguageFolder}

This tag expands to the language folder to use for the Sandcastle shared content files. If a folder is not found for the selected language, the default US-English Sandcastle shared content files are used.

{@LangId} and {@LanguageName}

These tags expands to the locale ID (LCID) and the locale ID plus language name for the Language project option.

{@Locale}

This tag expands to the locale name for the Language project option.

{@ManifestTransformation}

This tag expands to the document model transformation filename for the selected presentation style.

{@ManifestTransformationParameters}

This tag expands to the document model transformation parameters for the selected presentation style.

{@OutputFolder}

This tag expands to the full path to the output folder and is used in the templates to help the tools locate the output folder.

{@PresentationPath} and {@PresentationStyle}

The first tag expands to the path of the presentation folder that contains the art, scripts, style sheets, and transformations for the style selected with the project's PresentationStyle property. The second expands to the ID of the style itself.

{@ProjectFolder} and {@HtmlEncProjectFolder}

These tags expand to the path that contains the project file (plain text and HTML encoded). This is useful for build components that need paths relative to the project.

{@ProjectNodeName}

This expands to the root namespace page ID (the project node ID). The resolved value will be in the format R:Project_[HtmlHelpName] where "HtmlHelpName" is the value of that property from your project.

{@ProjectNodeIDRequired} and {@ProjectNodeIdOptional}

These expand to the root namespace page ID (the project node ID) that gets passed to the document model transformation. The resolved value will be in the format Project_[HtmlHelpName] where "HtmlHelpName" is the value of that property from your project. The "Optional" version may be an empty string if not used for the build.

{@ResourceItemFiles}

This tag expands to a list of the resource item files in the project that contain project overrides for the Sandcastle resource items used in the generated help topics. To be included, the project file must have its BuildAction set to ResourceItems.

{@SHFBFolder}

This tag expands to the path to the Sandcastle Help File Builder installation folder.

{@SyntaxFilters} and {@SyntaxFiltersDropDown}

These tags expand to the language filter components that determine which languages appear in the Syntax section of each help topic.

{@TargetFrameworkIdentifier}

This tag expands to target framework identifier based on the current FrameworkVersion project property setting. It will be .NETFramework for .NET versions, Silverlight for Silverlight versions, .NETPortable for the .NET Portable framework versions, or .NETCore for .NET for Windows Store Apps frameworks.

{@TocTransformation}

This tag expands to the table of contents transformation filename for the selected presentation style.

{@TocTransformationParameters}

This tag expands to the table of contents transformation parameters for the selected presentation style.

{@TokenFiles}

This tag expands to a list of the conceptual content token files that will be used by the token Shared Content Component in conceptual content builds. To appear in the list, the project file must have its BuildAction set to Tokens.

{@TransformComponentArguments}

This expands to the transform component arguments that are passed to the BuildAssembler tool's TransformComponent.

{@WindowOptions}

This tag expands to a value in the help file project that determines the window options available. Currently, a default set of options is used to display most of the common features such as the basic toolbar buttons and the search tab. If the IncludeFavorites project property is set to true, the value includes the option to show the Favorites tab too.

{@WorkingFolder} and {@HtmlEncWorkingFolder}

These tags expand to the full path to the working folder (plain text and HTML encoded) and are used in the templates to help the tools locate the files in the temporary working folder.

Build1xHelpFile.proj, BuildHelpViewerFile.proj, BuildOpenXmlFile.proj, GenerateMarkdownContent.proj

These MSBuild projects are used to build the HTML Help 1, MS Help Viewer, Open XML, and markdown help projects respectively and copy the resulting output and supporting files to the project's output folder. The MS Help Viewer version simply copies the supporting files to the project's output folder as the build engine compresses the topics into the archive that becomes the MSHC file.

GenerateInheritedDocs.proj and GenerateInheritedDocs.config

This MSBuild project and configuration file are used to generate the inherited documentation file.

GenerateRefInfo.proj

This MSBuild project is used to generate the reflection information from the documentation assemblies using MRefBuilder. The result is the reflection.org file that contains information about the types in each assembly.

Help1x.hhp

This is the help file project template for HTML Help 1 help files. This defines the basic help file options and the help window properties.

HelpContentSetup.msha, InstallMSHC.bat, and RemoveMSHC.bat

These are the template file used for the MS Help Viewer content setup file and the example scripts used to install and remove the MS Help Viewer content.

MRefBuilder.config

This configuration file is used to supply some configuration information to MRefBuilder that it uses when generating the reflection information file.

PlaceHolderNode.aml

This is a blank MAML topic used as the target for empty place holder nodes when generating MS Help Viewer files. MS Help Viewer does not support empty place holder nodes so this topic fills them so that the build succeeds and generates a valid file. A unique ID is generated for each placeholder inserted into the file.

TransformBuildLog.xsl

This XSL transformation file is used to transform the build log into something that is more readable by formatting the build steps into collapsible sections and highlight errors and warnings.