T4 範本指示詞

發行項
02/22/2013

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

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

使用範本指示詞

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

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% 目錄。

若要在偵錯工具的設計階段範本，請開啟文字範本的捷徑功能表在 [方案總管] 中的，然後選取 [偵錯 T4 範本]。

hostspecific 屬性

範例：
```
hostspecific="true"
```
有效值：
true, false, trueFromBase.預設值為 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).GetCOMService(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 #>

如果您使用 inherits 和 hostspecific 屬性，請指定" true」host= " trueFromBase」在衍生類別和的 host=在基底類別。這可避免 Host 屬性的雙定義所產生程式碼的。

language 屬性

範例：
language="VB"
有效值：
C# (預設值)

VB

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.

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

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

警告
如果您使用 inherits 和 hostspecific 屬性，請指定 hostspecific= " trueFromBase」在衍生類別和 host= " true」在基底類別。這可避免 Host 屬性的雙定義所產生程式碼的。

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

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

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

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

LinePragmas 屬性

範例：
linePragmas="false"
有效值：
true (預設值)

false

設定為 false 的這個屬性移除工作階段狀態值在產生的程式碼中的行號的標記。這表示您可以使用產生的程式碼中的行號，編譯器就會報告錯誤。這會讓您更多偵錯選項，在中，您可以選擇偵錯文字範本或產生的程式碼。

這個屬性也說明，如果您發現加註的絕對檔名產生分散合併在原始程式碼控制之下。

可視性屬性

範例：
visibility="internal"
有效值：
public (預設值)

internal

在執行階段文字範本，這個設定所產生之類別的可視性屬性。根據預設，類別是程式碼公用 API 的一部分，不過，您可以設定 visibility="internal" 您可以確認，您的程式碼可以使用文字產生的類別。

共用方式為