The ESENT database engine (Extensible Storage Engine) is part of every version of Microsoft Windows and no set up is required. The build components use a slightly modified version of the Managed ESENT library to store the cached information in a series of ESENT databases accessed using a persistent dictionary instance. The database files are created on first use during the build based on the component configuration settings.

The Resolve Reference Links component allows you to configure the location and local cache size for the MSDN content IDs, the framework reflection data, and the project data if enabled. The Comments Index and Reflection Index components allow you to specify the location of the framework data and the project data if enabled along with the local cache size and the maximum number of uncached project data files to keep in memory during the build. In all cases, the local cache size determines how many items are cached in memory after being retrieved from the database. This gives a slight performance increase over having to read the common items repeatedly from the database. If a local cache size is set to zero, the local cache is disabled. This will save additional memory at the expense of build time. If the local cache fills up, it is flushed and will start being filled again as items are requested.

The default configurations should be sufficient for most builds. The framework data caches default to being stored in the local application data folder. The project data, if cached, is stored in the working folder so that it is rebuilt whenever the project is built to ensure that it contains current information. You can typically leave the project data caching option disabled unless the build runs out of memory while generating the topics as you will get better performance by loading the project data into memory. The cache usage is reported at the end of the build in a series of diagnostic messages. You can use this information to increase the local cache sizes if necessary if they are being flushed very often or shrink them to conserve more memory.

Each configuration dialog contains a Purge button that can be clicked to purge the current cache database files. They will be recreated on the next build.

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.

The id and groupId attributes on the data and targets elements can be used to group common sets of files so that their information is cached in the same database.

<!-- This should replace the third instance of the CopyFromIndexComponent. -->
<component id="Comments Index Data (ESENT Cache)">
  <index name="comments" value="/doc/members/member" key="@name" cache="30" localCacheSize="2500"
    frameworkCachePath="{@LocalDataFolder}Cache\CommentsIndexCache" projectCachePath="">
    <data base="C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.0"
      files="*.xml" recurse="false" duplicateWarning="false" groupId=".NETFramework_4.0.30319_F0754620" />
    <data base="C:\Program Files (x86)\Reference Assemblies\Microsoft\FSharp\2.0\Runtime\v4.0"
      files="*.xml" recurse="false" duplicateWarning="false" groupId=".NETFramework_4.0.30319_8010FBEB" />
    <data files="C:\CP\TFS01\SHFB\TestCaseProject\Doc\Help\Working\comments.xml" duplicateWarning="false"
      groupId="Project_Comments_{@UniqueID}" />
    <data files="C:\CP\TFS01\SHFB\TestCaseProject\Doc\Help\Working\TestDoc.XML" duplicateWarning="false"
      groupId="Project_Comments_{@UniqueID}" />
    <data files="C:\CP\TFS01\SHFB\TestCaseProject\Doc\Help\Working\_InheritedDocs_.xml"
      duplicateWarning="false" groupId="Project_Comments_{@UniqueID}" />
  </index>
  <copy name="comments" source="*" target="/document/comments" />
</component>

<!-- This should replace the first instance of the CopyFromIndexComponent. -->
<component id="Reflection Index Data (ESENT Cache)">
  <index name="reflection" value="/reflection/apis/api" key="@id" cache="15" localCacheSize="2500"
    frameworkCachePath="{@LocalDataFolder}Cache\ReflectionIndexCache" projectCachePath="">
    <data base="{@SHFBFolder}Data\Reflection" recurse="true" files="*.xml" duplicateWarning="false"
      groupId="ReflectionIndexCache">
      <!-- A list of namespace elements can be specified here to limit what data is loaded
      <namespace file="System.xml" />
      <namespace file="System.IO.xml" />
      etc. -->
    </data>
    <data files="reflection.xml" groupId="Project_Ref_{@UniqueID}" />
  </index>
  <copy name="reflection" source="*" target="/document/reference" />
</component>

<!-- This should replace the standard ResolveReferenceLinksComponent2 build
     component. -->
<component id="Resolve Reference Links (ESENT Cache)">
  <locale value="{@Locale}" />
  <linkTarget value="{@SdkLinkTarget}" />
  <msdnContentIdCache path="{@LocalDataFolder}Cache\MsdnContentId.cache"
    cachePath="{@LocalDataFolder}Cache\ESentMsdnContentIdCache" localCacheSize="2500" />
  <targets base="{@SHFBFolder}Data\Reflection" recurse="true" files="*.xml" type="{@SdkLinkType}"
    id="FrameworkTargets" cachePath="{@LocalDataFolder}Cache\ESentFrameworkTargetCache" localCacheSize="2500">
    <!-- A list of namespace elements can be specified here to limit what data is loaded
    <namespace file="System.xml" />
    <namespace file="System.IO.xml" />
    etc. -->
  </targets>
  <targets files="reflection.xml" type="Local" id="ProjectTargets" />
</component>

Other Resources