T4 範本指示詞

更新：2011 年 3 月

Visual Studio T4 文字範本的開頭通常是 template 指示詞，用於指定範本的處理方式。 文字範本和其所包含之任何檔案中的 template 指示詞不得超過一個。

如需撰寫文字範本的一般概觀，請參閱撰寫 T4 文字範本。

使用範本指示詞

<#@ template [language="VB"] [compilerOptions="options"] [culture="code"] [debug="true"] [hostspecific="true"] [inherits="templateBaseClass"] #>

template 指示詞具有數個可讓您指定不同轉換層面的屬性。 所有屬性都是選擇性的。

compilerOptions 屬性

• 範例：
  compilerOptions="optimize+"

• 有效值：
  任何有效的編譯器選項。 如需詳細資訊，請參閱 依分類列出的 C# 編譯器選項和 依分類列出 Visual Basic 編譯器選項。

  忽略執行階段 (前置處理過的) 範本。

將範本轉換為 Visual C# 或 Visual Basic 並編譯產生的程式碼時會套用這些選項。

culture 屬性

• 範例：
  culture="de-CH"

• 有效值：
  "" (不因文化特性而異)，此為預設值。

  以 xx-XX 字串形式表示的文化特性。 例如，en-US、ja-JP、de-CH、de-DE。 如需詳細資訊，請參閱 System.Globalization.CultureInfo。

culture 屬性會指定當運算式區塊轉換為文字時所要使用的文化特性。

debug 屬性

• 範例：

  debug="true"
  

• 有效值：
  true, false. 預設值為 False。

debug 屬性會指定是否要啟用偵錯。 如果為 true，表示中繼程式碼檔將會包含啟用偵錯工具所需的相關資訊，以識別範本內中斷或例外狀況發生的位置。 就設計階段範本來說，中繼程式碼檔會被寫入 %TEMP% 目錄。

若要在範本執行時於特定的點啟動偵錯工具，請插入 Launch 的呼叫。 若要在後續的點中斷執行，請插入 Break 的呼叫。 例如：

<#@ template debug="true" language="C#" #>
<#@ output extension=".txt" #>
Output something.
<# 
 // Break here:
 System.Diagnostics.Debugger.Launch();  
#>
Output more.
<#
 // Break here also:
 System.Diagnostics.Debugger.Break();  
#>
Output more.

如需詳細資訊，請參閱逐步解說：偵錯文字範本。

hostspecific 屬性

• 範例：

  hostspecific="true"
  

• 有效值：
  true, false. 預設值為 False。

如果您將這個屬性值設定為 true，就會有名為 Host 的屬性加入至文字範本所產生的類別中。 此屬性是轉換引擎主應用程式的參考，並宣告為 Microsoft.VisualStudio.TextTemplating.ITextTemplatingEngineHost。 如果您定義了自訂主應用程式，則可以將它轉換為自訂主應用程式型別。

由於這個屬性的型別依主應用程式的型別而定，因此只有在撰寫僅限搭配特定主應用程式使用的文字範本時才有用處。

當 hostspecific 為 true 且您正在使用 Visual Studio 時，可以將 this.Host 的型別轉換為 IServiceProvider 來存取 Visual Studio 的功能。 您也可以使用 Host.ResolvePath(filename) 取得專案中檔案的絕對路徑。 例如：

<#@ template debug="false" hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#@ import namespace="EnvDTE" #>
<#@ import namespace="System.IO" #>
<# // Get the Visual Studio API as a service:
 DTE dte = ((IServiceProvider)this.Host).GetService(typeof(DTE)) as DTE;  
#>
Number of projects in this solution: <#=  dte.Solution.Projects.Count #>

<#
 // Find a path within the current project:
 string myFile = File.ReadAllText(this.Host.ResolvePath("MyFile.txt"));
#>
Content of myFile is:
<#= myFile #>

language 屬性

• 範例：
  language="VB"

• 有效值：
  C# (預設值)

  VB

  (在這個版本中，VBv3.5 和 C#v3.5 值都已過時，但將會解譯為 VB 和 C#)。

language 屬性會指定在陳述式及運算式區塊中原始程式碼使用的語言 (Visual Basic 或 Visual C#)。 從中產生輸出的中繼程式碼檔會使用這個語言。 這個語言與範本產生的語言無關，它可以是任何種類的文字。

例如：

<#@ template language="VB" #>
<#@ output extension=".txt" #>
Squares of numbers:
<#
  Dim number As Integer
  For number = 1 To 4
#>
  Square of <#= number #> is <#= number * number #>
<#
  Next number
#>

inherits 屬性

您可以指定範本的程式碼是否能繼承自另一個類別，而且這個類別也可從文字範本產生。

執行階段 (前置處理過的) 文字範本中的繼承

您可以在執行階段文字範本之間使用繼承，以建立基本範本，此範本會擁有數個衍生的變體。 [自訂工具] 屬性設為 TextTemplatingFilePreprocessor 的範本，即為執行階段範本。 執行階段範本會產生您可以在應用程式中呼叫的程式碼，用以建立範本中定義的文字。 如需詳細資訊，請參閱使用前置處理過的 T4 文字範本在執行階段產生文字。

如果沒有指定 inherits 屬性，則會從文字範本產生基底類別和衍生類別。 指定 inherits 屬性時，只會產生衍生類別。 您可以手動撰寫基底類別，但是它必須提供衍生類別所用的方法。

更典型的是，您會將另一個前置處理過的範本指定為基底類別。 基底範本提供通用的文字區塊，可以與衍生之範本的文字相互交錯。 您可以使用 <#+ ... #> 類別功能區塊，以定義包含文字片段的方法。 例如，您可以在基底範本中放置輸出文字的架構，提供可在衍生之範本中被覆寫的虛擬方法：

• 執行階段 (前置處理過的) 文字範本 BaseTemplate.tt：

  This is the common header.
  <# 
    SpecificFragment1(); 
  #>
  A common central text.
  <# 
    SpecificFragment2(); 
  #>
  This is the common footer.
  <#+ 
    // Declare abstract methods
    protected virtual void SpecificFragment1() { }
    protected virtual void SpecificFragment2() { }
  #>
  

• 執行階段 (前置處理過的) 文字範本 DerivedTemplate1.tt：

  <#@ template language="C#" inherits="BaseTemplate" #>
  <# 
    // Run the base template:
    base.TransformText();
  #>
  <#+
  // Provide fragments specific to this derived template:
  protected override void SpecificFragment1()
  {
  #>
     Fragment 1 for DerivedTemplate1
  <#+
  }
  protected override void SpecificFragment2()
  {
  #>
     Fragment 2 for DerivedTemplate1
  <#+
  }
  #>
  

• 用來叫用 DerivedTemplate1 的應用程式程式碼：

  Console.WriteLine(new DerivedTemplate().TransformText());
  

• 產生的輸出：

  This is the common header.
     Fragment 1 for DerivedTemplate1
  A common central text.
     Fragment 2 for DerivedTemplate1
  This is the common footer.
  

您可以在不同的專案中建置基底和衍生類別。 請記得將基底專案或組件加入至衍生專案的參考。

您也可以將一般手寫的類別當做基底類別。 基底類別必須提供衍生類別所用的方法。

設計階段文字範本中的繼承

[自訂工具] 設為 TextTemplatingFileGenerator 的檔案，即為設計階段文字範本。 這種範本會為形成 Visual Studio 專案之一部分的程式碼或文字產生輸出檔。 為產生輸出檔，會先將範本轉譯為中繼程式碼檔，後者通常不會顯示出來。 inherits 屬性會為這個中繼程式碼指定基底類別。

如果是設計階段文字範本，您可指定任何衍生自 Microsoft.VisualStudio.TextTemplating.TextTransformation 的基底類別。 使用 <#@assembly#> 指示詞，可以載入包含基底類別的組件或專案。

如需詳細資訊，請參閱 Gareth Jones 部落格文章：文字範本中的繼承(英文)。

變更記錄