本文章是由機器翻譯。

table.one { table-layout:fixed; width : 900px; } table.two { table-layout:fixed;width:900px; margin-bottom: 10px; } .tdwidth{ width:100px; }

基本技術

記錄您的程式碼使用 XML 註解

Lisa Feigenbaum

本文部分根據 Visual Studio 鮮版。所有的資訊有變更。

內容

XML 註解的基本概念
自訂 XML 註解
產生 XML 文件檔案
增強 XML 註解的 Visual 的 Studio
註解，優點 Else 某人的程式碼
從.NET Framework 的技巧
產生 Nicer 文件
在 Visual Studio 2010 XML 註解

尋找文件程式碼的簡單卻有效的方式嗎？XML 註解會提供絕佳解決方案。在 Visual Studio 2005 中最先引用的 Visual Basic 的 XML 註解)。它們可以用於建立文件的專案檔，而且提供豐富的開發環境經驗，為您自己，您的團隊或其他人使用您的程式碼。

這的篇文章中，我將為您介紹 XML 註解並說明如何使用它們。我將探索在的 XML 註解可以用來自訂您的程式碼撰寫環境以及從您的程式碼中的註解中建立文件檔案的方式。我將也示範一些未來的 Visual Studio 功能，以將建立的 XML 註解，在程式碼中所使用的更好的經驗。

XML 註解的基本概念

XML 註解可以用來文件命名空間以外的幾乎所有定義。這包括類型 (類別、 模組、 介面、 結構、 列舉、 委派 (Delegate)、 欄位 (Dim)、 屬性 (屬性)、 事件 (事件) 和方法 (Sub、 函式、 將宣告運算子)。

XML 註解會以內嵌方式，原始程式碼中直接插入。這樣讓他們的最新發展的程式碼，比較容易。插入的 XML 註解，輸入三個單引號標記 (' 」) 立即上述定義如下：

'''
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...

或者，您也可以輸入 ' 」 在開頭，定義行然後按 ENTER。 Visual Studio 將會插入 XML 註解，以填入一個基本的架構。

''' <summary>
''' 
''' </summary>
''' <param name="regKey"></praram>
''' <returns></returns>
''' <remarks></remarks>
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...

這的篇文章的目的我使用簡單的函式具有一個參數來示範 XML 註解功能。 XML 的基本架構會根據定義而有所不同。 例如，XML 基本架構函式會包含在傳回的項目，而子函數的基本架構不。 方法的參數標記的數目會也根據而有所不同參數的數目。

請注意雖然 Visual Studio 將會插入適當的 XML 基本架構定義的而且如果註解時取得的同步處理，則將會提供一些警告，它將不會自動更正註解。 因此，請確定更新定義您變更註解。

之後插入 XML 基本架構，您可以透過將您的意見內容的 wells 索引標籤。 Visual Studio 以顏色標示完全從標記的 XML 內容。 如果您不需要這些，如 ＜ 備註 ＞) 項目，您也可以刪除項目。

最後，您可以將項目加入，無法在原始的 XML 基本架構。 開始鍵入左的角括弧 (<) 的一般標籤清單中將顯示的 IntelliSense 快顯功能表中所示 [圖 1 ]。

[圖 1 XML 註解在 IntelliSense 中

您可以在任何有效的 XML 中加入 XML 註解。 文件中，可以是找到的常使用的標記清單 」 建議使用 XML 標記 Documentation Comments (Visual Basic) ." 如果註解會花太多的空間，可摺疊該使用的摘要，+/-] 左邊程式碼編輯器中所示的控制項 [圖 2] .

[圖 2 摺疊 XML 註解

自訂 XML 註解

先前的範例中，我會做一些變更到原始的 XML 基本架構。 在的企業環境中工作的開發人員可能需要變更預設 XML 註解，以符合其特定的企業指導方針。 若要協助這些案例 Visual Basic 可自訂預設的 XML 基本架構。

先，建立新的 XML 檔案，以便呼叫 VBXMLDoc.xml，其中包含您的預設註解範本。 範例檔案包含在本文的程式碼下載。 您可以儲存 VBXMLDoc.xml 至適當的位置，根據您的 Windows 和 Visual Studio 版本如 [圖 3 ] 所示。 在每一種的情況下取代 在路徑中您的使用者名稱。

Visual Studio 有內建的預設值，取得插入，在 XML 骷髏但在啟動時所存在 VBXMLDoc.xml 時，Visual Studio 會使用 XML 定義從該檔案而。 VBXMLDoc.xml 下載程式碼中所提供的版本會包含，否則會由 Visual Studio 會插入預設標籤。 若要變更預設值，請尋找您感興趣的程式碼項目類型，然後編輯檔案中的 [XML 項目]。

例如，讓我們先變更 XML 基本架構函式取得插入的。 **[圖 4]**會顯示函式的預設和自訂的項目。 樣板項目的子系，表示 XML 項目將會被插入的 XML 註解的基本架構。 CompletionList 項目的子系會表示建議會出現在 IntelliSense 中，在輸入上述函式在左的角括弧 (<)。

圖 4 的 XML 標記的函式

預設值為 XML

<CodeElement type="Function">
  <Template>
    <summary/>
    <param/>
    <returns/>
    <remarks/>
  </Template>
  <CompletionList>
    <exception cref=""/>
    <include file="" path=""/>
    <param name=""/>
    <remarks/>
    <returns/>
    <summary/>
  </CompletionList>
</CodeElement>

自訂的 XML

<CodeElement type="Function">
  <Template>
    <summary/>
    <param/>
    <returns/>
    <author/>
  </Template>
  <CompletionList>
    <exception cref=""/>
    <include file="" path=""/>
    <param name=""/>
    <permission cref=""/>
    <returns/>
    <summary/>
    <author/>
    <history/>
  </CompletionList>
</CodeElement>

您可以在 [圖 4 ] 的第二個部分中看到，我可以做一些簡單的自訂。先，我移除從預設的基本架構和 IntelliSense 的 ＜ 備註 ＞ 項目。而且，作者項目新增到 「 預設的基本架構和 IntelliSense，並將記錄項目新增到 IntelliSense。

此時，您將必須關閉並重新開啟 Visual Studio 的 VBXMLDoc.xml 以取得變更。之後重新啟動，自動插入函式上的 XML 註解將會包含而非註解的作者] 項目：

''' <summary>
''' 
''' </summary>
''' <param name="regKey"></praram>
''' <returns></returns>
''' <author></author>
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...

雖然您可以將 XML 項目加入至範本，則無法將 XML 值。 因此，您可以在 IDE 的插入 <author> </author> 預設的情況下，但這不是可以讓它插入 <author> Microsoft Corporation </author>。

產生 XML 文件檔案

Visual Basic 編譯器為您的組件產生的 XML 文件，以程式碼中所定義的所有 XML 註解。 編譯器會也解決 cref，使用權限中, 使用的符號，並名稱屬性 (Attribute)，以及檔案的參考中包含的項目]。

產生的檔案不會以階層方式顯示您加上註解的成員。 而，它是一般清單。 它會包含唯一的識別碼字串，每個定義，可讓註解對應回至其定義，在程式碼中 (請參閱 [圖 5 )。 在此情況下，字串會是 M:RegLib.Helpers.RegKeyExists(System.string)。 M 代表方法 RegLib.Helpers 指定路徑，RegKeyExists 是方法名稱和 System.String) 參數的型別。

[圖 5 產生 XML 文件的摘要

<?xml version="1.0" ?>
<doc>
<assembly>
<name>RegLib</name>
</assembly>
<members>
...
<member name="M:RegLib.Helpers.RegKeyExists(System.String)">
  <summary>Determines whether a specific registry key exists.</summary>
  <param name="regKey">Name or path of the registry key.</param>
  <returns>True if the registry key exists; otherwise, False.</returns>
  <author>Microsoft Corporation</author>
</member>
...
</members>
</doc>

您可以產生 XML 文件檔案使用命令列編譯器，或透過 Visual Studio 介面。 如果您使用命令列編譯器編譯的使用 [選項 / doc 或 doc +]。 以相同的名稱和與組件相同的路徑，，就會產生的 XML 檔案。 若要指定不同的檔案名稱，使用 [/doc:file]。

如果使用 Visual Studio 介面會有的設定，來控制是否產生的 XML 文件檔。 將它設定按兩下 [我的專案在方案總管] 開啟專案設計工具] 中]。 巡覽至 [編譯] 索引標籤。 「 產生 XML 文件檔案 」 在 [的] 視窗的底部，請確定已核取。 預設此設定會為上。 它會產生 XML 檔案與組件中使用相同的名稱和路徑。

我的範例會是可以將組件和 XML 文件檔案將 RegLib.dll 和 RegLib.xml，分別稱為 RegLib，類別程式庫專案。 其建立所在的路徑會列在 [建置輸出路徑] 文字方塊中。 必須有這些檔案是產生的明確建置。

Microsoft 會使用 XML 註解，來產生文件的所有 Microsoft.NET Framework 組件。 它們所記錄 XML 文件檔案會放在 DLL 旁邊，並符合在 [名稱]。

增強 XML 註解的 Visual 的 Studio

許多 Visual Studio 功能會使用 XML 註解，以提供成員所使用的更好經驗。 因為 Visual Basic 編譯器永遠在背景執行，Visual Studio 可以使用 XML 註解，因為它們撰寫，而不需要的明確的建置。

最普遍使用 XML 註解的位置會是 IntelliSense。 XML 註解的摘要內容會出現在工具提示中。 方法是使用，IntelliSense 也會顯示參數內容中呼叫參數的 [說明] 工具提示 (請參閱 [圖 6 )。

[圖 6 參數說明使用 XML 註解的工具提示

在許多改良的體驗，XML 註解的探索物件瀏覽器中的成員。 物件瀏覽器將顯示摘要，參數，傳回，＜ 備註 ＞、 typeparam 和例外狀況的註解當它們存在 (請參閱 [圖 7 )。 類別設計工具]、 [類別] 檢視和 [物件測試工作台] 也可取得時使用 XML 註解。

[圖 7 物件瀏覽器，使用 XML 註解

註解，優點 Else 某人的程式碼

之前我會示範如何以自訂其定義中加入 XML 註解的函式 [Visual Studio 使用經驗。 在參考的組件中定義的成員，但是，並不實際遵循相同的處理序，因為您不一定有存取來源。 幸好，是您可以使用參考的成員在不同程序 (也涉及的 XML 註解) ！

這是一個主要的差異。 成員目前的方案 Visual Studio 功能運作針對根據來源的 XML 註解的記憶體中表示。 在這種情況下，XML 文件檔案的輸出完全並甚至不需要產生的 Visual Studio) 功能才能運作。 另一方面來說，在參考的組件的 XML 文件檔案做為輸入，讀取並執行會影響程式碼的環境內的行為。

讓我們來看一個範例。 我將建立新的專案，並參考我建置舊 (RegLib.dll) 的組件。 產生的 XML 文件檔案 (RegLib.xml) 會必須放在組件旁，而且必須相同的名稱。 如果我是從目前的專案存取 RegKeyExists 方法，它就會出現在 IntelliSense 中。 不過，我可以變更其外觀。

我會開啟 [RegLib.xml，，將變更摘要的內容 」 判斷登錄機碼是否 」。 更新程式會立即，發生，並在下次我存取 IntelliSense，中的成員我查看新文字的工具提示 (請參魷 \ [圖 8 ).

[圖 8 IntelliSense 的工具提示

從.NET Framework 的技巧

.NET Framework 會是您從您的專案所參考的組件的另一個範例。 請參考 Microsoft.VisualBasic.dll，可以在此找到其的 XML 文件檔案：

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

開啟 XML 檔案，然後檢查 XML 註解。 有一些有趣的 XML 項目，您可以在那裡找到。 例如，Filterpriority 會決定成員如何在 Visual Basic IntelliSense 中出現。 它應該會出現在 [一般] 索引標籤的 1 表示值，2 表示它應會出現在 [全部] 索引標籤中，，3 表示它應該會隱藏 IntelliSense 完全。 這個成員的 filterpriority 是設定為 1 中,，所以它會出現在 [一般。 輕鬆地，您可以 filterpriority 值變更為 2，並儲存 XML 檔案，因此成員會出現在 [全部] 索引標籤中。

請注意，編輯任何.NET Framework 的 XML 文件的檔案之前, 它最好事先建立複本。 您也必須在具有提高權限的應用程式中開啟檔案。 Visual Studio 會是一個很好的選項，因為它會保留檔案格式。

您可以使用本節所述的方法，以影響成員參考的組件，只要您具有其的 XML 文件檔案的存取，或如果您可以建立一個它不存在。 若要影響成員，在目前的組件中定義的 「 filterpriority，使用 [System.ComponentModel.EditorBrowsable 屬性。

另一個有趣的項目都是 PermissionSet。 這個項目會指定在哪些條件下才可以存取成員。 項目的內容參考，System.Security.permissions.SecurityPermission 的型別。

讓我們來降低我們目前的使用權限等級，並查看這對我們存取 FileWidth 的哪些效果。 建立一個主控台] 或 [Windows 應用程式。 按一下我的程式在方案總管] 開啟專案設計工具] 中。 選取 [安全設定] 索引標籤，([核取 [啟用 ClickOnce 安全性設定]，然後將 「 這個 」 部分信任的應用程式。

此時所需的權限沒有，讓 FileWidth 和相鄰的成員成為出灰色和 IntelliSense 中無法存取。 這個 Visual Basic 功能稱為 IntelliSense 的區域。 工具提示，表示哪些使用權限類型需要使用該成員。

您可以將 PermissionSet 項目加入至成員的 XML 文件檔案，並指定適當的使用權限中。

產生 Nicer 文件

Visual Basic 編譯器產生的 XML 是可讀取的但是方便無法在最使用。 已建立許多的工具建立 nicer 尋找的文件，更容易巡覽。

第一個工具會呼叫 sandcastle再加上 Microsoft 開發的。 安裝 Sandcastle 之後, 收集組件，您將會記錄 」、 「 它們的相依性和 「 其的 XML 文件檔案]。 將所有的資料複製到 vSandcastle 安裝資料夾 (通常是 C:\ Program Files Files\Sandcastle\Examples\sandcastle)。

開啟提高權限的命令提示字元中，並巡覽至在相同的目錄，然後執行此命令：

build_Sandcastle.bat prototype <your assembly name without the file extension>

目錄和檔案將會產生這項作業。開啟.chm 目錄，並開啟.chm 檔案內。它應該看起來像說明，在 [圖 9] 。

[圖 9 Sandcastle.chm 輸出

此工具提供許多其他輸出格式以外 chm.如需詳細資訊和 Sandcastle 上的宣告，請注意在部落格blogs.msdn.com/sandcastle.

NDoc是另一個常用的工具，您可以考慮使用，或者您無法在 Visual Basic 9 使用功能強大的 XML 功能，來撰寫您自己的自訂工具] ！

在 Visual Studio 2010 XML 註解

轉寄查詢有新的可能性，您可能與 XML 註解，在程式碼進行互動的方法。在 Visual Studio 2010 編輯器會重新寫入使用 Windows Presentation Foundation (WPF)，並允許豐富的視覺效果。編輯器的更新程式也會涉及遷移至新的元件系統在 Managed 擴充性 Framework (MEF)，讓它更容易註冊 Visual Studio 增益集。[圖 10 ] 顯示的建置在元件模型與新的編輯器的最上層的 XML 註解檢視器的範例。

[圖 10 在 Visual Studio 2010 的 XML 註解] 檢視器

按一下按鈕右上角) 參數的 WPF 控制項和原始的 XML 之間顯示。WPF 控制項一定會提供更清楚檢視。它也會利用 WPF 的功能，例如漸層] 和 [圓角邊緣時。WPF 能夠太包含影像或視訊 ！這當然是一個豐富的區域，要在 Visual Studio 2010 版本中利用協力廠商增益集。

您問題或意見寄至instinct@Microsoft.com.

Lisa Feigenbaum 會是的 Visual Basic 的社群的 [Microsoft 程式] 經理。她已經自 2004 Visual Basic 小組的成員。她目前的角色之前 Lisa 會是 Visual Basic 編輯器和偵錯工具，使用功能，例如 IntelliSense，程式管理員編輯-和-繼續，以及程式碼片段。您可以在各種不同的美國中找到 Lisa國際性的會議] 及 [使用者的群組，監看她的 Channel 9 網路廣播，或讀取她在 [VB 小組部落格上的張貼內容https://blogs.msdn.com/vbteam .