.net中使用Sandcastle(类似java中的jdoc)生成代码帮助文档

本文对原文进行了修正和重新编辑，原文地址：http://blog.csdn.net/yl2isoft/article/details/18454115

1.关于ndoc和Sandcastle

早期的.net开发人员可以用NDoc来生成类库的API文档，不过 NDoc不支持.net 2.0了（据说是作者知道微软要推出类似的工具停止了更新的），作者2005年已经停止开发NDoc了，网上虽然有一些在NDoc的基础上开发的支持.net 2.0的版本，但是在使用过程中偶尔会出现一些问题，随后，微软推出了一款小软件就支持这种功能，支持生成CHM格式或者Hxs格式的文档，这款软件就是Sandcastle，这个软件是公开源代码的
2.下载地址
http://sandcastle.codeplex.com/
3.使用

准备程序集和文档注释文件

Sandcastle生成帮助文档是基于代码编译后生成的程序集和文档注释文件来工作的。要想在代码编译过程中能生成文档注释文件，需要在VS中进行如下配置。

 

设置工程输出时包含XML文档文件，这样就会生成文档注释文件。

例：新建工程SandcastleExp，仅包含代码文件Student.cs，编译代码，在bin\Debug目录下的生成的SandcastleExp.dll和SandcastleExp.XML文件就是Sandcastle工具所需要的输入内容。

 使用命令行方式操作Sandcastle生成帮助文档

将步骤3生成的SandcastleExp.dll和SandcastleExp.XML文件拷贝至C:\test文件夹（也可以是其他自建的任意文件夹）,再将C:\Program Files (x86)\Sandcastle\Examples\Sandcastle（Sandcastle安装路径）下的批处理文件build_Sandcastle.bat拷贝至此文件夹。

使用cmd打开命令行窗口，进入该目录，输入命令：build_sandcastle.bat vs2005 SandcastleExp chm，回车。

成功执行后，会生成如下所示的chm文件。

 注意：第一次安装Sandcastle后需要重启电脑，否则运行build_sandcastle.bat会出错。因为安装Sandcastle 后会创建一个系统环境变量 DXROOT，不重启电脑，该环境变量不会起作用。

 

 使用图形用户界面的方式生成帮助文档

Sandcastle还提供了图形用户界面供用户操作。可执行文件为C:\Program Files (x86)\Sandcastle\Examples\Generic\SandcastleGui.exe。打开程序，并进行相关设置，界面如下。

 

点击“Build”后，在C:\Program Files (x86)\Sandcastle\Examples\test\vs2005\chm下生成chm帮助文件。

注意：必须使用管理员账户来运行程序。

在Win8环境下，需要修改C:\Program Files (x86)\Sandcastle\Examples\Generic\Generic.targets文件，具体修改内容如下：

    <When Condition="Exists('$(ProgramFiles) (x86)')">

      <PropertyGroup>

        <ToolsPath>$(ProgramFiles(x86)) </ToolsPath>

      </PropertyGroup>

</When>

将其中的“$(ProgramFiles(x86)) ”修改为“$(ProgramFiles) (x86) ”（注意：中间还有空格）否则程序无法生成chm文件。

PS：Sandcastle 支持将多个程序集的XML文档注释生成一个chm文件的功能，可以将多个程序集和对应XML文档注释分别放在两个文件夹下，然后用AddFolder功能 一次性将文件夹下的文件添加到项目中，这样就可以将多个程序集的XML注释合并生成一个CHM文档了