Documentation Links for System Types

Topics: User Forum
Jul 12, 2007 at 12:24 AM
I'm new to Sandcastle Help File Builder. Using Sandcastle Help File Builder version, I have successfully created my first documentation file. I have noticed one problem. The documentation links for system types are not shown in my documentation file. Instead of being shown as hypertext, references to system types are just shown in bold.

I've left the SHFB project's FrameworkVersion property, which specifies the .NET Framework version to which the documentation links for system types should point., to the default, 2.0.50727. That looks right, as I have Visual Studio 2005 and .Net 2.
Jul 12, 2007 at 2:39 AM
One of two things can cause it that I know of. The first is that you've set the SdkLinkType project property to none. It should be set to MSDN to link to the online content. The other is that this a VB.NET project. The VB.NET compiler doesn't always write the cref tags out as fully qualified like the C# compiler does. As such you must do it manually including the prefix (T: for type, M: for method, etc for example <see cref="T:System.String"/>).

Jul 12, 2007 at 10:20 PM
The assembly that is to be documented is written in C#, not VB.NET. SdkLinkType was set to MSDN, not None. HelpFileFormat was initially set to HtmlHelp1x. Setting HelpFileFormat to HtmlHelp2x made no difference when SdkLinkType was set to MSDN.

I have now also tried setting SdkLinkType to Index, in conjunction with setting HelpFileFormat to HtmlHelp2x. In this case, the references to system types are shown as hypertext. However, when a link to a system type is clicked, the following error message is shown instead of the page that the link is attempting to reference:

Sorry, no topics were found for the selected link.
Keywords = "T:System.String"
IndexMoniker =
Source URL =

(I was viewing the Help 2 file with H2 Viewer. I don't know if that would make any difference.)
Jul 13, 2007 at 2:53 AM
Create a new project, don't change any options, just add the assemblies to document and build it. Links to MSDN for system types and methods should just work. If not, I don't know what is causing the problem. If you can duplicate in a small test project like this, send it to me and I'll see if there's anything obvious that I'm missing.

Jul 15, 2007 at 11:02 PM
I've created a new project, without changing any options, to document a small test assembly. I still get the same problem. I have sent you an email message attaching the .dll and .xml files for the test assembly. If you want me to send additional files, please let me know.
Jul 16, 2007 at 11:25 PM
For the benefit of anyone interested in the answer to this problem, here's what I sorted out after the following advice by email from Eric:

The BuildAssembler utility does try to access the internet to resolve the MSDN links using the MSDN web service.
If it is blocked, that would explain why you can't get the links to work. In the past, failure to contact the web service
usually aborted the build but it looks like Microsoft may have changed that behavior and it just falls back to
non-clickable links. See the FAQ for information on how to create a BuildAssembler.exe.config file that specifies
the necessary proxy settings so that it can pass through the firewall and hopefully connect with the web service
(the "My build fails because I am behind a proxy server..." question).

The second of the three BuildAssembler.exe.config suggestions in the FAQ worked for me.