All three components require an existing SQL Server database in order to cache the MSDN content IDs, the framework data, and the project data if enabled. You must specify the SQL Server connection string in each component's configuration dialog by clicking the Setup button. The default connection string assumes the use of a LocalDB instance of SQL Server. Full versions and Express versions are also supported. Adjust the connection string as necessary.

The set up dialog contains an option to execute a script that will create the database and all of the necessary tables. This script only needs to be executed once the very first time you add one of the components to a project file. Adjust the location of the database files if necessary. It is assumed you have the necessary permissions to create databases and tables on the server defined in the connection string. If not, you may need your database administrator to create and initialize the database.

The Resolve Reference Links component allows you to configure the 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 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 project data, if cached, is purged and reloaded 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 related cache database tables. They will be filled with data again 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 group within the table data.

<!-- This should replace the third instance of the CopyFromIndexComponent. -->
<component id="Comments Index Data (SQL Cache)">
  <index name="comments" value="/doc/members/member" key="@name" cache="30" localCacheSize="2500"
    cacheProject="false" connectionString="Data Source=(localdb)\v11.0;Initial Catalog=Sandcastle">
    <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 (SQL Cache)">
  <index name="reflection" value="/reflection/apis/api" key="@id" cache="15" localCacheSize="2500"
    cacheProject="false" connectionString="Data Source=(localdb)\v11.0;Initial Catalog=Sandcastle">
    <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 (SQL Cache)">
  <locale value="{@Locale}" />
  <linkTarget value="{@SdkLinkTarget}" />
  <sqlCache connectionString="Data Source=(localdb)\v11.0;Initial Catalog=Sandcastle"
    msdnLocalCacheSize="2500" frameworkLocalCacheSize="2500"
    projectLocalCacheSize="2500" cacheProject="false" />
  <msdnContentIdCache path="{@LocalDataFolder}Cache\MsdnContentId.cache" />
  <targets base="{@SHFBFolder}Data\Reflection" recurse="true" files="*.xml" type="{@SdkLinkType}"
    groupId="FrameworkTargets">
    <!-- 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" groupId="Project_{@UniqueID}" />
</component>

Other Resources