T4 テンプレート ディレクティブT4 Template Directive

Visual Studio T4 テキストテンプレートは、通常、 template テンプレートの処理方法を指定するディレクティブで始まります。A Visual Studio T4 text template usually starts with a template directive, which specifies how the template should be processed. テキスト テンプレートおよびそれに含まれるファイルには、template ディレクティブを 1 つしか含めることができません。There should be no more than one template directive in a text template and any files that it includes.

テキストテンプレートの記述の概要については、「 T4 テキストテンプレートの作成」を参照してください。For a general overview of writing text templates, see Writing a T4 Text Template.

template ディレクティブの使用Using the Template Directive

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

template ディレクティブには、変換のさまざまな側面を指定できる属性がいくつかあります。The template directive has several attributes that allow you to specify different aspects of the transformation. 属性はすべて省略可能です。All the attributes are optional.

compilerOptions 属性compilerOptions attribute

例:Example:

compilerOptions="optimize+"

有効な値:Valid values:

有効なコンパイラ オプション。Any valid compiler options.

実行時 (前処理された) テンプレートでは無視されます。Ignored for run-time (preprocessed) templates.

テンプレートが Visual C#Visual C# または Visual BasicVisual Basic に変換されている場合にこれらのオプションが適用され、生成されたコードがコンパイルされます。These options are applied when the template has been converted into Visual C#Visual C# or Visual BasicVisual Basic, and the resulting code is compiled.

culture 属性culture attribute

例:Example:

culture="de-CH"

有効な値:Valid values:

インバリアント カルチャである "" (既定値)。"", the invariant culture, which is the default.

xx-XX 形式の文字列で表現されたカルチャ。A culture expressed as a string in the form xx-XX. たとえば、en-US、ja-JP、de-CH、de-DE などがあります。For example, en-US, ja-JP, de-CH, de-DE. 詳細については、「System.Globalization.CultureInfo」を参照してください。For more information, see System.Globalization.CultureInfo.

culture 属性では、式ブロックをテキストに変換する際に使用するカルチャを指定します。The culture attribute specifies the culture to use when an expression block is converted to text.

debug 属性debug attribute

例:Example:

debug="true"

有効な値:Valid values:

true

false (既定値)false (default)

debug 属性が true の場合、デバッガーでテンプレート内の中断または例外の発生位置を正確に特定できるようにする情報が中間コード ファイルに出力されるようになります。If the debug attribute is true, the intermediate code file will contain information that enables the debugger to identify more accurately the position in your template where a break or exception occurred.

デザイン時テンプレートの場合、中間コードファイルは % TEMP% ディレクトリに書き込まれます。For design-time templates the intermediate code file will be written to your %TEMP% directory.

デバッガーでデザイン時テンプレートを実行するには、テキストテンプレートを保存し、ソリューションエクスプローラーでテキストテンプレートのショートカットメニューを開き、[ T4 テンプレートのデバッグ] を選択します。To run a design-time template in the debugger, save the text template, then open the shortcut menu of the text template in Solution Explorer, and choose Debug T4 Template.

hostspecific 属性hostspecific attribute

例:Example:

hostspecific="true"

有効な値:Valid values:

true

false (既定値)false (default)

trueFromBase

この属性の値を true に設定した場合、テキスト テンプレートによって生成されたクラスに、Host というプロパティが追加されます。If you set the value of this attribute to true, a property named Host is added to the class generated by your text template. プロパティは、変換エンジンのホストへの参照で、 ITextTemplatingEngineHostとして宣言されます。The property is a reference to the host of the transformation engine, and is declared as ITextTemplatingEngineHost. カスタム ホストを定義している場合は、そのカスタム ホストの型にキャストできます。If you have defined a custom host, you can cast it to the custom host type.

このプロパティの型はホストの型に依存するため、特定のホストとのみ連携するテキスト テンプレートを作成している場合以外、利用価値はありません。Because the type of this property depends on the type of host, it is only useful if you are writing a text template that works only with a specific host. これは、 デザイン時テンプレートには適用できますが、 実行時テンプレートには適用されません。It's applicable to design-time templates, but not run-time templates.

hostspecifictrue で、visual studio を使用している場合は、IServiceProvider にキャストして this.Host visual studio の機能にアクセスできます。When hostspecific is true and you are using Visual Studio, you can cast this.Host to IServiceProvider to access Visual Studio features. また、Host.ResolvePath(filename) を使用して、プロジェクトのファイルの絶対パスを取得することもできます。You can also use Host.ResolvePath(filename) to obtain the absolute path of a file in the project. 次に例を示します。For example:

<#@ template debug="false" hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#@ import namespace="EnvDTE" #>
<#@ import namespace="System.IO" #>
<#@ import namespace="Microsoft.VisualStudio.TextTemplating" #>
<# // 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 属性を一緒に使用する場合は、派生クラスで host="trueFromBase"、基底クラスで host="true" を指定します。If you use the inherits and hostspecific attributes together, specify host="trueFromBase" in the derived class and host="true" in the base class. これで、生成されるコードで Host プロパティの定義が重複することを回避できます。This avoids a double definition of the Host property in the generated code.

language 属性language attribute

例:Example:

language="VB"

有効な値:Valid values:

C# (既定値)C# (default)

VB

属性は、 language Visual BasicVisual Basic Visual C#Visual C# ステートメントおよび式ブロック内のソースコードに使用する言語 (または) を指定します。The language attribute specifies the language (Visual BasicVisual Basic or Visual C#Visual C#) to use for the source code in statement and expression blocks. 出力の生成元である中間コード ファイルでこの言語が使用されます。The intermediate code file from which the output is generated will use this language. この言語はテンプレートで生成される言語とは無関係であり、どのような種類のテキストであってもかまいません。This language is not related to the language that your template generates, which can be any kind of text.

次に例を示します。For example:

<#@ 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 属性inherits attribute

テンプレートのプログラム コードを別のクラスから継承できることを指定できます。クラスは、テキスト テンプレートから生成することもできます。You can specify that the program code of your template can inherit from another class, which can also be generated from a text template.

実行時 (前処理された) テキスト テンプレートでの継承Inheritance in a run-time (preprocessed) text template

実行時テキスト テンプレート間で継承を使用して、複数の派生バリアントを含む基本テンプレートを作成できます。You can use inheritance between run-time text templates to create a basic template that has several derived variants. 実行時テンプレートは、 カスタムツール プロパティが Texttemplatingfilepreprocessor プロセッサに設定されているテンプレートです。Run-time templates are those that have the Custom Tool property set to TextTemplatingFilePreprocessor. 実行時テンプレートでは、そのテンプレートに定義されているテキストを作成するために、アプリケーションで呼び出すことができるコードが生成されます。A run-time template generates code that you can call in your application to create the text defined in the template. 詳細については、「T4 テキスト テンプレートを使用した実行時テキスト生成」を参照してください。For more information, see Run-Time Text Generation with T4 Text Templates.

inherits 属性を指定しない場合は、テキスト テンプレートから基底クラスと派生クラスが生成されます。If you do not specify an inherits attribute, a base class and a derived class are generated from your text template. inherits 属性を指定すると、派生クラスだけが生成されます。When you specify an inherits attribute, only the derived class is generated. 基底クラスは手動で作成できますが、派生クラスで使用するメソッドを提供する必要があります。You can write a base class by hand, but it must provide the methods that are used by the derived class.

通常は、前処理された別のテンプレートを基底クラスとして指定します。More typically, you specify another preprocessed template as the base class. 基本テンプレートでは、派生テンプレートのテキストとインタリーブできる共通のテキスト ブロックを提供します。The base template provides common blocks of text, which can be interleaved with text from the derived templates. クラス機能ブロック (<#+ ... #>) を使用して、テキスト フラグメントを含むメソッドを定義できます。You can use class feature blocks <#+ ... #> to define methods that contain text fragments. たとえば、基本テンプレートに出力テキストのフレームワークを配置し、派生テンプレートでオーバーライドできる仮想メソッドを提供することができます。For example, you can place the framework of the output text in the base template, providing virtual methods that can be overridden in derived templates:

実行時 (前処理された) テキスト テンプレートの BaseTemplate.tt:Run-time (preprocessed) text template 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:Run-time (preprocessed) text template 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 を呼び出すアプリケーション コード:Application code to invoke DerivedTemplate1:

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

結果の出力:Resulting output:

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

さまざまなプロジェクトの基底クラスと派生クラスを作成できます。You can build the base and derived classes in different projects. 基本プロジェクトまたはアセンブリを派生プロジェクトの参照に追加することを忘れないでください。Remember to add the base project or assembly to the derived project's references.

手動で作成した通常のクラスを基底クラスとして使用することもできます。You can also use an ordinary hand-written class as the base class. 基底クラスでは、派生クラスで使用するメソッドを提供する必要があります。The base class must provide the methods used by the derived class.

警告

inherits 属性と hostspecific 属性を一緒に使用する場合は、派生クラスで hostspecific="trueFromBase"、基底クラスで host="true" を指定します。If you use the inherits and hostspecific attributes together, specify hostspecific="trueFromBase" in the derived class and host="true" in the base class. これで、生成されるコードで Host プロパティの定義が重複することを回避できます。This avoids a double definition of the Host property in the generated code.

デザイン時テキスト テンプレートでの継承Inheritance in a design-time text template

デザイン時テキストテンプレートは、 カスタムツールTexttemplatingfilegeneratorに設定されているファイルです。A design-time text template is a file for which Custom Tool is set to TextTemplatingFileGenerator. このテンプレートは、Visual Studio プロジェクトの一部を形成するコードまたはテキストの出力ファイルを生成します。The template generates an output file of code or text, which forms part of your Visual Studio project. 出力ファイルを生成するために、テンプレートは、まず中間プログラム コード ファイルに変換されます。通常、このファイルは表示されません。To generate the output file, the template is first translated into an intermediate program code file, which you do not usually see. inherits 属性では、この中間コードの基底クラスを指定します。The inherits attribute specifies the base class for this intermediate code.

デザイン時テキスト テンプレートの場合、Microsoft.VisualStudio.TextTemplating.TextTransformation から派生した基底クラスを指定できます。For a design-time text template, you can specify any base class that is derived from Microsoft.VisualStudio.TextTemplating.TextTransformation. <#@assembly#> ディレクティブを使用して、基底クラスを含むアセンブリまたはプロジェクトを読み込みます。Use the <#@assembly#> directive to load the assembly or project that contains the base class.

詳細については、 Gareth Jones のブログの「テキストテンプレートでの継承」を参照してください。For more information, see "Inheritance in Text Templates" in Gareth Jones' Blog.

linePragmas グマ属性linePragmas attribute

例:Example:

linePragmas="false"

有効な値:Valid values:

true (既定値)true (default)

false

この属性を false に設定すると、生成されたコード内で行番号を識別するタグが削除されます。Setting this attribute to false removes the tags that identify your line numbers within the generated code. つまり、コンパイラは生成されたコードの行番号を使用してエラーを報告します。このため、デバッグ時の選択肢が増えて、テキスト テンプレートをデバッグするか、それとも生成されたコードをデバッグするかを選択できます。This means that the compiler will report any errors by using line numbers of the generated code.This gives you more debugging options, as you can choose to debug either the text template or the generated code.

この属性は、プラグマ内の絶対ファイル名が見つかった場合にも、ソースコード管理下で混乱が生じないようにするために役立ちます。This attribute can also help if you're finding the absolute filenames in pragmas are causing distracting merges under source code control.

visibility 属性visibility attribute

例:Example:

visibility="internal"

有効な値:Valid values:

public (既定値)public (default)

internal

実行時テキスト テンプレートでは、これは生成されたクラスの可視性属性を設定します。In a runtime text template, this sets the visibility attribute of the generated class. 既定では、クラスはコードのパブリック API の一部ですが、visibility="internal" を設定すると、自分のコードだけがそのテキスト生成クラスを使用するようにできます。By default, the class is part of the public API of your code, but by setting visibility="internal" you can make sure that only your code can use the text-generating class.