Sandcastle：.NET API文档构建器

Sandcastle 软件安装

GitHub仓库地址：Releases · EWSoftware/SHFB (github.com)

使用说明

常见报错：Errors and Warnings (ewsoftware.github.io)

演练：创建您的第一个项目

本演练将指导您创建第一个帮助文件生成器项目。

重要

本演练假定您使用的是帮助文件生成器的独立 GUI。如果你正在使用Visual Studio扩展包，过程类似，但命令位置会有所不同在某些情况下。有关 Visual Studio 扩展包的概述以及如何在其中查找与独立 GUI，请参阅 Visual Studio 集成包主题。

先决条件

在创建帮助文件生成器项目之前，请确保已安装所有必要的工具，并且已在项目中启用了 XML 注释，并且在代码中添加了一些注释。

新项目

创建一个全新的项目

选择文件 |新项目
在“另存为”对话框中，选择要在其中保存新项目的文件夹，然后选择输入其名称。单击“保存”以创建新项目。完成后，将为您打开“解决方案/项目资源管理器”窗口和“项目属性”窗口。
暂时忽略属性窗口，右键单击“文档源”节点在项目资源管理器中。在上下文菜单中，选择“添加文档源”。一个文档 source 是一个文件，例如程序集或 Visual Studio 解决方案或项目，信息将来自其中提取以生成 API 文档。对于此演示，请导航到帮助文件生成器文件夹（通常为 C：\Program Files （x86）\EWSoftware\Sandcastle Help File Builder），然后选择 SandcastleBuilder.WPF.dll 程序集。

提示

选择程序集或 XML 注释文件时，帮助文件生成器将自动为您添加合作伙伴文件（即同名程序集或程序集的 XML 注释文件对于同名注释文件）。也可以一次性选择和添加多个文件，也可以从Windows中拖动多个文件资源管理器并放在“文档源”节点上。
现在，我们将向项目添加一个引用程序集。参考文献是 作为一个或多个文档源程序集的依赖项的程序集。它们包含信息为记录的类创建继承的成员信息是必需的，但这些成员信息本身不需要 API 文档。右键单击“引用”节点，然后选择“添加文件/项目引用”。对于此演示，请导航到帮助文件生成器文件夹（通常为 C：\Program Files （x86）\EWSoftware\Sandcastle Help File Builder），然后选择 SandcastleBuilder.Utils.dll 程序集。

提示

鉴于解决方案和项目作为文档源，您可能会发现将它们添加为文档更容易源，而不是它们包含的程序集、注释和引用。使用解决方案或项目时，将从中导入这些项在构建时自动。
现在可以生成基本帮助文件了。选择文档 |为此构建项目。帮助文件构建器将打开输出窗口并开始显示来自构建过程。取决于文档源的数量、其中的类型和成员的数量，以及其他一些因素，这可能需要几分钟，或者在非常大的项目中，可能需要几个小时。

提示

所有生成警告和错误都使用代码值报告。您可以查看这些值在帮助文件的“错误和警告”部分中获取有关以下内容的信息它们的含义以及解决问题的可能解决方案。

注意

构建过程可能会消耗大量内存，如果您的系统小于 1GB，则完成构建可能需要更多时间。可能影响生成时间的另一个因素是 Html SDK 链接类型、MS 帮助查看器 SDK 链接类型和网站 SDK 链接类型项目属性设置。默认情况下，它们都设置为 MSDN，这会导致构建汇编程序工具联系交叉引用服务，用于解析指向所有 .NET Framework 类型和成员的联机内容的链接。如果你的互联网连接速度很慢，生成的构建将需要更长的时间。请参阅上述 SDK 的文档链接类型属性，以获取有关其可能值的信息。

注意

当 SDK 链接类型属性设置为 MSDN 时，生成可能会如果您位于代理服务器后面，则失败。有关解决方法，请参阅常见问题解答。
生成过程完成后，可以选择“文档 |“查看帮助文件”菜单选项以查看帮助文件。默认的“查看帮助文件”选项根据哪种类型显示帮助格式或构建的类型（帮助 1、MS 帮助查看器、降价或网站）。您还可以选择要查看的特定帮助格式如果按照“帮助文件格式”项目属性确定的方式生成了多个格式。

注意

ASP.NET 网站使用 .NET 2.0 提供的内置开发 Web 服务器启动或以后。您可以通过用户首选项更改用于它的设置。

如果使用 Visual Studio 模板创建了项目，则项目将包含内容布局文件、徽标图像和一些默认概念主题（欢迎页面和简单版本历史记录）。请参阅的欢迎主题，了解有关添加和管理概念内容的一些常规信息。有关更具体的信息，请参阅概念内容主题及其子主题关于概念内容。请参阅沙堡 MAML 指南帮助文件，了解有关以下内容的更多信息用于创建概念主题文件的 MAML 元素。