偵錯 T4 文字範本

您可以在文字範本中設定中斷點。 若要偵錯設計階段文字範本，請儲存文字範本檔案，然後在 [方案總管] 中檔案的捷徑功能表上選擇 [偵錯 T4 範本]。 若要偵錯執行階段文字範本，只需偵錯其所屬的應用程式。

若要偵錯文字範本，您應該了解範本轉換程序的步驟。 每個步驟中可能會發生不同類型的錯誤。 步驟如下。

Step	設計階段範本：發生時	執行階段範本：發生時
程式碼會從文字範本產生。 指示詞中的錯誤，或是不相符或無序 <#...#> 標記。	當您儲存範本或叫用文字轉換時。	當您儲存範本或叫用文字轉換時。
產生的程式碼會進行編譯。 範本程式碼中的編譯錯誤。	緊接在上一個步驟之後。	連同您的應用程式程式碼。
程式碼執行。 範本程式碼中的執行階段錯誤。	緊接在上一個步驟之後。	當您的應用程式執行並叫用範本程式碼時。

在大部分情況下，會在錯誤報表中提供範本程式碼中的行號。 當錯誤報表參考暫存檔案名稱時，通常的原因是文字範本程式碼中的括弧不符。

您可以在文字範本中設定中斷點，並以一般方式進行偵錯。

常見錯誤和修正

下表列出最常見的錯誤及其修正。

錯誤訊息	描述	解決方案
無法載入轉換類別所繼承的基底類別 '{0}'。	如果您在範本指示詞的 inherits 參數中找不到指定的基底類別，就會發生。 訊息會提供範本指示詞的行號。	請確定指定的類別存在，且其所在位置的組件是在組件指示詞中進行指定。
無法解析下列檔案的 Include 文字：{0}	發生於您找不到包含的範本時。 訊息會提供所要求 include 檔案的名稱。	請確定檔案路徑相對於原始範本路徑，或檔案位於向主機註冊的位置，或是檔案有完整路徑。
初始化轉換物件時產生錯誤。 轉換將不會執行。	發生於轉換類別的 'Initialize()' 失敗或傳回 false 時。	Initialize() 函式中的程式碼來自 <#@template#> 指示詞和指示詞處理器中所指定的基底轉換類別。 導致初始化失敗的錯誤可能位於錯誤清單中。 調查失敗的原因。 您可以遵循程序來偵錯範本，查看 Initialize() 的實際產生程式碼。
指示詞處理器 '{1}' 的組件 '{0}' 未獲授與 FullTrust 權限集合。 只允許信任的組件提供指示詞處理器。 將不會載入此指示詞處理器。	發生於系統未將 FullTrust 權限授與包含指示詞處理器的組件時。 訊息會提供組件的名稱和指示詞處理器的名稱。	請確定您僅在本機電腦上使用受信任的組件。
路徑 '{0}' 必須是這部電腦的本機路徑或是您信任區域的一部分。	發生於指示詞或組件指示詞參考的檔案不在本機電腦或網路信任區域時。	請確定指示詞或組件指示詞所在的目錄位於您信任的區域。 您可以透過 Internet Explorer 將網路目錄新增至您信任的區域。
多個語法錯誤，例如「不正確權杖 'catch'」或「命名空間不能直接包含成員」	範本程式碼中的右大括弧太多。 編譯器會將其與標準產生程式碼混淆。	檢查程式碼分隔符號內的右大括弧和括弧數目。
迴圈或條件未正確編譯或執行。 例如： <#if (i>10)#> Number is: <#= i #> 。 此程式碼一律會輸出 i 的值。 只有「Number is:」是條件式。	在 C# 中，一律使用大括弧括住內嵌在控制項陳述式中的文字區塊。	新增大括弧：<#if (i>10) { #> Number is: <#= i #><# } #>。
處理設計階段範本或編譯執行階段 (預處理) 範本時，「運算式太複雜」。 在嘗試檢查執行階段範本所產生的程式碼時，Visual Studio 會停止運作。	文字區塊太長。 T4 會將文字區塊轉換成字串串連運算式，每個範本行都有一個字串常值。 很長的文字區塊可能會超越編譯器的大小限制。	使用運算式區塊來分割長文字區塊，例如： <#= "" #>

警告描述和修正

下表列出最常見的警告，以及修正程式 (如果有的話)。

警告訊息	描述	解決方案
載入 include 檔案 '{0}' 傳回 Null 或空字串。	如果包含的文字範本檔案空白，就會發生。 訊息會提供 included 檔案的檔案名稱。	請移除 include 指示詞，或確定檔案包含一些內容。
正在編譯轉換：	在此字串前面加上編譯轉換時源自編譯器的所有錯誤或警告。 此字串表示編譯器擲回錯誤或警告。	如果您在尋找 DLL 時發生問題，若 DLL 位於 GAC 中，您可能需要提供完整路徑或完整強式名稱。
'{0}' 參數已存在於指示詞中。 將會忽略重複的參數。	發生於在指示詞中指定參數一次以上時。 訊息會提供參數的名稱和指示詞的行號。	移除重複的參數規格。
載入 include 檔案 '{0}' 時發生錯誤。 將會忽略 include 指示詞。	發生於在 include 指示詞中找不到指定的檔案時。 訊息會提供檔案的名稱和指示詞的行號。	請確定 include 檔案存在於與原始文字範本檔案相同的目錄中，或存在於向主機註冊的其中一個 Include 目錄中。
為 Transformation 類別指定了不正確的基底類別。 基底類別必須衍生自 Microsoft.VisualStudio.TextTemplating.TextTransformation。	發生於範本指示詞中的 inherits 參數指定不繼承自 TextTransformation 的類別時。 訊息會提供範本指示詞的行號。	指定衍生自 TextTransformation 的類別。
'template' 指示詞中指定了不正確的文化特性。 文化特性必須為「xx-XX」格式。 將會使用不因文化特性而異。	發生於範本指示詞中的文化特性參數指定錯誤時。 訊息會提供範本指示詞的行號。	將 culture 參數變更為「xx-XX」格式的有效文化特性。
範本指示詞中指定了不正確的偵錯值 '{0}'。 偵錯值必須為「true」或「false」。 預設會使用「false」。	發生於範本指示詞中的 debug 參數未正確指定時。 訊息會提供範本指示詞的行號。	將偵錯參數設定為「true」或「false」。
範本指示詞中指定了不正確的 HostSpecific 值 '{0}'。 HostSpecific 值必須為「true」或「false」。 預設會使用「false」。	發生於 template 指示詞中的主機特定參數指定不正確時。 訊息會提供範本指示詞的行號。	將主機特定參數設定為「true」或「false」。
'template' 指示詞中指定了不正確的語言 '{0}'。 語言必須為「C#」或「VB」。 將會使用預設值「C#」。	發生於 template 指示詞中指定不支援的語言時。 只允許「C#」或「VB」(不區分大小寫)。 訊息會提供範本指示詞的行號。	將範本指示詞中的 language 參數設定為「C#」或「VB」。
在範本中找到多個輸出指示詞。 除了第一個指示詞之外，所有指示詞都會被忽略。	發生於在範本檔案中指定多個 output 指示詞時。 訊息會提供重複輸出指示詞的行號。	移除重複的 output 指示詞。
在範本中找到多個範本指示詞。 除了第一個指示詞之外，所有指示詞都會被忽略。 應該在一個範本指示詞內指定範本指示詞的多個參數。	發生於您在文字範本檔案 (包括 Included 檔案) 內指定多個 template 指示詞時。 訊息會提供重複範本指示詞的行號。	將不同的 template 指示詞彙總成一個 template 指示詞。
未針對名為 '{0}' 的指示詞指定處理器。 將會忽略指示詞。	發生於您指定 custom 指示詞，但未提供 processor 屬性時。 訊息會提供指示詞的名稱和行號。	提供具有指示詞 processor 處理器名稱的 directive 屬性。
針對名為 '{1}' 的指示詞找不到名為 '{0}' 的處理器。 將會忽略指示詞。	發生於系統找不到您在 custom 指示詞中指定的 directive 處理器時。 訊息會提供指示詞名稱、處理器名稱和指示詞的行號。	將指示詞中的 processor 屬性設定為指示詞處理器的名稱。
找不到指示詞'{1}'的必要參數 '{0}'。 將會忽略指示詞。	發生於系統未提供必要指示詞參數時。 訊息會提供遺漏參數的名稱、指示詞名稱和行號。	提供遺漏的參數。
名為 '{0}' 的處理器不支援名為 '{1}' 的指示詞。 將會忽略指示詞。	發生於指示詞處理器不支援指示詞時。 訊息會提供違規指示詞的名稱和行號，以及指示詞處理器的名稱。	更正指示詞的名稱。
檔案 '{0}' 的 Include 指示詞會造成無限迴圈。	如果指定迴圈 Include 指示詞 (例如，檔案 A 包含檔案 B，其中包括檔案 A)，則會顯示。	請勿指定迴圈 Include 指示詞。
正在執行轉換：	將此字串前面加上執行轉換時所產生的所有錯誤或警告。	不適用。
在區塊中找到非預期的開始或結束標記。 請確定您沒有將開始或結束標記錯誤輸入，且範本中沒有任何巢狀區塊。	當您有非預期的 <# 或 #> 時就會顯示。 也就是說，如果您在另一個尚未關閉的開啟標記之後有 <# ，或者當其之前沒有未關閉的開啟標記時，您就會有 #>。 訊息會提供不相符標記的行號。	請移除不相符的開始或結束標記，或是使用逸出字元。
指定指示詞的格式不正確。 將會忽略指示詞。 請以 <#@ name [parametername="parametervalue"]* #> 格式指定指示詞	如果未以正確的格式指定指示詞，則由剖析器顯示。 訊息會提供不正確指示詞的行號。	請確定所有指示詞的格式都是 <#@ name [parametername="parametervalue"]* #>。 如需詳細資訊，請參閱 T4 文字範本指示詞。
無法為註冊的指示詞處理器 '{1}' 載入組件 '{0}' {2}	發生於主機無法載入指示詞處理器時。 訊息會識別提供給指示詞處理器和指示詞處理器名稱的組件。	請確定指示詞處理器已正確註冊，且組件存在。
無法針對註冊的指示詞處理器 '{2}' 找到組件 '{1}' 中的類型 '{0}' {3}	發生於指示詞處理器類型無法從其組件載入時。 訊息會提供類型、組件和指示詞處理器的名稱。	vshost 會在登錄中找到指示詞處理器資訊 (名稱、組件和類型)。 請確定指示詞處理器已正確註冊，且類型存在於組件中。
載入組件 '{0}' 時發生錯誤	發生於載入組件發生問題時。 訊息會提供組件的名稱。	您可以指定要載入 <@#assembly#> 指示詞中的組件，以及依指示詞處理器。 此字串後面的錯誤訊息應該提供更多資料，說明組件載入失敗的原因。
針對名為 '{1}' 的指示詞建立及初始化處理器時發生問題。 處理器的類型為 {0}。 將會忽略指示詞。	發生於系統無法建立或初始化指示詞處理器時。 訊息會提供指示詞的名稱和行號，以及處理器的類型。	請確定您使用正確的指示詞處理器，且指示詞處理器具有公用預設建構函式。 否則，請使用偵錯選項來找出指示詞處理器的 Initialize() 方法失敗的原因。 如需詳細資訊，請參閱針對文字範本進行疑難排解。
處理名為 '{0}' 的指示詞時擲回例外狀況。	發生於指示詞處理器在處理指示詞時擲回例外狀況時。	請確定指示詞處理器的參數正確無誤。
主機嘗試解析組件參考 '{0}' 時擲回例外狀況。	發生於主機嘗試解析組件參考時擲回例外狀況時。 訊息會提供組件參考字串。	組件參考來自 <@#assembly#> 指示詞及來自指示詞處理器。 請確定組件參數中提供的 'name' 參數正確無誤。
嘗試為指示詞 {2} 指定不支援的 {1} 值 '{0}'	當您提供不支援的要求或提供引數時，會由 RequiresProvidesDirectiveProcessor 發生 (所有產生的指示詞處理器皆由其衍生)。	請確定 name='value' 配對中提供的名稱需要且提供參數正確。