记录您的代码使用 XML注释
查找文档您的代码的简单而有效的方法？ XML注释提供很好的解决方案。在
Visual Studio 2005中最先引入 Visual Basic的 XML
注释。它们可以用创建该的项目文档文件，并为您自己、您的 teammates或使用您的代码的其他人提供丰富的开发环境体验。
此文章中,我将向您介绍 XML
注释，并介绍了如何使用它们。我将探讨的 XML注释可用于自定义编码环境，并从代码中的注释中创建文档文件的方法。我还将显示您将创建用于处理
XML注释在代码中更好体验的某些将来 Visual Studio功能。
XML注释基础知识
XML 注释可用于对文档除了命名空间的几乎所有定义。这包括类型（类、模块、接口、结构、枚举、委托）、字段
(Dim)、属性（属性）、事件（事件）和方法（Sub、函数、声明运算符）。
XML 注释是直接在源代码中的插入嵌入式。这使得更易于随着代码发展使其保持最新。要插入的 XML注释，键入三个报价单标记
(")正上方定义，如下：
'''
Function RegKeyExists(ByVal regKey As String) As Boolean
Dim exists As Boolean = False
Try
...
此外，还可以键入"的开头定义行，然后按 Enter。
Visual Studio 将插入要填充的 XML注释的一个框架。
''' <summary>
'''
''' </summary>
''' <param name="regKey"></praram>
''' <returns></returns>
''' <remarks></remarks>
Function RegKeyExists(ByVal regKey As String) As Boolean
Dim exists As Boolean = False
Try
...
这篇文章的目的我使用简单的函数使用一个参数演示 XML注释功能。根据定义，XML框架变化。例如，XML主干为函数包含一个返回元素，而不是为一个子框架。为方法参数标记的数量也异参数的数目。
请注意尽管 Visual Studio将插入适当的 XML
框架，为定义，并将提供一些警告，如果注释时获得的同步，它将不会自动更正注释为您。因此，请确保更新定义进行更改的注释。
一旦插入XML框架，可以 Tab
内容 wells，将您的意见。 Visual Studio colorizes完全从标记的 XML
内容。如果您不需要它们，如说明元素，您还可以删除元素。
最后，您可以添加未在原始 XML框架中的元素。作为您开始键入左的尖括号 (<)，常用的标记将显示一个列表的
IntelliSense弹出菜单中所示图 1。
图 1XML
注释在 IntelliSense中
可以将任何有效的 XML添加到 XML
注释。文章中找常用的标记列表"建议的文档注释
(Visual Basic)的 XML
标记."
如果注释占用太多的空间时，您可以折叠它的摘要使用在 +/-中所示在代码编辑器的左边的控件图 2
.
图 2折叠 XML注释
自定义 XML注释
在前面的示例我进行大量更改原始的 XML框架。在企业环境中使用开发人员可能需要更改默认 XML注释，以匹配其特定的企业指南。若要帮助这些情况下
Visual Basic提供了一种方法自定义默认 XML框架。
首先，创建称为 VBXMLDoc.xml包含您的默认注释模板的一个新的 XML文件。在示例文件包含本文代码下载中。将
VBXMLDoc.xml保存到适当的位置根据您版本 Windows和 Visual Studio，如图
3所示。在每一的种情况下请路径中使用您自己的用户姓名替换 <user>。
|
图 3 VBXMLDoc.xml的保存位置 |
|
Visual Studio 2005 |
Visual Studio 2008 |
Windows XP |
Windows Vista |
路径 |
|
X |
|
X |
|
C:\Documents and Settings\ <user> \Application Data\Microsoft\Visual Studio\8.0 |
|
X |
|
|
X |
C:\Users\<user>\AppData\Roaming\Microsoft\VisualStudio\8.0 |
|
|
X |
X |
|
C:\Documents and Settings\ <user> \Application Data\Microsoft\Visual Studio\9.0 |
|
|
X |
|
X |
C:\Users\<user>\AppData\Roaming\Microsoft\VisualStudio\9.0 |
Visual Studio 已内置在 XML skeletons获取插入的默认值但 VBXMLDoc.xml则在启动时，Visual
Studio将改用 XML
定义从该文件。 VBXMLDoc.xml代码下载中提供的版本包含在默认标记，将否则插入 Visual Studio的。要更改默认值，请找到您感兴趣的代码元素类型，并编辑文件中的
XML元素。
例如，让我们来更改函数获取插入的 XML主干。图 4显示默认和自定义的项的函数。模板元素的子级表示
XML注释框架中插入的 XML元素。 CompletionList元素的子级代表在键入函数上方的左的尖括号
(<)将显示在 IntelliSense中拼写建议。
图 4的 XML
标记的函数
默认 XML
<CodeElement type="Function">
<Template>
<summary/>
<param/>
<returns/>
<remarks/>
</Template>
<CompletionList>
<exception cref=""/>
<include file="" path=""/>
<param name=""/>
<remarks/>
<returns/>
<summary/>
</CompletionList>
</CodeElement>
自定义的 XML
<CodeElement type="Function">
<Template>
<summary/>
<param/>
<returns/>
<author/>
</Template>
<CompletionList>
<exception cref=""/>
<include file="" path=""/>
<param name=""/>
<permission cref=""/>
<returns/>
<summary/>
<author/>
<history/>
</CompletionList>
</CodeElement>
可以看到在图 4的第二部分，我进行几个简单的自定义。首先，我将从默认的框架和
IntelliSense删除说明元素。此外，我将作者元素添加到默认的框架和 IntelliSense，并我将在历史记录元素添加到 IntelliSense。
此时，需要关闭并重新打开获取选取的 VBXMLDoc.xml中更改的 Visual Studio。重新启动之后,函数上方自动插入在
XML注释将包含而不是说明的作者元素：
''' <summary>
'''
''' </summary>
''' <param name="regKey"></praram>
''' <returns></returns>
''' <author></author>
Function RegKeyExists(ByVal regKey As String) As Boolean
Dim exists As Boolean = False
Try
...
虽然有可能将 XML元素添加到模板，但是不可以添加 XML值。因此，您可以使
IDE中的插入 <author> </author>默认，但不可以使得插入 <author> Microsoft Corporation </author>。
生成 XML文档文件
Visual Basic 编译器为您的程序集生成 XML文档，在代码中定义的所有 XML注释。编译器将还解决
cref，权限中,使用的符号，然后名称属性，以及中的文件引用包含元素。
生成的文件不会显示您的注释的成员层次结构。相反，它将是一个简单列表。它包含允许映射回到代码中其定义注释的每个定义的一个唯一 ID字符串（请参见图
5）。在这种情况下，该字符串是 M:RegLib.Helpers.RegKeyExists(System.string)。方法
M 代表，RegLib.Helpers指定路径，RegKeyExists是方法名称和 System.String参数类型。
图 5生成 XML
文档摘要
<?xml version="1.0" ?>
<doc>
<assembly>
<name>RegLib</name>
</assembly>
<members>
...
<member name="M:RegLib.Helpers.RegKeyExists(System.String)">
<summary>Determines whether a specific registry key exists.</summary>
<param name="regKey">Name or path of the registry key.</param>
<returns>True if the registry key exists; otherwise, False.</returns>
<author>Microsoft Corporation</author>
</member>
...
</members>
</doc>
您可以生成 XML文档文件使用命令行编译器，或通过 Visual Studio接口。如果您使用命令行编译器编译，使用选项
/ doc或文档按。将生成一个 XML文件，同名的和与该程序集相同的路径中。若要指定不同的文件名，可使用
/doc:file。
如果您使用 Visual Studio界面，还有控制是否生成 XML文档文件的设置。若要设置其，双击打开项目设计器的解决方案资源管理器中我项目。导航到编译选项卡。查找在窗口底部的"生成
XML 文档文件"，并确保其选中。默认情况下此设置是。它生成 XML文件使用与程序集相同的名称和路径。
我的示例是一个类的库项目，以便在程序集和 XML文档文件 RegLib.dll和
RegLib.xml，分别称为 RegLib。在"生成输出路径"文本框中列出它们将在其中创建的路径。必须有要生成这些文件的一个显式版本。
Microsoft 使用 XML注释生成的所有 Microsoft.NET Framework程序集的文档。
XML文档文件位于旁边 DLL它们记录，并名称匹配。
增强 Visual Studio和 XML
注释
许多 Visual Studio功能使用 XML
注释提供使用成员的体验。因为 Visual Basic编译器始终正在运行后台，Visual Studio可以使用
XML 注释，因为它们都是编写，而不需要显式的生成。
在最流行的位置，使用 XML注释的位置是 IntelliSense。
XML注释摘要内容显示在工具提示中。该方法是使用，IntelliSense还显示参数内容参数帮助工具提示中（请参见图
6）。
图 6参数帮助使用 XML注释的工具提示
浏览对象浏览器中的成员是 XML注释中多改进的经验。对象浏览器显示摘要，参数，返回，说明、 typeparam和异常注释它们存在（参见图
7）时。它们可用时，类设计器、类视图和对象测试工作台还使用 XML注释。
图 7对象浏览器使用 XML注释
注释的优点 Else某人的代码
前面我还说明了如何通过将 XML注释添加到其定义中自定义 Visual Studio体验为函数。在被引用程序集中定义的成员，但是，不实用的方法遵循相同的过程由于您不一定具有到源的访问。幸运的是，没有可用于引用的成员在不同进程（还涉及
XML注释）！
没有一个主要区别。当前的解决方案中的成员，Visual Studio功能使用对基于源的 XML注释在内存中的表示形式。在这种情况下，XML文档文件是仅仅是输出，，不甚至需要为能够使用
Visual Studio功能生成。而在另一方面，在引用的程序集的情况下 XML文档文件作为输入中,
读取并且影响编码的环境中的行为。
让我们看一个示例。我将创建一个新的项目，并引用我构建了较早的 (RegLib.dll)程序集。生成的
XML文档文件 (RegLib.xml)必须位于该程序集的旁边，并且必须相同的名称。如果我从当前项目中访问 RegKeyExists方法，它将会出现在
IntelliSense中。但是，我可以更改其外观。
我打开 RegLib.xml，，更改为"确定该注册表项是否存在"的摘要的内容。此更新立即，和我访问
IntelliSense 中,成员的下次我看到新文本在工具提示（请参见图 8 ).
图 8IntelliSense
工具提示
.NET Framework中的技巧
.NET Framework 是从您的项目引用程序集的另一个示例。请考虑的 Microsoft.VisualBasic.dll，可以此处找到的
XML 文档文件：
C:\Windows\Microsoft.NET\Framework\v2.0.50727\en\Microsoft.VisualBasic.xml
打开 XML文件并检查 XML
注释。有一些有趣的 XML元素，您会发现中。是例如 Filterpriority确定成员如何显示
Visual Basic IntelliSense。它应显示在公用选项卡中的 1表示值，2
表示它应将其出现在全部选项卡，并且 3表示它应隐藏 IntelliSense中完全。此成员filterpriority设置为
1，使其共同将显示时。您轻松地未能将 filterpriority值更改为 2，和保存
XML文件，因此该成员将显示在全部选项卡。
请注意，编辑任何.NET Framework XML文档文件之前,
它最好事先创建副本。还需要具有提升的权限的应用程序中打开文件。 Visual Studio是一个不错的选择，因为它将保留文件格式。
可以使用本节中介绍的方法来影响中引用的程序集的成员，只要您可以访问的 XML文档文件，或如果该项不存在可以创建一个。若要影响在当前程序集中定义的成员的
filterpriority，使用 System.ComponentModel.EditorBrowsable属性。
另一个有趣的元素是 PermissionSet。此元素指定何种情况下该成员是可访问。该元素的内容引用
System.Security.permissions.SecurityPermission 类型。
让我们降低我们当前的权限级别，请参阅这对我们访问 FileWidth有何影响。创建一个控制台或 Windows应用程序。单击我的程序在
Solution Explorer打开项目设计器中。选择安全选项卡，检查"启用 ClickOnce安全设置"然后"这是完全可信的应用程序"。
到目前为止所需的权限不可用，因此 FileWidth和相邻的成员成为出灰色和 IntelliSense中不可访问。此
Visual Basic功能称为 IntelliSense中区域。工具提示表示的权限类型必须使用该成员。
可以将 PermissionSet元素添加到成员 XML文档文件，并可以指定适当的权限。
生成 Nicer文档
由 Visual Basic编译器生成的 XML
是可读，但不是最友好。很多工具创建以创建易于导航的 nicer查找文档。
第一个工具称为sandcastle由 Microsoft开发。安装
Sandcastle之后,
收集您制作文档的程序集、它们的依赖项和其 XML文档文件。请将这些材料的所有复制到 vSandcastle安装文件夹（通常为
C:\Program Files Files\Sandcastle\Examples\sandcastle)。
打开提升的命令提示符并定位到在相同的目录然后运行此命令：
build_Sandcastle.bat prototype <your assembly name without the file extension>
目录和文件都将生成此操作。打开.chm目录，然后打开在此.chm文件。它应类似帮助图
9中。
图 9Sandcastle.chm
输出
该工具提供了许多其他输出格式，而不 chm.有关更多信息和 Sandcastle上的进一步通知，请监视在网络日志blogs.msdn.com/sandcastle.
NDoc是另一个常用的工具，可以考虑使用，也可以编写您自己的自定义工具来在 Visual Basic 9中使用功能强大的
XML功能！
XML注释在 Visual Studio 2010
正向查找，有新的可能性，您可能与在代码中的 XML注释交互的方式。 Visual Studio 2010编辑器重写使用
Windows Presentation Foundation (WPF)，并允许丰富的可视化效果。编辑器更新还包括将移动到新组件系统在托管扩展 Framework (MEF)，这使得更易于注册
Visual Studio加载项。图 10显示了生成新的编辑器和组件模型的顶部的 XML注释查看器的一个示例。
图 10在 Visual Studio 2010的
XML 注释查看器
单击按钮在右上角开关 WPF控件和原始 XML
之间显示。 WPF
控件当然提供了更清晰的视图。它还利用 WPF的功能，如渐变和圆边。 WPF可以包括图像或视频，过！这将当然是一个格式区域的第三方外接程序以利用
Visual Studio 2010版本中。