General Questions

This topic covers general questions and issues.

Why is it called Sandcastle?

From Anand Raman: When Microsoft shipped Visual Studio 2005 (code named Whidbey) Microsoft internally used a "beach theme" code base called Coronado to build and ship the conceptual and managed reference content. As a part of this beach theme, the managed reference reflection and build engine portion of the Coronado code base was called Sandcastle. Internally, Sandcastle was used by developers across teams to produce documentation for their XML comments.

How do I use Sandcastle and the help file builder?

Read through the topics in the Getting Started section in the table of contents. These will give you an overview of how to use Sandcastle, the help file builder, and how to set up your projects to generate XML comments.

I have been using version 1.7.0.0 or earlier. The latest release is a significant change. Where did option/feature X go?

Be sure to read through the version history starting at Version 1.8.0.0 (Alpha) since it contains all of the information about the change in project format and the user interface. The Where Did That Feature Go? section in that topic contains information about how to find features or equivalent functionality in the new release.

How do I document a web application or a website project?

See the Documenting Web Projects help file for details.

How can I create a link to a conceptual topic/namespace element's help topic from an external source such as application code or a page in an external website?

Set the project's NamingMethod property based on your preference and see the NamingMethod help topic for examples that show how to open specific topics based on the selected naming method from application code and how to determine the URL for a website link.

Why don't my project's pre-build and/or post-build events evaluate and run correctly?

Pre-build and post-build events were not always supported in help file builder projects. Older projects created before they were supported do not contain the necessary properties and they will be incorrectly added to the first property group if modified in the property pages.

The pre-build and post-build event properties need to be added in a new property group at the very end of the project after the help file builder target file import as shown in the following example:

 
<Import Project="$(SHFBROOT)\SandcastleHelpFileBuilder.targets" />

<PropertyGroup>
  <PreBuildEvent>ECHO "Hello from the pre-build event"</PreBuildEvent>
  <PostBuildEvent>ECHO "Hello from the post-build event"</PostBuildEvent>
  <RunPostBuildEvent>OnBuildSuccess</RunPostBuildEvent>
</PropertyGroup>

This is necessary to allow the PreBuildEvent and PostBuildEvent targets to be evaluated correctly. They are imported from Microsoft.Common.Targets. You can edit the help file builder project in a text editor and move the properties to the end of the file manually to correct the problem.

See Also

Other Resources