Alpha - question / issue

Oct 24, 2008 at 4:42 PM
First and foremost - excellent job on SHFB!

When I added my solution as a Documentation Source I received the following error:

SHFB: Error BE1002: BUILD FAILED: The imported project "C:\Microsoft.CSharp.targets" was not found. Confirm that the path in the <Import> declaration is correct, and that the file exists on disk.  C:\UEApp\ImageMoverWPF\CompositeWPF\Composite\Composite.csproj

The applicable excerpt from Composite.csproj follows:

 <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />


How do I get the conceptual data to appear?  I added a .content file but I appear to be missing something... 

Oct 24, 2008 at 7:29 PM
Regarding MSBuildToolsPath, this appears to be the way that .NET 3.5 SP1 and VS2008 SP1 reference the base build target files now.  Since SHFB is built against the .NET 2.0 MSBuild libraries, it doesn't define it.  What I can do is add code that checks to see if that variable is defined and, if not, set it to an appropriate value.  I've also got another request to allow defining other custom variables that may appear in projects.  New work item:

Regarding conceptual content, adding a .content file is just the first step.  Double-click it to open it for editing.  From there you can add topics to it that define the layout and topic properties such as the title, help attributes, and index keywords.  Adding topics to the content layout file adds them to the SHFB project automatically as well.  If you have existing MAML topics in the project, you can add them to the content layout by selecting the "existing item" option from the one of the Add toolbar buttons or context menu options.  See the Conceptual Content Properties section of the help file for details.  I haven't revised that part of the help yet so it's still written from the perspective of version but the info on how to add topics and so forth is still relevant.

Oct 24, 2008 at 8:13 PM
Edited Oct 24, 2008 at 8:16 PM
[Eric] I haven't revised that part of the help yet so it's still written from the perspective of version but the info on how to add topics and so forth is still relevant.

And very much self-explanatory;  I gleened the new location of the Conceptual topics from the SandcastleBuilder.shfbproj in the Doc folder.   Once I saw the .Content file it was downhill from there.

What threw me the curve, I figured this out after your response, was that I did not click "save".   After initial attempts to add the solution failed (also gleened from the above referenced project when I didn't find an "import solution") I simply added the executable, it sucked in the other files, hit build and walla!  I had my .CHM (note that I never hit save).   So when I added the topics and didn't get any results my first reaction was that I didn't understand the process.

The fact that your layout and design makes us long time Visual Studio developers feel right at home could be problematic as it lends itself to the "assumption" that things will automatically save upon build - particularly when adding resources didn't require a save.  

I really like the direction your taking the SHFB - so much easier (and it was already easy).

FAQ Candidates
 - Where were topics moved to?
 - What happened to Visual Studio Import?

BTW, where are you hiding the MAML preview?   I've become dependent on it for development of my project.   You make it easy to edit/manage AML files however I have a lot of projects to document and plan on creating a Web Doc project for each solution (using Expression Web or VS.aspx).  I'll then point MAMLConverter to it and your project, and then let it create the MAML for me.

Oct 24, 2008 at 9:53 PM
Good point about the save before build.  I'll see about getting it to do that with the option to prompt or just do it like Visual Studio.  The project file itself doesn't require saving as a clone of it gets used by the build process so it's always up to date.  However, supporting files like content layout files, token files, topics, etc. do need to be saved.

In case you haven't seen it, there's a "Where Did That Feature Go?" section in the Version release notes.  It describes where to find the various bits that moved around.  I'll add a general FAQ entry that takes you there too.

Preview Topic is still there.  Hit F5 in a topic window or select Window | Preview Topic to preview the topic being edited.  Actually, I ran into save issue for the Preview option.  It prompts before doing a preview if the content layout file is not saved since it needs that to ensure all the content is included in the build.

Off-topic: Like you, I didn't want to rewrite all of my HTML topics in MAML from scratch.  I created an HTML to MAML converter to help out with that.  I used it to convert the SHFB topics.  It's a simple console mode app with a basic rule file for converting the various HTML elements to equivalent MAML elements.  I plan on adding it to the Sandcastle Styles project this weekend.

Oct 25, 2008 at 2:16 PM
[EWoodruff] I created an HTML to MAML converter to help out with that.  I used it to convert the SHFB topics.

Very very nice!!!  And very much needed!  Thanks for giving me a heads up as there are so many other things I should be focusing my attention on; documentation and MAML was a serious bump in my road.   As an open source developer I know how priorities can twist and turn (often derailed by families which are a high priority in our lives) so waiting for Dave's WYSIWYG editor wasn't an option, last feedback back in June.   Your previewer was a very sweet surprise as there doesn't seem to be "anything" out there that does this.

In light of your news I'll shutdown the project, take what I have for my MAMLConverter and turn it into a blog download (later pointing to yours) and move on with front burner stuff.   I'll patiently await your converter and write MAML code during the interim (I am getting quite good in the environment you provided).

I'll be looking for that "Where Did that Feature Go?" section in the release notes (my bad).

Thanks Eric, like so many other developers I am so glad we have you to save us from the complexity of SandCastle.


Oct 26, 2008 at 12:12 AM
The HTML to MAML converter is now available at

Jan 22, 2009 at 10:50 PM
I'm getting the "SHFB: Error BE1002: BUILD FAILED: The imported project "C:\Microsoft.CSharp.targets" was not found." error in 1.8 as well.  Any ETA on a release, or is there a patch I can apply to the code and build it myself? 
Jan 23, 2009 at 1:58 AM
Edited Jan 31, 2009 at 10:45 PM
The current alpha release is built using .NET 2.0 and the MSBuild 2.0 engine.  As such, it doesn't know about MSBuildToolsPath.  The next release is built using .NET 3.5 and MSBuild 3.5 so it does handle it correctly.  In the meantime, the simplest workaround is to add the targets from the solution or project (the DLL and XML comments file) as documentation sources rather than the solution/project file itself.  At the project level, a hack that might work is to add a conditional property to the SHFB project file that defines MSBuildToolsPath if it isn't there and sets it to MSBuildBinPath.

<MSBuildToolsPath Condition=" '$(MSBuildToolsPath)' == '' ">$(MSBuildBinPath)</Configuration>

If you do that, just remember to remove it once the beta is released so that it doesn't cause any problems. 


Jan 31, 2009 at 10:47 PM
Edited Jan 31, 2009 at 10:53 PM
UPDATED 01/31/2009 - I originally stated in my previous post that a blog post suggested a new release of Sandcastle was coming soon but I see now that I misread it.  The 2 week reference was referring to the source code update for the existing version of Sandcastle.  The next release isn't actually due out until they ship VS2010 Beta 1.  Since there doesn't appear to be any date for that, it may be a while so I'll publish SHFB within a week which will use the existing release of Sandcastle.