Custom reference links to external links/other SHFB projects

Topics: Developer Forum
Jul 7, 2014 at 1:58 PM
Using this other topic ( and SHFB v1.9.7.0 I was able to adapt the source of "ResolveReferenceLinksComponent2" to create a custom component that resolves links to other SHFB project output. I essentially hijacked the "id" referecence type because I was never going to generate that type of output anyway:
//case ReferenceLinkType.Id:
//    writer.WriteStartElement("a");
//    writer.WriteAttributeString("href", ("ms-xhelp:///?Id=" + targetId).Replace("#", "%23"));
//    break;

case ReferenceLinkType.Id:
  string cleanedTargetId = targetId.Replace(".", "_").Replace(":", "_");
  string idHref = string.Format("{0}{1}.htm", targetBaseUrls[target.Container], cleanedTargetId);
  writer.WriteAttributeString("href", idHref);
  writer.WriteAttributeString("target", linkTarget);
This also needed a duplication of the "ResolveReferenceLinksComponent2" component file, adding the extra data I needed:
<helpOutput format="Website">
  <targets base="%PROGRAMFILES(x86)%\Sandcastle\Data\Reflection" recurse="true" files="*.xml" type="msdn" />
  <targets base="..\..\..\Ikvm\ReflectionData\Reflection" files="*.xml" baseUrl="http://tfsdev:82/Ikvm/" type="id" />
  <targets base="..\..\..\Technology\ReflectionData\Reflection" files="*.xml" baseUrl="http://tfsdev:82/Technology/2.10SP2/?topic=html/" type="id" />
  <targets files="reflection.xml" type="Local" />
However, the latest version of SHFB has refactored this component and the components mechanism. So, to my questions:
  1. Is this still the right way to do it?
  2. If a take a fresh copy of "ResolveReferenceLinksComponent" and apply my changes in, where is the default config for this component that I can use as a starting point? Would I still specify my data in the same way?
Thanks in advance,

Jul 7, 2014 at 3:14 PM
Your modifications to the ID handling should work as is. You'll need to modify the MEF factory class and the related export attribute to expose the component and provide a default configuration. See the SqlResolveReferenceLinksComponent for an example factory class that is similar to what you want to do. See the Creating a BuildAssembler Build Component topic for info on creating build components.

Jul 9, 2014 at 10:17 AM
Thanks for the quick reply Eric. I'll use that as the starting point.

Aug 11, 2014 at 3:02 PM

Due to the issue described in, I need to use the Naming Method of HashedMemberName or Guid in order to generate the documentation correctly. In fact, the new VS2013 presentation errors when building because of this issue when using the MemberName Naming Method - VS2005 succeeds but does not properly generate the topics.

Anyway, what this means is that in order to correctly reference one topic in one Sandcastle project from another project, I need to replicate the logic for generating the topic names for the Naming Method of HashedMemberName or Guid in my custom reference links component. I've trawled the SHFB source looking for references to the NamingMethod enum and searching for reasonable strings that I thought would get me there, but to no avail. Could you point me in the right direction please?

Thanks in advance,

Aug 11, 2014 at 3:50 PM
Example code for computing the member IDs using the different naming methods can be found in the Topic Naming subsection of the Help File Category Properties topic.

Aug 15, 2014 at 9:40 AM

I've now got all my classes documented and appearing in the ToC (even the ones that only differ in case) and referencing across SHFB projects using the GUID naming method. And all in the new VS2013 style to boot!

So thanks again for your help.