The Multi-Format Output Component is used to execute a set of build components to generate help topics for one or more help file formats at the same time with differing configuration options.

The following is an example configuration for the Multi-Format Output component. It should be inserted as the last component in the configuration file. All subsequent components are nested within it as child elements, one set for each possible help file format.

Example Configuration Copy imageCopy
      <!-- Multi-format output component.  This must wrap the component set
   unique to each output file format. -->
      <component type="SandcastleBuilder.Components.MultiFormatOutputComponent"
assembly="{@SHFBFolder}SandcastleBuilder.Components.dll"
id="Multi-format Output Component">
          <!-- This defines the formats to generate -->
          <build formats="{@HelpFileFormat}" />

          <!-- This defines the set of components for HTML Help 1 files -->
          <helpOutput format="HtmlHelp1">
              <!-- Resolve shared content -->
              <component type="Microsoft.Ddue.Tools.SharedContentComponent"
                  assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll">
                  <content file="{@ResourceItemsFolder}shared_content.xml" />
                  <content file="{@ResourceItemsFolder}reference_content.xml" />
                  <content file="{@ResourceItemsFolder}syntax_content.xml" />
                  <content file="{@ResourceItemsFolder}feedback_content.xml" />
                  <!-- These must be last in order to override other elements! -->
                  <content file="SharedBuilderContent.xml" />
                  <content file="PresentationStyleBuilderContent.xml" />
                  {@ResourceItemFiles}
              </component>

              <!-- Resolve conceptual links -->
              <component type="Microsoft.Ddue.Tools.ResolveConceptualLinksComponent"
                  assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll" showBrokenLinkText="true">
                  <targets base="xmlComp" type="Local" />
              </component>

              <!-- Resolve reference links -->
              <component type="Microsoft.Ddue.Tools.ResolveReferenceLinksComponent2"
    assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll"
    locale="{@Locale}" linkTarget="{@SdkLinkTarget}">
                  <msdnContentIdCache path="{@LocalDataFolder}Cache\MsdnContentId.cache" />
                  <targets base="{@SandcastlePath}Data\Reflection" recurse="true" files="*.xml"
                      type="{@HtmlSdkLinkType}" id="FrameworkTargets">
                      {@ReferenceLinkNamespaceFiles}
                  </targets>
                  <targets files="reflection.xml" type="Local" id="ProjectTargets" />
              </component>

              <!-- Save the result -->
              <component type="Microsoft.Ddue.Tools.SaveComponent"
                  assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll">
                  <save base="Output\HtmlHelp1\html" path="concat(/html/head/meta[@name='file']/@content,'.htm')"
                      indent="{@IndentHtml}" omit-xml-declaration="true" add-xhtml-namespace="false" />
              </component>
          </helpOutput>

          <!-- This defines the set of components for MS Help 2 files -->
          <helpOutput format="MSHelp2">
              <!-- Resolve shared content -->
              <component type="Microsoft.Ddue.Tools.SharedContentComponent"
                  assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll">
                  <content file="{@ResourceItemsFolder}shared_content.xml" />
                  <content file="{@ResourceItemsFolder}reference_content.xml" />
                  <content file="{@ResourceItemsFolder}syntax_content.xml" />
                  <content file="{@ResourceItemsFolder}feedback_content.xml" />
                  <!-- These must be last in order to override other elements! -->
                  <content file="SharedBuilderContent.xml" />
                  <content file="PresentationStyleBuilderContent.xml" />
                  {@ResourceItemFiles}
              </component>

              <!-- Insert additional MS Help 2 attributes -->
              <component type="Microsoft.Ddue.Tools.MSHelpAttrComponent"
    assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll" id="MS Help 2 Attributes">
                  {@HelpAttributes}
              </component>

              <!-- Resolve conceptual links -->
              <component type="Microsoft.Ddue.Tools.ResolveConceptualLinksComponent"
                  assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll" showBrokenLinkText="true">
                  <targets base="xmlComp" type="Index" />
              </component>

              <!-- Resolve reference links -->
              <component type="Microsoft.Ddue.Tools.ResolveReferenceLinksComponent2"
    assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll" locale="{@Locale}"
                  linkTarget="{@SdkLinkTarget}">
                  <msdnContentIdCache path="{@LocalDataFolder}Cache\MsdnContentId.cache" />
                  <targets base="{@SandcastlePath}Data\Reflection" recurse="true" files="*.xml"
                      type="{@MSHelp2SdkLinkType}" id="FrameworkTargets">
                      {@ReferenceLinkNamespaceFiles}
                  </targets>
                  <targets files="reflection.xml" type="Index" id="ProjectTargets" />
              </component>

              <!-- Save the result -->
              <component type="Microsoft.Ddue.Tools.SaveComponent"
                  assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll">
                  <save base="Output\MSHelp2\html" path="concat(/html/head/meta[@name='file']/@content,'.htm')"
                      indent="{@IndentHtml}" omit-xml-declaration="true" add-xhtml-namespace="false" />
              </component>
          </helpOutput>

          <!-- This defines the set of components for MS Help Viewer files -->
          <helpOutput format="MSHelpViewer">
              <!-- Resolve shared content -->
              <component type="Microsoft.Ddue.Tools.SharedContentComponent"
                  assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll">
                  <content file="{@ResourceItemsFolder}shared_content.xml" />
                  <!-- Override the paths for MS Help Viewer -->
                  <content file="{@ResourceItemsFolder}shared_content_mshc.xml" />
                  <content file="{@ResourceItemsFolder}reference_content.xml" />
                  <content file="{@ResourceItemsFolder}syntax_content.xml" />
                  <content file="{@ResourceItemsFolder}feedback_content.xml" />
                  <!-- These must be last in order to override other elements! -->
                  <content file="SharedBuilderContent.xml" />
                  <content file="PresentationStyleBuilderContent.xml" />
                  {@ResourceItemFiles}
              </component>

              <!-- Resolve conceptual links -->
              <component type="Microsoft.Ddue.Tools.ResolveConceptualLinksComponent"
                  assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll" showBrokenLinkText="true">
                  <targets base="xmlComp" type="Id" />
              </component>

              <!-- Resolve reference links -->
              <component type="Microsoft.Ddue.Tools.ResolveReferenceLinksComponent2"
    assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll"
    locale="{@Locale}" linkTarget="{@SdkLinkTarget}">
                  <msdnContentIdCache path="{@LocalDataFolder}Cache\MsdnContentId.cache" />
                  <targets base="{@SandcastlePath}Data\Reflection" recurse="true" files="*.xml"
                      type="{@MSHelpViewerSdkLinkType}" id="FrameworkTargets">
                      {@ReferenceLinkNamespaceFiles}
                  </targets>
                  <targets files="reflection.xml" type="Id" id="ProjectTargets" />
              </component>

              <!-- Add MS Help Viewer metadata -->
              <component type="Microsoft.Ddue.Tools.MSHCComponent"
    assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll">
                  <data topic-version="{@TopicVersion}" toc-file="toc.xml"
      toc-parent="{@ApiTocParentId}" toc-parent-version="{@TocParentVersion}" locale="{@Locale}" />
              </component>

              <!-- Save the result -->
              <component type="Microsoft.Ddue.Tools.SaveComponent"
                  assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll">
                  <save base="Output\MSHelpViewer\html" path="concat(/html/head/meta[@name='file']/@content,'.htm')"
                      indent="{@IndentHtml}" omit-xml-declaration="false" add-xhtml-namespace="true" />
              </component>
          </helpOutput>

          <!-- This defines the set of components for websites -->
          <helpOutput format="Website">
              <!-- Resolve shared content -->
              <component type="Microsoft.Ddue.Tools.SharedContentComponent"
                  assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll">
                  <content file="{@ResourceItemsFolder}shared_content.xml" />
                  <content file="{@ResourceItemsFolder}reference_content.xml" />
                  <content file="{@ResourceItemsFolder}syntax_content.xml" />
                  <content file="{@ResourceItemsFolder}feedback_content.xml" />
                  <!-- These must be last in order to override other elements! -->
                  <content file="SharedBuilderContent.xml" />
                  <content file="PresentationStyleBuilderContent.xml" />
                  {@ResourceItemFiles}
              </component>

              <!-- Resolve conceptual links -->
              <component type="Microsoft.Ddue.Tools.ResolveConceptualLinksComponent"
                  assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll" showBrokenLinkText="true">
                  <targets base="xmlComp" type="Local" />
              </component>

              <!-- Resolve reference links -->
              <component type="Microsoft.Ddue.Tools.ResolveReferenceLinksComponent2"
    assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll"
    locale="{@Locale}" linkTarget="{@SdkLinkTarget}">
                  <msdnContentIdCache path="{@LocalDataFolder}Cache\MsdnContentId.cache" />
                  <targets base="{@SandcastlePath}Data\Reflection" recurse="true" files="*.xml"
                      type="{@WebsiteSdkLinkType}" id="FrameworkTargets">
                      {@ReferenceLinkNamespaceFiles}
                  </targets>
                  <targets files="reflection.xml" type="Local" id="ProjectTargets" />
              </component>

              <!-- Save the result -->
              <component type="Microsoft.Ddue.Tools.SaveComponent"
                  assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll">
                  <save base="Output\Website\html" path="concat(/html/head/meta[@name='file']/@content,'.htm')"
                      indent="{@IndentHtml}" omit-xml-declaration="true" add-xhtml-namespace="false" />
              </component>
          </helpOutput>
      </component>

The example given above is taken from the Sandcastle Help File Builder's configuration template file. When used with it, the replacement tags {@SHFBFolder} and {@OutputFolder} are used to insert the help file builder's folder and the project's output folder in the file paths. These are replaced at build time with the appropriate values. If using the component in your own build scripts, replace the tags with a relative or absolute path to the component assembly and output folder respectively. Likewise, the other tags are replaced with project values. Update them with the appropriate settings for your project.

The build element specifies which help file formats to build. The formats attribute should contain a comma separated list of help file formats. For example:

 Copy imageCopy
<build formats="MSHelpViewer, Website" />

For each possible help file format, a helpOutput element should appear with a format attribute that matches one of the possible help file formats. Nested within that element are the components and their configurations specific to that build format. If a format is not specified in the build element, the components for that format are not created and will be ignored during the build.

See Also