本教程展示如何使用 XML 将代码存档。
教程

C# 提供一种机制，供开发人 员使用 XML 将其代码存档。在源代码文件中，以下代码行可以 作为注释处理并放在文件中：以 /// 开始的行；在用户定义的 类型（如类、委托或接口）、某成员（如字段、事件、属性或方法） 或某命名空间声明之前的行。

示例

下面的示例提供对某个已存档的类型的基本概述。若要编译该示例 ，请键入以下命令行：

csc XMLsampl e.cs /doc:XMLsample.xml

这将创建 XML 文件 XMLsample.xml，您可以 在浏览器中或使用 TYPE 命令查看该文件。

// XMLsample.cs
// compile with: /doc:XMLsample.xml
us ing System;

/// <
sum mary>

/// Class level su mmary documentation goes here. <
/summary>

/// <
re marks>

/// Longer commen ts can be associated with a ty pe or member
/// through t he remarks tag<
/remarks>

public class SomeClass
{
/// <
summary>

/// Store for the name pro perty<
/summary>

pr ivate string myName = null;

/// <
summary>

/// The class constructor. <
/summary>

public SomeClass()
{
// TODO: Add Constructor Logi c here
}

// / <
summary>

/// Na me property <
/summary>
/// <
value>

/ // A value tag is used to desc ribe the property value<
/va lue>

public string Na me
{
get
{
if ( myName == null )
{
throw new Exception(" Name is null");

}< br>
r eturn myName;

}
}

/// <
summary&g t;

/// Description for S omeMethod.<
/summary>

/// <
param name="s">
Parameter description for s go es here<
/param>

// / <
seealso cref="String"> ;

/// You can use the cr ef attribute on any tag to ref erence a type or member
/// and the compiler will che ck that the reference exists. <
/seealso>

public void SomeMethod(string s)
{
}

/// <
summary>

/// Some oth er method. <
/summary>

/// <
returns>

/// Return results are describ ed through the returns tag.< ;
/returns>

/// <
se ealso cref="SomeMethod(string) ">

/// Notice the use of the cref attribute to refe rence a specific method <
/s eealso>

public int So meOtherMethod()
{
return 0;

}

/// <
summary>

/// The entry point for the appli cation.
/// <
/summary >

/// <
param name= "args">
A list of command l ine arguments<
/param>

public static int Main(Str ing[] args)
{
/ / TODO: Add code to start appl ication here

ret urn 0;

}
}

代码讨 论

XML 文档以 /// 开头。创建新项目时 ，向导将为您放入一些起始 /// 行。对这些注释的处理有一些 限制：

文档必须是符合标准格式的 X ML。如果 XML 不符合标准格式，将生成警告，并且文档文件 将包含一条注释，指出遇到错误。有关符合标准格式的 XML 的 更多信息，请参见 XML 词汇表。

开发人员 可自由创建自己的标记集。有一套建议的标记（请参见“其他阅读材 料”部分）。某些建议的标记具有特殊含义：

& lt;
param>
标记用于描述参数。如果使用，编译器 将验证参数是否存在，以及文档中是否描述了所有参数。如果验证失 败，则编译器发出警告。

cref 属性可以附 加到任意标记，以提供对代码元素的引用。编译器将验证该代码元素 是否存在。如果验证失败，则编译器发出警告。查找 cref 属 性中描述的类型时，编译器还考虑任何 using 语句。

<
summary>
标记由 Visu al Studio 内的“智能感知”使用，用来显示类型或成员 的其他相关信息。

示例 输出

以下是从上面的类生成的 XML 文件：< br>
<
?xml version="1.0"? >

<
doc>

< ;
assembly>

<
n ame>
xmlsample<
/name>
< br> <
/assembly>

<
members>

& lt;
member name="T:SomeClass"&g t;

<
summary& gt;

Class level summary documentation goes he re.<
/summary>

<
remarks>

Longer comments can be a ssociated with a type or membe r
through the remarks tag<
/remarks>

<
/member>

<
member name="F:SomeC lass.myName">

<
summary>

Store for the name property <
/summary>

&l t;
/member>

<
m ember name="M:SomeClass.#ctor" >

<
summar y>
The class constructor.< ;
/summary>

<
/member>

<
mem ber name="M:SomeClass.SomeMeth od(System.String)">

<
summary>

Description for SomeM ethod.<
/summary>

<
param name="s">
Parameter description for s g oes here<
/param>

<
seealso cref="T:Sy stem.String">

You can use the cref attribu te on any tag to reference a t ype or member
and the compiler will check th at the reference exists. <
/ seealso>

<
/me mber>

<
member name="M:SomeClass.SomeOtherMe thod">

<
s ummary>

Some other method. <
/summary> ;

<
returns&g t;

Return resul ts are described through the r eturns tag.<
/returns>

<
seealso cref= "M:SomeClass.SomeMethod(System .String)">

N otice the use of the cref attr ibute to reference a specific method <
/seealso>

<
/member>

<
member name="M:SomeClass .Main(System.String[])">

<
summary>
The entry point for the application.
<
/summary>

<
param name="args"& gt;
A list of command line arg uments<
/param>

<
/member>

& lt;
member name="P:SomeClass.Na me">

<
sum mary>

Name p roperty <
/summary>

<
value>

A value tag is used t o describe the property value& lt;
/value>

<
/ member>

<
/members >

<
/doc>

注意 XML 文件并不提供有关类型和成员的完整信息（ 例如，它不包含任何类型信息）。若要获得有关类型或成员的完整信 息，文档文件必须与实际类型或成员上的反射一起使用。