12.3 使用XML注释

在代码中嵌入了XML注释后，可能想要生成一个包含文档的XML文件。VB会自动使用默认的输出路径和文件名来创建这个XML文件，但是C#在默认情况下关闭了这种默认行为。因此，如果希望生成文档，就必须手动打开该选项。

为确认文档输出的位置，可在Solution Explorer的右击上下文菜单中打开项目的属性页面。为此，在Solution Explorer中找到要创建文档的项目，右击与其对应的项，然后选择Properties命令。

XML文档选项位于Build区域中（如图12-2所示）。在常规生成选项的下面有一个Output区域，它包含了一个启用生成XML文档文件的复选框。选中该复选框后，就可以在旁边的文本区域中指定将生成的XML文件的文件名。

图12-2

对于VB应用程序，生成XML文档文件的选项在项目属性的Compile选项卡上。

一旦保存了这些选项，下一次构建项目时，Visual Studio就会在处理过程中添加/doc编译器选项，以生成指定的XML文档。

生成的XML文件包含一个完整的XML文档，可以对其应用XSL转换，也可以在另一个应用程序中使用XML文档对象模型处理它。所有对异常、参数、方法以及其他see also链接的引用都包含为可寻址的完整信息，包括名称空间、应用程序以及类数据。本章的后面将介绍如何使用这个XML文件，通过Sandcastle生成专业外观的文档。

IntelliSense信息

使用XML注释的另一个好处是Visual Studio可以在IntelliSense引擎中使用这些注释。只要定义了Visual Studio能理解的文档标记，就会在IntelliSense中生成信息，这样就可以在代码的任意位置访问这些信息。

有两种方式可以访问IntelliSense。如果被引用的成员位于同一项目中，或者位于同一解决方案的另一个项目中，则不需要构建或者生成XML文件就可以访问这些信息。尽管如此，即使项目位于当前应用程序解决方案之外，也可以使用IntelliSense。

要点是在构建过程生成XML文件时，该文件必须与要构建的.NET程序集同名。例如，如果编译输出的是MyApplication.exe，相关的XML文件就必须命名为MyApplicaion.xml。此外，生成的XML文件必须与已编译的程序集位于同一个文件夹中，只有这样Visual Studio才能找到它。