To use these components, select the ComponentConfigurations property in the project and add the three components noted above to your project. The components contain no editable configuration options. If using the build components in your own build scripts or with other build tools, see the Example.config file included with the standalone build component download for an example of how to add the components to the configuration file.

Note

You must perform at least one build with any project to create the comments and reflection data cache files. The MSDN URL cache is cumulative so you must perform at least one build with each project to which you add it so as to ensure that all URLs for the given project are in the cache. Once built, you can find the cache files in the .\Cache folder located in the EWSoftware\Sandcastle Help File Builder folder in the Local Application Data folder. Under Vista and Windows 7, the local application data folder is usually equivalent to the value of the %LOCALAPPDATA% environment variable value. Under Windows XP, the equivalent is usually %USERPROFILE%\Local Settings\Application Data. To rebuild the cache files, simply delete them from that location.

These are some observations made by using the three components in various projects:

• The first two provide the least benefit and are fairly consistent in the amount of time saved. They benefit small projects with shorter build times the most and, to a certain extent, can be used to offset the rather lengthy initialization time of the Resolve Reference Links component. Nothing could be done to shorten its startup time unfortunately (see below).
• The cached MSDN URL component can provide a huge performance increase. This will be most evident in control libraries in which the classes are derived from Windows Forms or web controls which have a large number of inherited members thus causing a spike in the number of MSDN lookups that occur. Non-UI projects with base classes that are simpler result in fewer lookups and benefit less.
• Using the cached MSDN URL component is, after the initial build, almost equivalent to setting the *SdkLinkType property to None/Index/Id in regards to build time but adds the benefit of keeping the actual online links in place.
• That said, the larger the project the less benefit you may see. For example, if your project contains 10,000+ topics, it is already going to run pretty long and the few minutes saved by the cached URLs may end up making little difference in the end.

An attempt was made to try to cache the index information generated when the Resolve Reference Links component initializes but in that case, the information is much more complex and there is so much of it that there was a negative impact on performance. As such, it must still load the index information in the normal fashion when it starts. As noted, you can use the first two cached build components to offset that somewhat.

The examples given below are taken from the Sandcastle Help File Builder's configuration file templates. When used with it, you may specify various replacement tags such as {@SHFBFolder}, and {@LocalDataFolder} to insert special folder and project option values into the configuration at build time. If using the component in your own build scripts, replace the tags with an actual absolute or relative path or an appropriate option value. The {@ProjectLinks} option should be replaced with None, Local, or Index based on your preferred link type and help file format. The {@SdkLinkType} option should be replaced with None, Index, Id, or Msdn based on your preferred link type and help file format.

When documenting a .NET 3.0 or .NET 3.5 assembly, there are several framework comments files. You can add additional cache elements specifying the additional framework comments files. Be sure to give each cacheFile attribute a unique name.

CopyCached Reflection Index Data Example

<!-- Cached Reflection Index Data component.  This should replace
     the first instance of the CopyFromIndexComponent. -->
<component id="Cached Reflection Index Data"
  type="SandcastleBuilder.Components.CachedCopyFromIndexComponent"
  assembly="{@SHFBFolder}SandcastleBuilder.Components.dll">
    <index name="reflection" value="/reflection/apis/api"
       key="@id" cache="10">
        <cache base="{@SandcastlePath}Data\Reflection"
            recurse="true" files="*.xml"
            cacheFile="{@LocalDataFolder}Cache\Reflection.cache"/>
        <data files="reflection.xml" />
    </index>
    <copy name="reflection" source="*" target="/document/reference" />
</component>

CopyCached Framework Comments Index Data Example

<!-- Cached Framework Comments Index Data component.  This should
     replace the third instance of the CopyFromIndexComponent. -->
<component id="Cached Framework Comments Index Data"
  type="SandcastleBuilder.Components.CachedCopyFromIndexComponent"
  assembly="{@SHFBFolder}SandcastleBuilder.Components.dll">
    <index name="comments" value="/doc/members/member"
      key="@name" cache="100">
      <cache files="%SystemRoot%\Microsoft.NET\Framework\v2.0.50727\en\*.xml"
        cacheFile="{@LocalDataFolder}Cache\en_2.0.50727.cache" />
      <data files="ExtraComments.xml" />
      <data files="TestDoc.xml" />
      <data files="_InheritedDocs_.xml" />
    </index>
    <copy name="comments" source="*" target="/document/comments" />
</component>

CopyCached MSDN URL References Example

<!-- Cached MSDN URL references component.  This should replace
     the standard ResolveReferenceLinksComponent2 build component. -->
<component id="Cached MSDN URL References"
  type="SandcastleBuilder.Components.CachedResolveReferenceLinksComponent"
  assembly="{@SHFBFolder}SandcastleBuilder.Components.dll"
  locale="{@Locale}" linkTarget="{@SdkLinkTarget}">
    <cache filename="{@LocalDataFolder}Cache\MsdnUrl.cache" />
    <targets base="{@SandcastlePath}Data\Reflection" recurse="true"
        files="*.xml" type="{@SDKLinkType}" />
    <targets files="reflection.xml" type="{@ProjectLinkType}" />
</component>

Other Resources