T4 模板指令

项目
02/21/2013

Visual Studio T4 文本模板通常以 template 指令开头，该指令指定应如何处理模板。文本模板及其包括的任何文件中不应有多个 template 指令。

有关编写文本模板的一般概述，请参见编写 T4 文本模板。

使用 Template 指令

<#@ 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 博客中的“Inheritance in Text Templates”（文本模板中的继承）。

LinePragmas 属性

示例：
linePragmas="false"
有效值：
true（默认值）

false

将此属性设置为 false 将移除标识您在生成的代码中的行号的标记。这意味着可以使用生成的代码，的行号编译器将报告所有错误。这使您更多调试选择，在中，您可以选择调试文本模板或生成的代码。

此属性还有助于，如果发现杂注中的绝对文件名导致混乱合并在源代码管理之下。

可见性特性

示例：
visibility="internal"
有效值：
public（默认值）

internal

在运行时文本模板，则设置生成的选件类的可见性特性。默认情况下，选件类是您的代码公共 API 的一部分，但是，通过设置 visibility="internal" 可以确保，则您的代码只能使用文本生成的选件类。

通过