基本技术 : 记录您的代码使用 XML 注释

项目
09/27/2016

基本技术

记录您的代码使用 XML 注释

Lisa Feigenbaum

这篇文章部分基于 Visual Studio 的预发布版本。如更改，恕所有信息。

内容

XML 注释基础知识
自定义 XML 注释
生成 XML 文档文件
增强 Visual Studio 和 XML 注释
注释的优点 Else 某人的代码
.NET Framework 中的技巧
生成 Nicer 文档
XML 注释在 Visual Studio 2010

查找文档您的代码的简单而有效的方法？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 。

图 1 XML 注释在 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 ).

图 8 IntelliSense 工具提示

.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 中。

图 9 Sandcastle.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 版本中。

将您的问题和提出的意见发送至instinct@Microsoft.com.

Lisa Feigenbaum 是 Visual Basic 社区，Microsoft 项目经理。用户已 2004 Visual Basic 团队的成员。其当前的角色之前 Lisa 已为 Visual Basic 编辑器和调试器，从事功能如 IntelliSense，程序管理器编辑-和-继续和代码段。您可以在各种美国找到 Lisa和国际会议和用户组观看她频道 9 网络广播或读取其张贴内容在 VB 团队博客上 https://blogs.msdn.com/vbteam.

其他资源