用微软Sandcastle创建.NET文档

    从一开始，.NET Framework就允许C#开发者在他们的代码中使用XML形式的注释。这一特性被增加到VB.NET 2.0中。该编译器能够使用这些注释生成基本的技术文档。使用XML注释最终得到一个难以理解的大型XML文件。   

    开发者想要并希望用其它工具代替XML，建立更易于理解的文档。开源项目NDoc通过改进和简化上述过程，并提供各种帮助文件格式，满足了这一需求。遗憾的是，由于创立者很少或几乎没有得到开发社区的支持，最终该项目被终止。

    NDoc宣布终止后，微软推出它的第一版文档工具――Sandcastle。这是一个管理类库的文档编译器。它还可通过反射处理汇编源代码，并在代码中使用XML注释生成MSDN形式的文档，这种文档比难以解读的XML更易于理解。微软称它在内部使用它创建.NET Framework文档。

    Sandcastle与.NET Framework 2.0（可在线找到它与1.1版本的用法说明）和.NET Compact Framework组合使用。Sandcastle支持本地化，并提供一个基本的命令行编译器界面和一个Visual Studio插件。

    如何获取Sandcastle

    微软2007年3月的社区技术预览提供最新版的Sandcastle。你可以在Windows Server 2003或Windows XP Service Pack 2上安装和运行该工具。它需要系统上安装有.NET Framework 2.0和HTML Help Workshop。安装必要的软件后，你就可以接着安装Sandcastle工具。

    深入了解

    Sandcastle中共有三个组件：MrefBuilder、Build Assembler和XslTransform。这些工具使用编译汇编代码时生成的输出结果，包括DLL文件以及XML注释文件。

    MrefBuilder反射一个项目的汇编代码并生成一个输出文件。MrefBuilder是一个随Sandcastle安装的命令行工具。它生成的输出文件通过XslTransform命令行工具转换成一个叫做reflection.xml的文件。reflection.xml文件包含所有文档数据，但不提供显示细节。

    MrefBuilder完成工作后，立即由Build Assembler接手处理。Build Assembler可由命令行工具BuildAssembler启动。它利用由MrefBuilder生成的数据(reflection.xml)和任何代码注释（保存在独立的XML文件中），生成按逻辑分组的HTML文件。HTML Help Compiler再利用这些HTML文件生成最终结果。

    该工具并未限制你一次处理一个汇编。如果你需要处理几个汇编代码，你必须深入了解Sandcastle配置文件。它是一个包含建立帮助文件主题所需步骤的XML文件。

    输出结果

    Sandcastle生成的输出结果具有以下特点：

• 类似于MSDN布局的界面。
• 自动生成索引项、内容项目表、主题块和页面布局，提高一致性和熟悉程度。
• 自动生成语法宣称部分。
• 自动生成继承表。
• 代码彩色化。
• 提供多种风格和语言选择，终端用户可从中选择自己最喜欢的形式。

    输出结果以HTML和CSS形式显示，微软承诺将来提供更多选择。

    可选界面

    许多开发者讨厌命令行界面――他们更喜欢灵巧的GUI界面，如流行的Visual Studio IDE。同时，你还可以使用第三方工具，利用一个友好的GUI界面推动Sandcastle过程。以下是三个有效的工具：

• Sandcastle Help File Builder：它提供一个类似于NDoc的界面，允许你输入现有的NDoc项目，自动完成创建过程。
• SandcastleGUI：这是一个免费的Sandcastle GUI前端界面。
• Sandcastle CHM编译BAT脚本和配置实用工具：这是一个配置实用工具和批处理脚本，由它通过Sandcastle可建立MSDN形式的类文档CHM文件。

    帮助他人

    如果开发者处理应用程序代码，他们需要了解应用程序的工作原理，以及如何使用应用程序界面。微软Sandcastle提供为你的项目生成MSDN形式文档所需的必要工具。检查这个Sandcastle wiki了解该工具。

    你一直都对代码归档吗？在开发文档时你使用哪些工具和技巧？请在文后的讨论部分与社区分享你的观点和经历。