建立自訂 T4 文字範本指示詞處理器

「文字範本轉換流程」採用「文字範本」檔案做為輸入，並產生文字檔做為輸出。 「文字範本轉換引擎」會控制流程，而且此引擎會與文字範本轉換主機和一或多個文字範本「指示詞處理器」互動，以完成流程。 如需詳細資訊，請參閱文字範本轉換流程。

若要建立自訂指示詞處理器，您可以建立繼承 DirectiveProcessor 或 RequiresProvidesDirectiveProcessor 的類別。

這兩者之間的差異在於 DirectiveProcessor 會實作從使用者取得參數所需的最少介面，並產生可產生範本輸出檔的程式碼。 RequiresProvidesDirectiveProcessor 會實作「要求/提供」設計模式。 RequiresProvidesDirectiveProcessor 會處理兩個特殊參數 (requires 和 provides)。 例如，自訂指示詞處理器可能會接受來自使用者的檔案名稱、開啟和讀取檔案，然後將檔案的文字儲存在名為 fileText 的變數中。 RequiresProvidesDirectiveProcessor 類別的子類別可能會從使用者取得檔案名稱做為 requires 參數的值，以及取得要儲存文字的變數名稱做為 provides 參數的值。 此處理器會開啟並讀取檔案，然後將該檔案的文字儲存在指定的變數中。

在從 Visual Studio 中的文字範本呼叫自訂指示詞處理器之前，您必須先註冊該處理器。

如需如何新增登錄機碼的詳細資訊，請參閱部署自訂指示詞處理器。

自訂指示詞

自訂指示詞看起來像這樣：

<#@ MyDirective Processor="MyDirectiveProcessor" parameter1="value1" ... #>

想要從文字範本存取外部資料或資源時，您可以使用自訂指示詞處理器。

不同的文字範本可以共用單一指示詞處理器所提供的功能，因此指示詞處理器會提供一種方法，來分解程式碼以供重複使用。 內建 include 指示詞是類似的，因為您可以使用其來分解程式碼，並在不同的文字範本之間共用。 差異在於 include 指示詞所提供的任何功能都是固定的，而且不接受參數。 如果想要將一般功能提供給文字範本，並允許範本傳遞參數，您必須建立自訂指示詞處理器。

自訂指示詞處理器的一些範例可以是：

• 從資料庫傳回資料的指示詞處理器，其接受使用者名稱和密碼做為參數。

• 要開啟和讀取檔案的指示詞處理器，其接受檔案的名稱做為參數。

自訂指示詞處理器的主體部分

若要開發指示詞處理器，您必須建立繼承自 DirectiveProcessor 或 RequiresProvidesDirectiveProcessor 的類別。

您必須實作的最重要 DirectiveProcessor 方法如下。

• bool IsDirectiveSupported(string directiveName) - 如果您的指示詞處理器可以處理具名指示詞，則傳回 true。

• void ProcessDirective (string directiveName, IDictionary<string, string> arguments) - 範本引擎會針對範本中每個出現的指示詞呼叫這個方法。 您的處理器應該儲存結果。

在對 ProcessDirective() 進行所有呼叫之後，範本化引擎會呼叫下列方法：

• string[] GetReferencesForProcessingRun() - 傳回範本程式碼所需的組件名稱。

• string[] GetImportsForProcessingRun() - 傳回可用於範本程式碼的命名空間。

• string GetClassCodeForProcessingRun() - 傳回範本程式碼可以使用的方法、屬性和其他宣告的程式碼。 若要這樣做，最容易的方式是建置一個字串，包含 C# 或 Visual Basic 程式碼。 若要使指示詞處理器能夠從使用任何 CLR 語言的範本進行呼叫，您可以將陳述式建構為 CodeDom 樹狀結構，然後傳回以範本所使用語言序列化樹狀結構的結果。

• 如需詳細資訊，請參閱逐步解說：建立自訂指示詞處理器。

相關內容

• 部署自訂指示詞處理器說明如何註冊自訂指示詞處理器。
• 逐步解說：建立自訂指示詞處理器描述如何建立自訂指示詞處理器、如何註冊和測試指示詞處理器，以及如何將輸出檔案格式化為 HTML。