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

更新 : 2011 年 3 月

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

テキスト テンプレートの作成方法の概要については、「T4 テキスト テンプレートの作成」を参照してください。

template ディレクティブの使用

<#@ 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 のブログを参照してください。

履歴の変更

日付	履歴	理由
2011 年 3 月	親トピックから分離されました。 compilerOptions が追加されました。 テキスト テンプレートの継承に関するブログ エントリへのリンクが追加されました。	情報の拡充