SHFB Apparently Skips Some Assemblies

Topics: Developer Forum, User Forum
Sep 23, 2012 at 5:02 PM
Edited Sep 23, 2012 at 9:54 PM

I've got a project that comprises of 4 DLLs. One DLL (say, A.dll) doesn't have any (non-BCL) references, the other three DLLs (say, B.dll, C.dll, D.dll) each reference A.dll. I've been used Sandcastle and SHFB for a long time for creating API docs for those four assemblies, in HTML format.

Now, after upgrading to SHFB and the current Sandcastle version,the HTML help output contains the following:

  • Namespaces and types from A.dll, except for one particular namespace in A.dll
  • B.dll

For anything else, no contents files are generated.

The table of contents of the generated website includes all namespaces and types; however it only displays those mentioned above properly (nice name + link to the appropriate docs page), while any other namespaces and types are represented by their internal identifier (e.g. N:SomeNamespace or M:One.Two.Three.Four.#ctor) and invariably link to the index page of the generated website (i.e. Index.html#).

I don't really know where to start looking for a cause for this; I have been using SHFB + Sandcastle for various projects before, and when I run my updated installation of SHFB and Sandcastle on the previous state of my project for which I've already successfully generated flawless docs before, the same problem as described above now appears.

As my project in question is open source I can provide code to reproduce the problem; however linking seems to be disabled in this forum. Let me know if I can be of any assistance finding the responsible bug(s), and please tell me if you have any clues on how I could find out where that bug is located in the first place; SHFB or Sandcastle.

Thanks in advance!

Update: I have downgraded to SHFB and everything works again; yet I'd still like to know how to work around/fix that bug in newer versions.

Sep 24, 2012 at 1:15 AM

I'm not aware of any changes that would cause a problem like that and, as with the Help 1 compiler crashing, I don't recall anyone reporting a similar issue.  I'd have to see the projects in question to see about duplicating the issue.  You can e-mail them to me if you like.  My e-mail address is in the footer of the pages in the SHFB help file and in the About box in the standalone GUI.



Sep 24, 2012 at 8:32 AM

Hello Eric,

thank you very much for your response.

The project I was trying with yesterday can be obtained from here:

I will send you a zip file where the binaries are pre-compiled, so you don't have to build them yourself.



Sep 25, 2012 at 7:23 PM

Your example was missing some reference assemblies related to gtk-sharp but after ignoring those, the help file compiled just fine.  The Help 1 output was generated and everything looks okay.  You'll need to be more specific about the problem above with regard to what isn't showing up properly as I don't see any issues in the TOC or the topics.  Regarding the help compiler, I suppose it's possible something got messed up and uninstalling and reinstalling the HTML Help Workshop may help correct it.



Sep 25, 2012 at 8:22 PM


thank you for your message.

Sorry about the Gtk# assemblies; I've gotten so used to having them around that I occasionally forget they're not part of the .NET default installation :-)

Unfortunately, I didn't take a screenshot, so I'll have to describe - always using the correct, current SHFB version as a reference [1]:

Instead of the items TwoLayeredGUI.WPF Namespace, TwoLayeredGUI.WinForms Namespace and TwoLayeredGUI.Wizard, there were three items labeled N:TwoLayeredGUI.WPF, N:TwoLayeredGUI.WinForms and N:TwoLayeredGUI.Wizard. All of their sub-items were labeled with their internal names rather than properly formatted ones, as well. Also, these particular items didn't link to any content pages, but just to Index.html#, and as a matter of fact, no content files were created for them.

All other items in the menu were formatted properly and worked fine.

As for uninstalling and reinstalling HTML Help Workshop, I'm not sure how that could change anything as HTML Help Workshop magically started working again without crashing right after I had uninstalled SHFB and reinstalled I'm going to try it again, though; to see whether the problems reappear.



Sep 25, 2012 at 10:58 PM

Hi again,

I have uninstalled SHFB, downloaded the complete bundle again and installed that. And, guess what - both described problems are back.

This time, I have taken some screenshots:

  • : The table of contents. As you can see, the three described items are not displayed correctly.
  • : Comparison between ok and erroneous subtrees. Everything in TwoLayeredGUI.Gtk is displayed correctly, while for TwoLayeredGUI.WPF, only the internal identifiers are shown.
  • : Some of the erroneous subtrees are expanded; all trees nodes are labeled with the internal identifiers. Also, the hovered tree node links to Index.html# rather than the correct description page.

I'll try the HTML Help Workshop reinstall some other time, for hopes it will fix the crash issue at least. It certainly won't (shouldn't?) affect the problem you're seeing in these screenshots, because HTML Help Workshop isn't touched during website generation.

It's silly, but the only common ground I'm seeing between the items that are displayed incorrectly is that their second namespace level stars with a 'W' ... that, or something's hitting a limit at 6 nested namespaces. It doesn't seem to be linked to the assemblies, as TwoLayeredGUI.Wizard is in the same assembly as most of the things visible on the root level, and TwoLayeredGUI.Gtk works while TwoLayeredGUI.WinForms and TwoLayeredGUI.WPF do not.

When I've got more time, I can try and compile the docs for some other project with SHFB; maybe a pattern will become more apparent then. I'm not sure when I get to doing that, though. Still grateful for any ideas on what to do to help fix this :-)


Sep 26, 2012 at 2:06 AM

I see that you are using the hierarchical TOC plug-in.  If you disable or remove it, does the problem go away?



Sep 26, 2012 at 5:36 PM

Hello Eric,

after remoing the hierarchical TOC plug-in, HTML Help Workshop still crashes.

As for the other problem; it still appears in the same way, too; the table of contents now looks like this:

i.e. the very same namespaces as before are still broken and the other namespaces seem fine.


Sep 26, 2012 at 7:35 PM

Hello again,

I have tried this on a different computer now and I could reproduce both issues (Microsoft Help Workshop crashing and some namespaces not being properly generated) there.

I'll give you an outline of the two machines:


  • Windows Vista 32 Bit
  • German
  • VS 2008 installed
  • .NET 1.0, 1.1, 2.0, 3.0, 3.5 and 4.0 are installed


  • Windows 7 64 Bit
  • German
  • no VS is installed
  • .NET 1.0, 1.1, 2.0, 3.0, 3.5 and 4.0 are installed; 2.0, 3.0, 3.5 and 4.0 with their 64 bit version

(.NET versions based on what's in <Windows>\Microsoft.NET\Framework and <Windows>\Microsoft.NET\Framework64)

The following is my path through the SHFB installer, as executed on both machines every time I installed SHFB

  • Welcome
  • .NET 4.0 found
  • (Help File Formats)
  • Help 1 compiler found
  • Help 2 compiler not found (I'm not targetting MS Help 2 and hence have no need for it)
  • Sandcastle Tools (Installed the two pre-selected option as well as the Language Packs one)
  • No style branding package copied (I have no VS, so there's nowhere to copy this from - as stated in the text, this will only affect the VS2010 presentation style, whereas I'm using the VS2003 one, so I can safely skip this step)
  • No MAML schema IntelliSense installed (I don't use VS, so I don't need this)
  • SHFB installed
  • Visual Studio Package: Unable to locate the VSIX package installer (as I don't have VS2010, this is not a surprise)
  • Completion

Please let me know if you have any ideas what else I could try to get more information about this.


Sep 28, 2012 at 3:07 PM

Since the only real difference between what you are doing and what I have done is that you are using your full project, I think I may just have to download your project and build it to see if I can duplicate the issue under the same set of circumstances project-wise.



Sep 30, 2012 at 7:34 AM

Hello Eric,

what I sent you should be the full project already. In fact, on the Q. machine (the 2nd one I tried), I used the ZIP file I sent to you.

Are you sure it has nothing to do with not having VS installed? As most .NET developers, including you (?), probably do, this might be an explanation of why hardly anyone's noticing such problems while I encounter them on several machines.


Nov 15, 2012 at 4:18 PM
Edited Nov 15, 2012 at 4:19 PM
EWoodruff wrote:

Since the only real difference between what you are doing and what I have done is that you are using your full project, I think I may just have to download your project and build it to see if I can duplicate the issue under the same set of circumstances project-wise.



Hello again,

I think the issue is caused by path length. I could reproduce both of my issues with the ZIP file I sent to you on a third machine the other day, and the issues consistently disappear if I build the project outside of my usual hierarchy, in a not very deeply nested directory instead.

I tried this after stumbling upon a posting in some forum mentioning issues with HTML Help Workshop due to an undocumented restriction in path length. I thought I should give it a try at least to resolve the hcc crash issue, but I'm surprised reducing the path length also resolves the issue with the HTML output, because that seems to mean whichever Sandcastle component produces the HTML output has a similar problem as the HTML Help Compiler.

Trying with different path lengths, the path to the doc directory from the ZIP file I sent to you (without a trailing backslash, i.e. until ...\doc) should be no more than 51 characters in length for hhc.exe to work flawlessly, and no more than 54 characters for the HTML output to be generated correctly. (Note that I'm not sure about the exact lengths that cause problems; the length of fully-qualified type names and/or of the SHFB project file or the output directly could well play a role, too. However, I'd like to ask you to try and reproduce the issue with my SHFB project based on these findings.)

So, SHFB and newer has a problem with long paths that still used to work with. If we can find out the exact problematic lengths, even if they cannot be solved (e.g. because they're buried deep within hhc.exe), it would be extremely useful if you could put a warning (or even just refuse to build?) in the output in SHFB when any of these maximum lengths is exceeded.

Another solution might be to create the temporary files directory someplace else, e.g. directly within the user's home directory, to reduce path length.

Nov 15, 2012 at 7:43 PM

I routinely build help file with paths longer than 54 characters.  SHFB's help file is built in C:\CP\TFS01\SHFB\Documentation\SandcastleBuilder\Help\Working (61 characters).  I'm not sure why that would have any particular effect since the OS max path length is 260 characters.  You will run into issues if you exceed that especially if using the Member Name naming method as they can get quite long.  Switching to GUID or Hashed Member Name as the naming option will usually resolve those problems.

The problems with the TOC are most likely caused by the help compiler too as full paths don't come into play when generating the intermediate TOC file and the TOC file passed to the help compiler doesn't contain full paths either.  Assuming the use of the Member Name naming option, I suppose it's possible the help compiler has an internal limit on filename length too but I'm sure somebody would have ran into it by now.  I can try your example again but I'm pretty sure all I did was extract it into a folder so it would already have been using your structure with one or two extra levels.

You can use the Working Files Path project property to point the working folder at an alternate location for the build to see if that helps too.