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

通常、Visual Studio の T4 テキストテンプレートは、テンプレートの処理方法を指定する template ディレクティブで始まります。テキストテンプレートおよびそれに含まれるファイルには、template ディレクティブを 1 つしか含めることができません。

テキストテンプレートの作成方法の概要については、「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 の属性を一緒に使用する場合は、派生クラスでhost=」true "」および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 の属性を一緒に使用する場合は、基本クラスと派生クラスで」true "にhost= hostspecific= "」trueFromBaseを指定します。これは、生成されるコードの 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" を設定して、コードだけがテキスト生成クラスを使用できることを確認できます。

Last updated on 2013-02-21