C#文件自動化 (轉)[@more@]

文件自動化:namespace prefix = o ns = "urn:schemas--com::office" />

  本文主要參考《ins C#》第15章的內容。

熟悉的員都知道，在java中有一種“文件註釋”。採用這種註釋之後，使用相應的命令，我們就可以得到與程式碼相關的文件說明。如今，在的世界中C#也提供了相同的功能。如果結合相應的工具，它還可以為我們產生漂亮的風格的文件。

文件自動化初步：

  在C#中文件註釋對應的符號是：///。但光使用它還是不能為我們產生程式碼文件，還必須使用特殊的標記才行。這些標記實際上是XML標記，最常用的是< summary >。例如：

///

/// A method with a string array param.

///

public void Koo(string[] ss) {}

  但是，並不是所有使用文件註釋和這些標記的地方都會為我們生成文件，它還會看這些標記是否與一些程式碼結構相關聯。例如：

///

/// 不產生這行

///

就不產生任何文件。這些程式碼結構必須是：class, struct, enum, method, property, field, indexer, delegate, 或event.

產生文件的命令

-  命令列：csc /doc: ….xml …..cs；

-  如使用VS.net，則：專案 -> 屬性 -> 屬性 -> 生成 -> 輸出 -> xml文件(在此填寫檔名和路徑)；

-  如要生成web註釋：工具 ->生成註釋 web......。

輸出文件的型別描述符

字元

描述

N

Namespace

T

型別：class, interface, struct, enum, delegate

F

Field

P

Property (包括indexers or other indexed properties)

M

Method (包括constructors和operators)

E

Event

!

Error:編譯器無法解析這個元素。

  一個輸出的檔案註釋的示例：

 

  An enum field.

 

 

  An enum type.

 

xml文件標記。

標記

描述

指示這行註釋標識為Code

指示多行註釋標識為Code

經常與連用，用來給出如何使用某些成員的例子。

指明一個成員會丟擲哪些異常，經常與cref屬性連用。

指明註釋在哪些檔案中，以及位置。

用來定義表頭，經常與連用

內部使用，如或。讓有機會給註釋文字加入其他的結構。

說明引數的屬性，編譯器會檢查引數的合法性。如果通不過，會在文件中產生!標識的警告。

類似。

標明用於成員的程式碼存取的性。

用於描述class或其它型別的描述性文字，不涉及具體細節（如果是這樣，使用

）。

描述方法或的返回值。

指定一個連結。

指定要出現在See Also部分的文字。

型別的描述性文字。它會被vs.net內建的liSense使用並顯示在對應的型別中。（即在vs.net中擊鍵“.”出現的提示）

描述屬性。

以上標記的屬性。

標記

描述

cref

可用於任何標記來提供一個程式碼元素的參考。編譯器將檢查這個程式碼元素是否存在，如不存在則在文件中用!標識。

name

用於或

標記使用的例子

1.  標記

///

/// A method with a string array param.

///

///

public void Koo(string[] ss) {}

2.  標記

///

/// A nonvoid method.

///

/// The result of the operation.

public int Noo() { return 0; }

3.  標記和cref 屬性：

///

///

/// Throws a FileIOException when...

///

///

public void Foo() {}

4.  , , 和標記

///

/// Hoo is a method in the Class1 class.

///

public void Hoo() {}

///

/// The Joo method.

/// This example shows how to use Joo:

///

///

/// public static void Main()

/// {

///  Console.WriteLine(Class1.Joo());

/// }

///

///

///

///

public static int Joo() { return 0; }

5.  標記

語法：

///

class Class1{

public static void Main() {}

}

supporting.xml

 

 

  The summary for this type.

 

 

 

 

  Another type description.

 

 

6.  標記

語法：

 

  term

  description

 

 

  term

   description

 

/// Here is an example of a bulleted list:

///

///

/// Item 1.

///

///

/// Item 2.

///

///

///

static void Main(string[] args) {}

擴充

  由於產生的文件是XML檔案，使得我們對它的處理非常方便。如可以定義一個xls來讓它產生符合我們需要的文件，如HTML、等等。對於HTML，C#的編譯器有內建的支援。我們可以使用標準的HTML標記來擴充它。但由於XML是well-formed的，因此對於一些沒有…>符號的HTML元素則必須作為一個XML有效元素使用。如
，對應為
。

總結

  本文詳細描述了C#文件自動化涉及的命令、標記和語法，並輔以例子說明。至於更詳細的資料請查閱MSDN和有關的文件。由於本人英文水平有限，不當之處請多多包涵。呵呵。