Visual Studio.net中的XML注釋 (1)

visual|xml Visual Studio.net中的XML注釋10/18/2001 11:1:33· · ··YESKY

　　 介紹

　　在這個實踐練習中，你將在C#源檔案中插入XML注釋，然後通過C#編譯器產生XML檔案。你可以在C#原始碼中使用XML相關的注釋標記，這些標記被用來指明哪些注釋需要輸出到XML檔案。

　　XML檔案可以作為代碼文檔。你可以在現存的檔案中加入新的注釋，或者修改現有注釋，以保持文檔和它對應代碼的一致性。為了建立一個更新的文檔記錄，你要重建XML檔案。

　　在本練習中，你將要:

　　 · 使用微軟Visual Studio.NET整合式開發環境建立和編輯一個專案檔

　　 · 建立一個XML檔案(doc.xml)

　　 · 在IDE中開啟項目和源檔案

　　 · 用MS-DOS命令編譯項目

　　 · 在XML檔案中應用XSL模板

　　 · 開啟doc.xml最終版本

　　 在IDE中建立一個新的項目

　　1．點擊Start，點擊Programs，點擊Microsoft Visual Studio.NET7.0，然後再點擊Microsoft Visual Studio .NET 7.0。IDE啟動頁面就會顯示，如圖1。


　　　　　　　　圖1 Visual Studio.NET IDE啟動頁面
　　注意：

　　當你用這種方法啟動IDE時，預設啟動頁面就會開啟。它提供了在此工作環境下的最近四個項目的連結，還提供了一些其它資源的連結。

　　你可以改變你的預設設定。點擊Tools，再點擊Options，然後選擇你喜歡的設定。

　　2．點擊File，點擊New，再點擊Project。New Project視窗就會出現，如圖2。

　　3．在Project Types面板裡點擊Visual C# Projects，在Templates面板上中點擊Empty Project。

　　4．在Name欄位中，鍵入XML Comments，然後選擇你的項目存放的位置(在本操作中我們使用預設位置)。

　　　　注意：在這個項目名中,"XML"與"Comments"中間有一個空格。

　　5．點擊OK。


　　　　　　　　　　　圖2. New Project視窗 　　 建立XMLComment.cs源檔案

　　XMLComment.cs檔案是用來建立XML文檔的源檔案。XML標籤及其相關文本在C#代碼中被注釋掉了。此源檔案在編譯時間，就通過這些XML標籤和文本產生XML文檔。

　　注意：

　　XML注釋標記是新加入C#的。在文本前面以三斜杠（///）打頭，它會告訴編譯器斜杠後面的文本是XML注釋。我們必須以三斜杠開頭以聲明這一行為XML注釋行。XML注釋必須採用XML標籤的格式，這樣才能產生XML文檔。

　　1．點擊File，再點擊Add New Item。Add New Item視窗將顯示如圖3。

　　2．在Categories面板裡點擊Local Project Items，在Templates面板中點擊Code File。

　　3．在name欄位中鍵入XMLComment.cs。

　　　注意："XMLComment.cs"中間沒有空格.


　　　　　　　　　　圖3.Add New Item視窗

　　4．點擊Open.

　　5．在頁面中敲入下面的代碼：

using System;

class XmlElement
{
///
/// Returns the attribute with the given name and
/// namespace
///
/// The name of the attribute
///
/// The namespace of the attribute, or null if
/// the attribute has no namespace
///
/// The attribute value, or null if the attribute
/// does not exist
///
public string GetAttr(string name, string ns) {
return "test";
}
}
　　6．點擊File，再點擊Save XMLComments.cs（或點擊Save表徵圖）。該檔案就被存到你的專案檔夾中。

　　7．點擊File，再點擊Exit。如果Microsoft Development視窗出現，點擊Yes儲存你的項目。

　　 在IDE中開啟項目和源檔案

　　1．點擊Start，點擊Programs，點擊Microsoft Visual Studio.NET7.0，然後再點擊Microsoft Visual Studio .NET 7.0。

　　2．點擊File，點擊Open，再點擊Project。

　　3．開啟路徑C:\Documents and Settings\Administrator\My Documents\Visual Studio Projects\XMLComments

　　4．點擊XMLComments.csproj或XMLComments.sln，然後點擊Open。

　　　注意：點擊兩個中的任何一個檔案都可以開啟項目

　　如果在主視窗中沒有開啟源檔案，在Solution Explorer視窗中雙擊XMLComments.cs.(見圖4)。源檔案就會在主視窗中開啟。保持IDE的開啟狀態，y以完成下面的步驟.


　　　　　　　　　圖4.XMLComment.cs文檔在IDE中的視圖
　　注意：System名字空間（namespaces）被聲明在在檔案頂端。所以這個名字空 間中的所有類在XmlElement類中可用。

　　XML元素"param"有兩個屬性，name和ns。我們把這些屬性值作為參數傳遞給GetAttr()。

　　 編譯

　　在本章中，你將使用兩個現存的檔案，make.bat 和doc.xsl。這些檔案必須存放在XMLComments專案檔夾中，此項目才能被正確編譯。

　　注意：doc.xsl檔案提供了類型表模板，用以在Web瀏覽器中顯示doc.xml檔案。make.bat檔案包含C#編譯選項。

　　1．點擊Start，點擊Programs，點擊Accessories，再點擊Windows Exployer。

　　2．開啟路徑C:\FieldContent\Experience VS.NET\Lab2。

　　3．高亮選中檔案doc.xsl和make.bat，點擊Edit，再點擊Copy。

　　4．開啟路徑C:\Documents and Settings\Administrator\My Documents\Visual Studio Projects\XMLComments。

　　5．點擊Edit，再點擊Paste將檔案粘貼到XMLComments檔案夾中。你將使用MS-DOS命令列來編譯這個項目。

　　6．在Windows Explorer中，開啟路徑C:\FieldContent\Experience VS.NET\Lab2。

　　7．雙擊Command Prompt。

　　8．敲入type make.bat，然後按斷行符號鍵。螢幕上會顯示make.bat file檔案的內容。

　　　注意：make.bat file檔案包含下面的參數：

　　　csc命令調用了C#編譯器

　　　/ target選項具體指明輸出檔案的格式。在這個例子裡，它是一個庫文， 即dll（XMLComment.dll）。

　　　/doc選項告訴編譯器從源檔案的文檔注釋中建立一個XML檔案(doc.xml)

　　　XMLComment.cs是需編譯的源檔案。

　　9．鍵入make，然後按斷行符號鍵。命令列提示視窗就會顯示如圖5。

　　　注意：當使用make命令編譯結束後，doc.xml XMLComment.dll檔案就被建立了。並且它們會被自動存放到XMLCommand專案檔夾中。對於C#來說，這是預設的。你不必指明儲存路徑除非你想改變它。

圖5.產生doc.xml後的DOS命令視窗

　　10．關閉命令提示.

doc.xsl的下載地址：http://msdn.microsoft.com/code/default.asp?url=/code/sample.asp?url=/msdn-files/027/001/686/msdncompositedoc.xml