自动文档化用 VB 创建的网站项目（使用 Sandcastle）

• 下载源代码 - 1.48 KB

引言

我有一个要求，需要为我创建的一个网站编写一些文档。该网站还包含一个包含一些 Web 服务的 .asmx 页面。

我成功地使用了 Microsoft Sandcastle，首先是命令行（再也不用了），然后是 Sandcastle Help File Builder（一个很棒的工具），为我编写的控制台应用程序生成了一个专业的 .chm 文件，并决定使用相同的工具来记录我的网站。

重要 - 此内容现已过时

请注意，本文档现在大部分已被以下内容取代： http://www.codeplex.com/SandcastleStyles/Release/ProjectReleases.aspx?ReleaseId=22689。

我建议读者参考以上 URL 来使用 Sandcastle 记录他们的网站项目。但是，本文档内容仍然保留，供那些对我在该项目发布之前是如何做到这一点的感兴趣的人参考。

背景

本文档探讨了如何为网站项目创建文档，这与用 Visual Basic 编写的 Web 应用程序项目（Web application project）**不同**。

关于这个主题，网络上有一些零散的信息，但我不得不查找很多地方（包括我自己的想象），才找到了一个完整的解决方案。正因为如此，我认为写一篇关于我所做的事情的文章可能会帮助到其他也想达到类似目标的人。

抱歉，各位 C# 程序员，但不幸的是，传递给 VB 编译器的用于使这一切生效的命令行选项不适用于 C# 编译器。稍后会详细介绍。

我终于找到了一个使用 VB 而非 C# 的实际理由……

更新：我发现可能有一些自定义代码提供程序可以扩展 C# 编译器来解决这个问题，地址是 http://www.codeplex.com/SandcastleStyles/Release/ProjectReleases.aspx?ReleaseId=13440 [^]。我没有尝试使用它们。

先决条件

为了获得最终的 CHM 文件，您需要安装一些东西。请在继续之前安装它们。

0. 您**必须**知道如何在代码中创建 XML 文档。如果您不知道，请在继续之前阅读 http://msdn.microsoft.com/en-us/library/xzysab5k(VS.80).aspx 以及页面底部的“请参阅”部分。整篇文章都依赖于 XML 注释！

1. 对 Sandcastle 的工作知识。在阅读我文章的其余部分之前，对 Sandcastle 有所了解会非常有益。前往 http://www.codeplex.com/Sandcastle 熟悉该项目。
2. 安装了 Sandcastle 二进制文件。从同一个位置获取它们。
3. 对 Sandcastle Help File Builder 的工作知识，以及成功创建基于控制台应用程序的 CHM 文件。前往 http://www.codeplex.com/SHFB 阅读相关内容。我强烈建议您花一些时间为您编写的简单控制台应用程序生成一个基本的 CHM 文件。这将帮助您更好地理解本文的其余部分。
4. 安装了 Sandcastle Help File Builder。从上面的 URL 获取。
5. 如果您没有阅读上面的第 3 点，我希望您现在去阅读 :) 请尝试成功记录一个控制台应用程序，然后再继续。

记录网站时遇到的问题

在尝试记录网站项目时，有几个障碍需要克服。我读过，Web 应用程序项目（随 Visual Studio 2005 SP1 附带，并且模仿了 VS2003 中的旧有方式）是一种不同的项目类型，并且稍微容易一些。

关于 Web 应用程序项目的任何讨论都超出了本文的范围，但我会指向 http://msdn.microsoft.com/en-us/library/aa730880(VS.80).aspx 以获取更多信息和背景阅读。

问题总结如下：

• Sandcastle 要求您引用一个 DLL。在发布网站项目时，您会得到许多随机命名的 DLL 文件。这也可以接受，您可以将它们全部添加到 Sandcastle 项目中，但下次发布网站项目时，DLL 的名称会发生变化，因此您必须删除/重新添加所有文件，每次生成都要这样。
• Sandcastle 需要一个包含所有 XML 注释的已创建的 XML 文件。乍一看，似乎无法让 Visual Studio 为网站项目创建这个文件。

引入 Web Deployment Projects - 问题解决：第 1 部分

为了解决第一个问题，我们使用了“Web Deployment Projects”。这是一个微软发布的插件，用于替代发布网站。除了其他一些有用的功能外，它允许将网站项目编译成一个单一的 DLL，并且可以指定其名称。这就解决了第一个问题。

现在您需要将 Web Deployment Projects 插件安装到 Visual Studio 中，并将 Web Deployment Project 添加到您的解决方案中，以便记录您希望记录的网站。

安装完插件后（从 http://msdn.microsoft.com/en-us/asp.net/aa336619.aspx 获取），在解决方案资源管理器中右键单击您的网站项目，然后选择“添加 Web Deployment Project”。

添加了 Web Deployment Project 后，在解决方案资源管理器中右键单击它，然后转到“属性页”。查看“输出程序集”。您需要确保选中了“将所有输出合并到单个程序集中”。为您构建的 Web 项目指定一个有意义的程序集名称。在此处输入的名称请牢记。

勾选“视为库组件”复选框。您在此处已完成，可以安全地关闭属性页。现在生成 Web Deployment Project，然后查看您在添加 WDP 时指定的路径。您应该会看到一个编译后的网站，类似于发布它的效果，但这里只有一个 DLL 文件，而不是多个。该 DLL 的名称应根据您在属性页中输入的名称。

引入 VB 编译器选项 - 问题解决：第 2 部分

还记得我总结了 Sandcastle 的两个问题吗？第一个问题我们已经通过上面的 WDP 解决了。另一个问题是 Sandcastle 需要一个包含 XML 注释的已创建的 XML 文件。这就是为什么本文档仅适用于 VB 应用程序而不适用于 C# 的原因。

两个编译器都可以通过 /doc 选项来调用，该选项指定 XML 文档注释的位置。网站项目的问题在于，会编译许多程序集，然后 WDP 将它们全部合并成一个单一的程序集。然而，创建多个程序集的过程意味着在典型的网站生成过程中，XML 文档文件会被编译器覆盖很多次，您无法获得完整的文档集。

VB 有一个名为“/doc+”的选项，它为每个程序集创建一个新的文档文件——这使我们得以继续。然而，C# 编译器没有这样的选项。我能想到的 C# 用户的方法是创建一个文件系统监视器应用程序来监视文件的所有更改……但这超出了本项目范围。如果您是 VB 用户，请继续阅读。很抱歉，对于本文而言，这对 C# 来说是一个“卡壳”问题。

接下来，我们需要告诉 VB 编译器创建此文档。为此，请在您的主 Web 应用程序的 web.config 文件中创建一个 system.codedom 部分。在最后的 </configuration> 行的上方，添加以下代码：

<system.codedom>
<compilers>
<compiler language="vb" extension=".vb"
    type="Microsoft.VisualBasic.VBCodeProvider, System, Version=2.0.0.0,
    Culture=neutral, PublicKeyToken=b77a5c561934e089" 
    compilerOptions="/optionstrict+ /doc+" />
</compilers>
</system.codedom>

请注意，这也会启用 Option Strict！这对您的 VB 应用程序来说是个好习惯，但您可能会注意到添加此代码后出现**大量**编译器错误，尤其是在尝试将字符串保存到整数变量等地方时。如果您认为暂时不使用 Option Strict 更好，可以使用：

<system.codedom>
<compilers>
<compiler language="vb" extension=".vb"
    type="Microsoft.VisualBasic.VBCodeProvider, System, Version=2.0.0.0,
    Culture=neutral, PublicKeyToken=b77a5c561934e089" compilerOptions="/doc+" />
</compilers>
</system.codedom>

现在会发生的是，VB 编译器将为程序集创建 XML 文档文件。我们又近了一步……

引入 CombineXmlDocComments - 问题解决：第 3 部分

生成后包含 XML 注释的文件默认保存在 C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Temporary ASP.NET Files。从该位置找到代表您应用程序的文件夹，稍作查找，您就会找到 XML 注释文件。

您会记得我之前说过，Sandcastle Help File Builder 希望**一个** XML 文件对应**一个** DLL 文件。目前的问题是我们有**多个** XML 文件，对应于 WDP 完成其魔法并将 DLL 合并之前的每个原始编译的程序集。

解决方案？编写一些代码……

我编写了一个基于控制台的应用程序，它将查找给定路径下的最新 XML 文件，将它们连接成一个单一的 XML 文件，并将这个新的“主注释”文件保存在指定的目录中。理想的目录是 WDP 生成的 .dll 文件所在的**相同文件夹**，对吧？这样，我们就可以将 Sandcastle Help File Builder 指向 DLL，它会在同一文件夹中找到 XML，并生成漂亮的文档。

我编写的代码可以从本文顶部的链接下载。我认为注释已经说明了一切，所以我不打算详细解释它的作用。

该应用程序设计为从命令行运行，格式如下：

CombineXmlDocComments param1 param2 param3

其中

• param1

应用程序在 Temporary ASP.NET Files 文件夹中根目录的路径。应用程序会自动查找树中的 XML 文件，所以这**应该是**类似：C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Temporary ASP.NET Files\MyWebApplication，而不是：C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Temporary ASP.NET Files\MyWebApplication\a2b88f6f\1efe7d38。

“a2b88f6f\1efe7d38”部分是相当随机的，而控制台应用程序有能力并且设计为可以自行解决这个问题。

• param2

输出文件位置。这应该与 WDP 被设置为指向的位置相同，但向下到“/debug/bin”级别。

例如，如果您将 WDP 设置为将文件发布到：c:\Webs\MyWebsite_Deploy，那么您将 param2 设置为：c:\Webs\MyWebsite_Deploy\Debug\bin。

• param3

这是您希望 XML 文件拥有的名称；**仅**传递名称，**不**包括扩展名。这应该与您在 WDP 中输入的“程序集名称”**完全相同**。例如，“MyWebsite”。

几乎完成了……

我们几乎完成了。现在我们可以生成包含单个程序集的 Web 应用程序，生成其 XML 文件，并通过从命令行运行控制台应用程序将这些 XML 文件合并到一个主 XML 文件中。

您现在可以尝试使用 Sandcastle 生成帮助文件了——您应该会得到一些有意义的输出。

您可能会注意到，您输入的 .aspx.vb 文件中的注释没有出现。这是因为默认情况下它们不在命名空间中。解决方案是将所有部分类声明放在 .aspx.vb 文件内部的自己的命名空间中，例如 MyApplication.Web.Forms。然后，当您运行 Sandcastle（在重新生成 Web 项目和 WDP；然后运行控制台应用程序合并和移动 XML 文档之后）时，请务必查看“命名空间”，并确保包含“MyApplication.Web.Forms”，这样您应该就能获得所需的文档了……:-)

（注意：如果您在将部分类放入命名空间后开始遇到生成错误，请打开 .aspx 页面并查找第一行中的“Inherits”，然后包含命名空间。例如，Inherits="WebForm1" 将变为 Inherits="MyApplication.Web.Forms.WebForm1"）。

大功告成——您现在应该能够完全记录您的网站项目了！回顾一下过程：

0. 学习如何使用 XML 注释您的代码。

1. 安装 Sandcastle
2. 安装 Sandcastle Help File Builder
3. 在记录简单的控制台应用程序方面取得一些成功，以便您对 Sandcastle Help File Builder 有一些背景了解
4. 安装 Web Deployment Projects
5. 将 WDP 添加到您的解决方案并进行配置
6. 修改 Web.config 以使编译器使用 /doc+ 生成文档
7. 将您的 Web 窗体（*.aspx.vb）文件放入命名空间
8. 使用 WDP 将您的带注释的 Web 应用程序生成为单个 DLL
9. 运行控制台应用程序以合并编译器生成的 XML 注释文件，并将其保存到与 DLL 相同的位置
10. 使用 SHFB 生成帮助文件，确保包含第 6 点中使用的命名空间

整理所有内容

最后，我们可以利用 WDP 后续任务的一个鲜为人知且文档极其不足的功能。我们可以添加一个后续任务，自动执行控制台应用程序，并自动执行 SHFB 来生成 .chm 文件。这意味着记录您的网站代码将变得像在解决方案资源管理器中点击“重新生成解决方案”一样简单。

要做到这一点，在解决方案资源管理器中，右键单击 WDP 并选择“打开项目文件”。您将在底部看到一些关于后续任务的注释。在文件的底部，显然不是在注释内，添加以下内容（根据需要替换文件路径）：

<Target Name="AfterMerge">
<!-- Combine the compiler generated XML files into a single XML file, and copy this
    over to the folder with the DLLs. -->
<Exec Command='C:\temp\CombineXmlDocComments.exe
 "C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Temporary ASP.NET Files\MyWebApplication"
 "C:\Visual Studio Working Copy\MyWebApplication_deploy\Debug\bin" MyWebApplication'/>

<!-- Run the Sandcastle Help File Builder. -->
<Exec Command=
 '"C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilderConsole.exe"
  "C:\Documents and Settings\itsdbsloan\Desktop\
   Sandcastle Projects\MyWebsiteApplication.shfb"' />
</Target>

这样就完成了！现在您只需要“重新生成解决方案”，即可自动创建 CHM 文件。

对于第一个项目来说有点麻烦，但记录第二个项目应该会容易得多。

1. 添加 WDP 并配置
2. 将命名空间添加到 .aspx.vb 文件
3. 打开 WDP 的属性页，并添加一些带有不同路径的后续任务

另请参阅

Sandcastle Styles 项目：Sandcastle Styles。