Build Actions
All file project items have a BuildAction property that determines how they
will be handled at build time.
None
This is the default build action for all files without a recognized file extension as well as all conceptual content topic files (.aml). Files with this build action are ignored at build time and will not be compiled into the help file.
Note
To include conceptual content topics in a help file, add a content layout file to the project and
use it to set the order and titles of the topics. For images that appear in conceptual content topics, use the Image build action.
Tip
Setting the build action to None on any file type will cause it to be
ignored during the build. This is useful for testing a different content layout while retaining the old file or
perhaps creating different content layouts that can be selected by altering the build action to select the one
you want for a given build.
Content
This is the default build action for any file that is considered to be HTML-based additional content or a supporting file. File extensions recognized include: .asp, .aspx, .ascx, .config, .css,.htm, .html, .js, .md, .txt, .zip
Note
Content files added to the root project folder will be copied to the root folder of the compiled help file. Files in subfolders will be copied to like-named subfolders in the compiled help file.
Image
Select this build action for images that appear in conceptual content topics. This is the default
build action for files with the following extensions: .bmp, .gif, .jpg, .jpeg, .png. The ImageId property value is used in the mediaLink and mediaLinkInline MAML elements to reference them. Changes can be made to the image
properties such as the file associated with the ID and its AlternateText without having
to visit each topic in which it is referenced.
Warning
The value of the ID assigned to an image should not be changed. If it is, you will be required to manually locate and update the old ID in all topics that reference it.
The CopyToMedia property can be used to specify whether or not the image
is copied to the .\Media folder even if not referenced in a media link. The default is
False to only copy the image if referenced. Setting it to True is useful if the image is used for other purposes
such as in an HTML content file, if used by a custom build component, or if it is only referenced in an externalLink MAML element.
Note
Unlike topics, image files will retain their name when copied to the media folder. As such, if you add two images from different locations that have the same name, one will overwrite the other when the help file is built.
This build action also causes the file to appear in the Entity References window when Images is selected in it.
CodeSnippets
Selecting this build action identifies the file as a code snippets file. These allows you to
define code samples outside of conceptual topic files. Each snippet has a unique ID that can be referenced in
multiple topics using a codeReference MAML element so that the snippets do not have to
be copied into each one. Files with a .snippets extension are automatically assigned this
build action. Multiple snippets files can exist in the project and all will be included in the conceptual
content build. This build action also causes the file to appear in the Entity References window when Code Snippets is selected in it.
Tip
When using the Sandcastle Help File Builder, the Code Block Component offers the same set of features and several others for both inline and external code snippets. In addition, it supports many other languages and can import code from working source code files which allows you to pull in examples from working projects that you can maintain and build without having to update a separate example snippets file. As such, you may prefer to use it rather than manage the code snippets in an XML file.
Tokens
A token is used as a replaceable tag within a conceptual content topic and is represented using a token element. The inner text of the element is a token name. The tokens are defined
in a separate token file. They are an easy way to represent common items that you use regularly such as a common
phrase or external link. Selecting this build action identifies the file as a token file. Files with a .tokens extension are automatically assigned this build action. Multiple token files can
exist in the project and all will be included in the conceptual content build. This build action also causes the
file to appear in the Entity References window when Tokens is selected in it.
ResourceItems
Resource items are used by Sandcastle to insert localizable or parameterized text into help topics. The resource items are defined in various files that differ based on the selected presentation style. Adding your own file to a project and selecting this build action identifies it as a resource item file and allows you to override the values used for the stock resource items defined by Sandcastle and/or the help file builder. Files with a .items extension are automatically assigned this build action. Multiple resource item files can exist in the project and all will be included in the build. If a resource item is defined in multiple files, the last definition encountered will be used.
ContentLayout
This is the default build action for content layout files (those with a .content extension). These are used to define the layout of conceptualcontent topics in the table of contents and the additional topic properties such as their title and index keywords.
Note
Without at least one content layout file, no conceptual content will appear in the compiled help file.
Multiple content layout files can appear in a project. Each has a SortOrder
property that is used to determine how their root entries are ordered within the overall table of contents. Each
content layout and site map file is sorted based on the sort order and their items are then merged into the table
of contents in that order.
SiteMap
This is the default build action for site map files (those with a .sitemap extension). These are used to define the layout of HTML and markdown based additional content topics in the table of contents and their title.
Note
Items referenced in a site map file must have a Content build action.
Unlike conceptual content, HTML and markdown based items in a project will be compiled into the
help file if they have a Content build action with or without a site map. In the
absence of a site map that references them, items will not appear in the table of contents. Files at the root
level appear at the root level of the help file. Files in subfolders will appear in like-named subfolders in the
help file.
Note that conceptual content is now the preferred method of adding non-API topics to the help file.
Multiple site map files can appear in a project. Each has a SortOrder
property that is used to determine how their root entries are ordered within the overall table of contents. Each
content layout and site map file is sorted based on the sort order and their items are then merged into the table
of contents in that order.
XamlConfiguration
Files with a .xamlcfg file extension will get a build action of XamlConfiguration by default. These files are used to pass additional configuration
information to the BuildAssembler tool's XAML Usage syntax generation component. The
settings include classes to exclude from getting XAML usage syntax, the assemblies that contain types that should
receive XAML usage syntax, and the XAML namespaces to associate with each API namespace. See the comments in the
template file for more information.
Note
These files will only be included in the build if the XamlUsage syntax
filter is enabled.