逐步解說：偵錯文字範本

發行項
08/12/2011

在偵錯文字範本之前，您應該先了解範本轉換流程的兩個步驟。在個別步驟中可能會發生不同的錯誤類別。步驟如下：

文字範本轉換引擎會建立名為「產生的轉換類別」(Generated Transformation Class) 的類別。為了建立產生的轉換類別，文字範本轉換引擎必須能夠剖析文字範本。

在此步驟中，文字範本中的錯誤 (例如不正確的標記) 可能讓剖析工作受阻。報告錯誤時，會指出發生錯誤的確切文字範本行號。
引擎會編譯產生的轉換類別。

在此步驟中，程式碼錯誤可能讓產生的轉換類別無法編譯。報告錯誤時，大部分錯誤都會連同確切的文字範本行號一併列出。範本程式碼中不對稱的括弧會造成錯誤，而報告這項錯誤時會以暫存檔案名稱指出已轉換的類別。
執行編譯的轉換類別來產生輸出。

此階段的錯誤不會連同確切的行號一併列出。您可以逐步執行範本程式碼，但是必須明確啟動偵錯工具，如下一節中所述。

若要偵錯文字範本，您必須先修正文字範本中的錯誤。接著，還必須修正產生之轉換類別中的錯誤。

注意事項
當您轉換文字範本時，在以下三個來源中，任何一個來源都可能發生錯誤：文字範本、產生的轉換類別以及任何從文字範本內呼叫的指示詞。在本逐步解說中，您將會對文字範本和產生的轉換類別進行偵錯。不過，您也可以使用這些程序來偵錯自訂指示詞。

本逐步解說所述的工作包括下列各項：

偵錯不正確的文字範本標記
逐步執行範本程式碼

建立文字範本

建立 C# 主控台應用程式專案，並將文字範本加入至方案。您會在稍後的步驟中偵錯這個文字範本。

若要建立文字範本

在 Visual Studio 中，建立新的 C# 主控台應用程式專案，並命名為 DebugTemplate。
將名為 DebugTest.tt 的文字範本檔加入至 DebugTemplate 專案。
確定 DebugTest.tt 的 [自訂工具] 屬性是設定為 [TextTemplatingFileGenerator]。
編輯檔案以包含下列這一行：
```
<#@ output extension=".txt" #> 
```
儲存檔案。

系統會轉換文字範本，並產生對應的輸出檔。新的檔案會出現在 [方案總管] 中的文字範本檔底下。

偵錯不正確的文字範本標記

撰寫文字範本時常見的語法錯誤是，使用不正確的開頭和結尾標記。在此程序中，您將偵錯不正確的標記。

若要偵錯不正確的文字範本標記

將下列程式碼加入至 DebugTest.tt：

注意事項

程式碼已內含錯誤。這是為了要偵錯而特意加入這個錯誤。
```
<# for (int i = 0; i < 3; i++) { >
Hello, World!
<# } #>
```
儲存檔案。

[錯誤清單] 視窗隨即出現，並顯示以下錯誤：

在區塊中發生未預期的開始或結束標記。請確定所輸入的開始或結束標記是否正確，以及範本中有沒有任何巢狀區塊。

在此情況下，程式碼中的錯誤是不正確的結尾標記所引起。結尾標記中遺漏了 #。
按兩下 [錯誤清單] 視窗中的錯誤，跳到程式碼部分。
為修正程式碼，請將 # 加入至結尾標記。
```
<# for (int i = 0; i < 3; i++) { #>
```
儲存檔案。

系統隨即轉換文字範本，並產生對應的輸出檔。 [錯誤清單] 視窗中現在沒有錯誤了。

逐步執行範本程式碼

若要逐步執行範本程式碼，您必須將兩個項目加入至範本：

<@#template debug="true" #>
System.Diagnostics.Debugger.Launch();

在下列程序中，您將會偵錯不存在的項目索引。這個錯誤與上一個程序中的錯誤類似。不過，您此時要使用 Visual Studio 偵錯工具對它進行偵錯。

若要使用偵錯工具進行偵錯

建立資料夾 C:\nonsense，然後將名為 nonsense.xml 的空白文字檔儲存至這個資料夾。

以下列程式碼取代 DebugTest.tt 中的程式碼：

注意事項
程式碼已內含錯誤。這是為了要偵錯而特意加入這個錯誤。

<#@ output extension=".txt" #>
<#@ assembly name="System.Xml.dll" #>
<#@ import namespace="System.Xml" #>
<#
XmlDocument xDoc = new XmlDocument();
   xDoc.Load(@"C:\nonsense\nonsense.xml");
   XmlAttributeCollection attributes = xDoc.Attributes;
   if (attributes != null)
   {
      foreach (XmlAttribute attr in attributes)
      { #>
       <#=  attr.Name #>
   <# }
   }
   #>

儲存檔案。

[錯誤清單] 視窗隨即出現，並顯示下列錯誤：

正在執行轉換: System.Xml.XmlException: 遺漏根項目。
加入 template 指示詞，並將 debug 參數設為 true：
```
<#@ template debug="true" #>
```

將 System.Diagnostics.Debugger.Launch() 陳述式加入至文字範本程式碼。

程式碼看起來如下所示：

<#@ template debug="true" #>
<#@ output extension=".txt" #>
<#@ assembly name="System.Xml.dll" #>
<#@ import namespace="System.Xml" #>
<#
   XmlDocument xDoc = new XmlDocument();
   System.Diagnostics.Debugger.Launch();
   xDoc.Load(@"C:\nonsense\nonsense.xml");
   XmlAttributeCollection attributes = xDoc.Attributes;
   if (attributes != null)
   { 
      foreach (XmlAttribute attr in attributes)
      { #>
       <#=  attr.Name #>
   <# }
   }
 #>

重新執行轉換。

[Visual Studio Just-In-Time 偵錯工具] 對話方塊隨即出現。
在 [可能的偵錯工具] 清單中，按一下 [新增 Visual Studio 2010 執行個體]，然後按一下 [是]。

DebugTest.tt 隨即在 Visual Studio 的新執行個體中開啟。

逐步執行程式碼到這一行：

xDoc.Load(@"C:\nonsense\nonsense.xml");

這一行將會發生錯誤。
關閉 Visual Studio 的第二個執行個體。
1. 在 [偵錯] 功能表上，按一下 [停止偵錯]。
2. 按一下 [檔案] 功能表上的 [結束]。
3. 當您收到提示，詢問是否要儲存對方案所做的變更時，請按一下 [否]。
  
  Visual Studio 的第二個執行個體隨即關閉。
修正文字範本並移除偵錯功能。
1. 在 [方案總管] 中，按兩下 DebugTest.tt 使之在編輯器中開啟。
2. 修正不正確的檔案名稱。例如，將名稱取代為：
  
  @"C:\\Program Files\\Microsoft Visual Studio 10.0\\Xml\\SnippetsIndex.xml"
3. 移除 template 指示詞和分欄線。
  
  文字範本看起來應該如下所示：
```
<#@ output extension=".txt" #>
<#@ assembly name="System.Xml.dll" #>
<#@ import namespace="System.Xml" #>
<#
    XmlDocument xDoc = new XmlDocument();
    xDoc.Load(@"C:\Program Files\Microsoft Visual Studio 10.0\Xml\SnippetsIndex.xml");
    foreach (XmlNode node in xDoc.SelectNodes("//*"))
    {  #>
       <#= node.Name #>
   <#  }
#>
```

儲存 DebugTest.tt。確認是否沒有錯誤，以及產生的 .txt 檔案是否列出 XML 檔中的節點名稱。

請參閱

參考

使用文字範本的常見錯誤和警告

共用方式為