This is something I wanted to share which saved me a lot of time
hoping it's not already have been fully covered being "How to Debug the SHFB Build Process"
in order to pin-point the problems with your doc sources, config, components, plug-ins etc...
This might look elementary to some, if so, you're welcome to comment.
OK, we already know that sand castle projects are Visual Studio projects
thus the build process is covered by the Microsoft MSBuild.exe executable.
This is the root of the build process thus what we're willing to debug.
If you're like me you didn't know you can debug a random .exe assembly
in Visual Studio.
What you do is that you create an empty VS project/solution. Then add an existing
project specifying MSBuild.exe path (Defined later).
From here we an specify arguments similar to the recommendation for running
the build process in post-build event in documentation. E.g.:
Arguments: /p:PARAMETERNAME=ARGUMENT;Configuration=Debug /nologo "PATHTOMYSHFBPROJECTFOLDER\MYSHFBPROJET.shfbproj"
pair is actual command-line variables that will be set
that you'll be able to handle in you SHFB project pre-build event.
By the mean of fancy SHFB configuration files, MSBuild.exe launches multiple other processes.
This includes itself (MSBuild.exe) and SHFB internal executables, e.g.: BuildAssembler.exe.
(I don't know if it's the case but I think the reason there's so many internal executables
in SHFB is because there would be no way of using DLLs inside the MSBuild project files.)
Child processes issued from MSBuild.exe are not attached to the debugger automatically.
The debugging faces a dead-end. What we can do is to attach the child MSBuild.exe processes
manually but a lot of child processes will spawn by MSBuild.exe at unpredictable moments.
So what I did is I installed a Visual Studio extension called Visual Commander
and defined a new custom C# command.
Basically it's a simple application with a background worker that auto-attaches spawning processes based on their names.
It has rough edges but it has an advantage over commercial products, it's free and I'm giving it for you now
Download the command here
. Download VSCMD then the command, then import it.
You'll easily find the string array where you an add your own processes to attach. I do feel that only MSBuild.exe
should be there since its native and only native processes spawn unattached, but I might be wrong and you might want to add
all SHFB executables in there.
Regarding managed assemblies, debugging is not very useful without symbols and especially when assemblies are built
in "Release" optimized mode. So if you want to debug SHFB internals, you need to re-build SHFB its code source in "Debug" mode.
As for symbols, SHFB solutions are already configured to generate them.
First download the SHFB source, then open the "MasterBuild.bat" batch file,
change the line IF '%BuildConfig%'=='' SET BuildConfig=Release
IF '%BuildConfig%'=='' SET BuildConfig=Debug
and execute it. Assuming you currently have SHFB installed. Take the content of the newly built SHFB binaries in
and copy them to SHFB install folder. In most case:
C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder\
Overwrite the content with the new files.
Last thing to do (optional) is to configure Visual Studio so it can download symbols directly from MS.
Click here for a turotial.
Voilà, you`re all set-up. Now use the command each time you want to debug. The debugger will break in SHFB code
automatically on thrown exceptions granted you set your debugger to break on thrown exceptions.
Click here for documentation
That's all, I hope that helps and that I'm not re-inventing the wheel.