HOW TO：使用 XML 文件功能 (C# 程式設計手冊)
更新：2007 年 11 月
下列範例提供已記錄文件的型別基本概觀。
範例
// compile with: /doc:DocFileName.xml
/// <summary>
/// Class level summary documentation goes here.</summary>
/// <remarks>
/// Longer comments can be associated with a type or member
/// through the remarks tag</remarks>
public class TestClass
{
/// <summary>
/// Store for the name property</summary>
private string _name = null;
/// <summary>
/// The class constructor. </summary>
public TestClass()
{
// TODO: Add Constructor Logic here
}
/// <summary>
/// Name property </summary>
/// <value>
/// A value tag is used to describe the property value</value>
public string Name
{
get
{
if (_name == null)
{
throw new System.Exception("Name is null");
}
return _name;
}
}
/// <summary>
/// Description for SomeMethod.</summary>
/// <param name="s"> Parameter description for s goes here</param>
/// <seealso cref="System.String">
/// You can use the cref attribute on any tag to reference a type or member
/// and the compiler will check that the reference exists. </seealso>
public void SomeMethod(string s)
{
}
/// <summary>
/// Some other method. </summary>
/// <returns>
/// Return results are described through the returns tag.</returns>
/// <seealso cref="SomeMethod(string)">
/// Notice the use of the cref attribute to reference a specific method </seealso>
public int SomeOtherMethod()
{
return 0;
}
/// <summary>
/// The entry point for the application.
/// </summary>
/// <param name="args"> A list of command line arguments</param>
static int Main(System.String[] args)
{
// TODO: Add code to start application here
return 0;
}
}
// This .xml file was generated with the previous code sample.
<?xml version="1.0"?>
<doc>
<assembly>
<name>xmlsample</name>
</assembly>
<members>
<member name="T:SomeClass">
<summary>
Class level summary documentation goes here.</summary>
<remarks>
Longer comments can be associated with a type or member
through the remarks tag</remarks>
</member>
<member name="F:SomeClass.m_Name">
<summary>
Store for the name property</summary>
</member>
<member name="M:SomeClass.#ctor">
<summary>The class constructor.</summary>
</member>
<member name="M:SomeClass.SomeMethod(System.String)">
<summary>
Description for SomeMethod.</summary>
<param name="s"> Parameter description for s goes here</param>
<seealso cref="T:System.String">
You can use the cref attribute on any tag to reference a type or member
and the compiler will check that the reference exists. </seealso>
</member>
<member name="M:SomeClass.SomeOtherMethod">
<summary>
Some other method. </summary>
<returns>
Return results are described through the returns tag.</returns>
<seealso cref="M:SomeClass.SomeMethod(System.String)">
Notice the use of the cref attribute 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"> A list of command line arguments</param>
</member>
<member name="P:SomeClass.Name">
<summary>
Name property </summary>
<value>
A value tag is used to describe the property value</value>
</member>
</members>
</doc>
編譯程式碼
若要編譯此範例，請輸入下列命令列：
csc XMLsample.cs /doc:XMLsample.xml
會產生 XML 檔案 XMLsample.xml，您可以使用瀏覽器或使用 TYPE 命令來檢視。
穩固程式設計
以 /// 起始的 XML 文件。建立新專案時，精靈會在專案中自動放置一些起始 /// 行。處理這些註解有一些限制：
文件必須依照語式正確 XML 格式。如果 XML 不是語式正確的格式，則會產生警告，而且文件檔會包含一段註解說明遇到錯誤。
開發者可以自由建立自己的標記集合。有一個建議的標記集合 (請參閱＜進一步閱讀＞章節)。某些建議的標記有特殊的意義：
<param> 標記是用來描述參數。如果使用，編譯器會驗證該參數及所有描述於文件中的參數是否存在。如果驗證失敗，編譯器會發出一個警告。
cref 屬性可以附加到任一個標記上，以提供程式碼項目的參考。編譯器會驗證此程式碼項目是否存在。如果驗證失敗，編譯器會發出一個警告。當尋找在 cref 屬性上描述的型別時，編譯器會遵循任何 using 陳述式的指示。
<summary> 標記是供 Visual Studio 內部的 IntelliSense 使用，以顯示型別或成員的額外資訊。
.gif "注意事項")
注意事項：XML 檔並不會提供型別和成員的完整資訊 (例如，其中並不會包含任何型別資訊)。如需型別或成員的完整資訊，文件檔必須配合實際型別或成員上的反應來使用。