记录您的代码使用 XML 注释---转自MSDN

记录您的代码使用XML注释

查找文档您的代码的简单而有效的方法？XML注释提供很好的解决方案。在
VisualStudio2005中最先引入VisualBasic的XML
注释。它们可以用创建该的项目文档文件，并为您自己、您的teammates或使用您的代码的其他人提供丰富的开发环境体验。
此文章中,我将向您介绍XML
注释，并介绍了如何使用它们。我将探讨的XML注释可用于自定义编码环境，并从代码中的注释中创建文档文件的方法。我还将显示您将创建用于处理
XML注释在代码中更好体验的某些将来VisualStudio功能。

XML注释基础知识
XML注释可用于对文档除了命名空间的几乎所有定义。这包括类型（类、模块、接口、结构、枚举、委托）、字段
(Dim)、属性（属性）、事件（事件）和方法（Sub、函数、声明运算符）。
XML注释是直接在源代码中的插入嵌入式。这使得更易于随着代码发展使其保持最新。要插入的XML注释，键入三个报价单标记
(")正上方定义，如下：

'''

FunctionRegKeyExists(ByValregKeyAsString)AsBoolean

DimexistsAsBoolean=False

Try

...

此外，还可以键入"的开头定义行，然后按Enter。
VisualStudio将插入要填充的XML注释的一个框架。

'''<summary>

'''

'''</summary>

'''<paramname="regKey"></praram>

'''<returns></returns>

'''<remarks></remarks>

FunctionRegKeyExists(ByValregKeyAsString)AsBoolean

DimexistsAsBoolean=False

Try

...

这篇文章的目的我使用简单的函数使用一个参数演示XML注释功能。根据定义，XML框架变化。例如，XML主干为函数包含一个返回元素，而不是为一个子框架。为方法参数标记的数量也异参数的数目。
请注意尽管VisualStudio将插入适当的XML
框架，为定义，并将提供一些警告，如果注释时获得的同步，它将不会自动更正注释为您。因此，请确保更新定义进行更改的注释。
一旦插入XML框架，可以Tab
内容wells，将您的意见。VisualStudiocolorizes完全从标记的XML
内容。如果您不需要它们，如说明元素，您还可以删除元素。
最后，您可以添加未在原始XML框架中的元素。作为您开始键入左的尖括号(<)，常用的标记将显示一个列表的
IntelliSense弹出菜单中所示图1。

图1XML
注释在IntelliSense中
可以将任何有效的XML添加到XML
注释。文章中找常用的标记列表"建议的文档注释
(VisualBasic)的XML
标记."
如果注释占用太多的空间时，您可以折叠它的摘要使用在+/-中所示在代码编辑器的左边的控件图2
.
图2折叠XML注释

自定义XML注释
在前面的示例我进行大量更改原始的XML框架。在企业环境中使用开发人员可能需要更改默认XML注释，以匹配其特定的企业指南。若要帮助这些情况下
VisualBasic提供了一种方法自定义默认XML框架。
首先，创建称为VBXMLDoc.xml包含您的默认注释模板的一个新的XML文件。在示例文件包含本文代码下载中。将
VBXMLDoc.xml保存到适当的位置根据您版本Windows和VisualStudio，如图
3所示。在每一的种情况下请路径中使用您自己的用户姓名替换<user>。

图3VBXMLDoc.xml的保存位置

VisualStudio2005	VisualStudio2008	WindowsXP	WindowsVista	路径
X		X		C:\DocumentsandSettings\<user>\ApplicationData\Microsoft\VisualStudio\8.0
X			X	C:\Users\<user>\AppData\Roaming\Microsoft\VisualStudio\8.0
	X	X		C:\DocumentsandSettings\<user>\ApplicationData\Microsoft\VisualStudio\9.0
	X		X	C:\Users\<user>\AppData\Roaming\Microsoft\VisualStudio\9.0

VisualStudio已内置在XMLskeletons获取插入的默认值但VBXMLDoc.xml则在启动时，Visual
Studio将改用XML
定义从该文件。VBXMLDoc.xml代码下载中提供的版本包含在默认标记，将否则插入VisualStudio的。要更改默认值，请找到您感兴趣的代码元素类型，并编辑文件中的
XML元素。
例如，让我们来更改函数获取插入的XML主干。图4显示默认和自定义的项的函数。模板元素的子级表示
XML注释框架中插入的XML元素。CompletionList元素的子级代表在键入函数上方的左的尖括号
(<)将显示在IntelliSense中拼写建议。
图4的XML
标记的函数
默认XML

<CodeElementtype="Function">

<Template>

<summary/>

<param/>

<returns/>

<remarks/>

</Template>

<CompletionList>

<exceptioncref=""/>

<includefile=""path=""/>

<paramname=""/>

<remarks/>

<returns/>

<summary/>

</CompletionList>

</CodeElement>

自定义的XML

<CodeElementtype="Function">

<Template>

<summary/>

<param/>

<returns/>

<author/>

</Template>

<CompletionList>

<exceptioncref=""/>

<includefile=""path=""/>

<paramname=""/>

<permissioncref=""/>

<returns/>

<summary/>

<author/>

<history/>

</CompletionList>

</CodeElement>

可以看到在图4的第二部分，我进行几个简单的自定义。首先，我将从默认的框架和
IntelliSense删除说明元素。此外，我将作者元素添加到默认的框架和IntelliSense，并我将在历史记录元素添加到IntelliSense。
此时，需要关闭并重新打开获取选取的VBXMLDoc.xml中更改的VisualStudio。重新启动之后,函数上方自动插入在
XML注释将包含而不是说明的作者元素：

'''<summary>

'''

'''</summary>

'''<paramname="regKey"></praram>

'''<returns></returns>

'''<author></author>

FunctionRegKeyExists(ByValregKeyAsString)AsBoolean

DimexistsAsBoolean=False

Try

...

虽然有可能将XML元素添加到模板，但是不可以添加XML值。因此，您可以使
IDE中的插入<author></author>默认，但不可以使得插入<author>MicrosoftCorporation</author>。

生成XML文档文件
VisualBasic编译器为您的程序集生成XML文档，在代码中定义的所有XML注释。编译器将还解决
cref，权限中,使用的符号，然后名称属性，以及中的文件引用包含元素。
生成的文件不会显示您的注释的成员层次结构。相反，它将是一个简单列表。它包含允许映射回到代码中其定义注释的每个定义的一个唯一ID字符串（请参见图
5）。在这种情况下，该字符串是M:RegLib.Helpers.RegKeyExists(System.string)。方法
M代表，RegLib.Helpers指定路径，RegKeyExists是方法名称和System.String参数类型。
图5生成XML
文档摘要

<?xmlversion="1.0"?>

<doc>

<assembly>

<name>RegLib</name>

</assembly>

<members>

...

<membername="M:RegLib.Helpers.RegKeyExists(System.String)">

<summary>Determineswhetheraspecificregistrykeyexists.</summary>

<paramname="regKey">Nameorpathoftheregistrykey.</param>

<returns>Trueiftheregistrykeyexists;otherwise,False.</returns>

<author>MicrosoftCorporation</author>

</member>

...

</members>

</doc>

您可以生成XML文档文件使用命令行编译器，或通过VisualStudio接口。如果您使用命令行编译器编译，使用选项
/doc或文档按。将生成一个XML文件，同名的和与该程序集相同的路径中。若要指定不同的文件名，可使用
/doc:file。
如果您使用VisualStudio界面，还有控制是否生成XML文档文件的设置。若要设置其，双击打开项目设计器的解决方案资源管理器中我项目。导航到编译选项卡。查找在窗口底部的"生成
XML文档文件"，并确保其选中。默认情况下此设置是。它生成XML文件使用与程序集相同的名称和路径。
我的示例是一个类的库项目，以便在程序集和XML文档文件RegLib.dll和
RegLib.xml，分别称为RegLib。在"生成输出路径"文本框中列出它们将在其中创建的路径。必须有要生成这些文件的一个显式版本。
Microsoft使用XML注释生成的所有Microsoft.NETFramework程序集的文档。
XML文档文件位于旁边DLL它们记录，并名称匹配。

增强VisualStudio和XML
注释
许多VisualStudio功能使用XML
注释提供使用成员的体验。因为VisualBasic编译器始终正在运行后台，VisualStudio可以使用
XML注释，因为它们都是编写，而不需要显式的生成。
在最流行的位置，使用XML注释的位置是IntelliSense。
XML注释摘要内容显示在工具提示中。该方法是使用，IntelliSense还显示参数内容参数帮助工具提示中（请参见图
6）。
图6参数帮助使用XML注释的工具提示
浏览对象浏览器中的成员是XML注释中多改进的经验。对象浏览器显示摘要，参数，返回，说明、typeparam和异常注释它们存在（参见图
7）时。它们可用时，类设计器、类视图和对象测试工作台还使用XML注释。
图7对象浏览器使用XML注释

注释的优点Else某人的代码
前面我还说明了如何通过将XML注释添加到其定义中自定义VisualStudio体验为函数。在被引用程序集中定义的成员，但是，不实用的方法遵循相同的过程由于您不一定具有到源的访问。幸运的是，没有可用于引用的成员在不同进程（还涉及
XML注释）！
没有一个主要区别。当前的解决方案中的成员，VisualStudio功能使用对基于源的XML注释在内存中的表示形式。在这种情况下，XML文档文件是仅仅是输出，，不甚至需要为能够使用
VisualStudio功能生成。而在另一方面，在引用的程序集的情况下XML文档文件作为输入中,
读取并且影响编码的环境中的行为。
让我们看一个示例。我将创建一个新的项目，并引用我构建了较早的(RegLib.dll)程序集。生成的
XML文档文件(RegLib.xml)必须位于该程序集的旁边，并且必须相同的名称。如果我从当前项目中访问RegKeyExists方法，它将会出现在
IntelliSense中。但是，我可以更改其外观。
我打开RegLib.xml，，更改为"确定该注册表项是否存在"的摘要的内容。此更新立即，和我访问
IntelliSense中,成员的下次我看到新文本在工具提示（请参见图8).
图8IntelliSense
工具提示

.NETFramework中的技巧
.NETFramework是从您的项目引用程序集的另一个示例。请考虑的Microsoft.VisualBasic.dll，可以此处找到的
XML文档文件：

C:\Windows\Microsoft.NET\Framework\v2.0.50727\en\Microsoft.VisualBasic.xml

打开XML文件并检查XML
注释。有一些有趣的XML元素，您会发现中。是例如Filterpriority确定成员如何显示
VisualBasicIntelliSense。它应显示在公用选项卡中的1表示值，2
表示它应将其出现在全部选项卡，并且3表示它应隐藏IntelliSense中完全。此成员filterpriority设置为
1，使其共同将显示时。您轻松地未能将filterpriority值更改为2，和保存
XML文件，因此该成员将显示在全部选项卡。
请注意，编辑任何.NETFrameworkXML文档文件之前,
它最好事先创建副本。还需要具有提升的权限的应用程序中打开文件。VisualStudio是一个不错的选择，因为它将保留文件格式。
可以使用本节中介绍的方法来影响中引用的程序集的成员，只要您可以访问的XML文档文件，或如果该项不存在可以创建一个。若要影响在当前程序集中定义的成员的
filterpriority，使用System.ComponentModel.EditorBrowsable属性。
另一个有趣的元素是PermissionSet。此元素指定何种情况下该成员是可访问。该元素的内容引用
System.Security.permissions.SecurityPermission类型。
让我们降低我们当前的权限级别，请参阅这对我们访问FileWidth有何影响。创建一个控制台或Windows应用程序。单击我的程序在
SolutionExplorer打开项目设计器中。选择安全选项卡，检查"启用ClickOnce安全设置"然后"这是完全可信的应用程序"。
到目前为止所需的权限不可用，因此FileWidth和相邻的成员成为出灰色和IntelliSense中不可访问。此
VisualBasic功能称为IntelliSense中区域。工具提示表示的权限类型必须使用该成员。
可以将PermissionSet元素添加到成员XML文档文件，并可以指定适当的权限。

生成Nicer文档
由VisualBasic编译器生成的XML
是可读，但不是最友好。很多工具创建以创建易于导航的nicer查找文档。
第一个工具称为sandcastle由Microsoft开发。安装
Sandcastle之后,
收集您制作文档的程序集、它们的依赖项和其XML文档文件。请将这些材料的所有复制到vSandcastle安装文件夹（通常为
C:\ProgramFilesFiles\Sandcastle\Examples\sandcastle)。
打开提升的命令提示符并定位到在相同的目录然后运行此命令：

build_Sandcastle.batprototype<yourassemblynamewithoutthefileextension>

目录和文件都将生成此操作。打开.chm目录，然后打开在此.chm文件。它应类似帮助图
9中。
图9Sandcastle.chm
输出
该工具提供了许多其他输出格式，而不chm.有关更多信息和Sandcastle上的进一步通知，请监视在网络日志blogs.msdn.com/sandcastle.

NDoc是另一个常用的工具，可以考虑使用，也可以编写您自己的自定义工具来在VisualBasic9中使用功能强大的
XML功能！

XML注释在VisualStudio2010
正向查找，有新的可能性，您可能与在代码中的XML注释交互的方式。VisualStudio2010编辑器重写使用
WindowsPresentationFoundation(WPF)，并允许丰富的可视化效果。编辑器更新还包括将移动到新组件系统在托管扩展Framework(MEF)，这使得更易于注册
VisualStudio加载项。图10显示了生成新的编辑器和组件模型的顶部的XML注释查看器的一个示例。
图10在VisualStudio2010的
XML注释查看器
单击按钮在右上角开关WPF控件和原始XML
之间显示。WPF
控件当然提供了更清晰的视图。它还利用WPF的功能，如渐变和圆边。WPF可以包括图像或视频，过！这将当然是一个格式区域的第三方外接程序以利用
VisualStudio2010版本中。