T4 テキストテンプレートを使用したデザイン時コード生成

[アーティクル]
08/09/2011

更新 : 2010 年 10 月

デザイン時 T4 テキストテンプレートを使用して、Visual Studio プロジェクトのプログラムコードや他のファイルを生成できます。テンプレートを作成するときは、モデルのデータに応じて生成されるコードが変わるようにするのが一般的です。モデルとは、アプリケーションの要件に関する重要な情報が含まれたファイルまたはデータベースのことです。

たとえば、ワークフローをテーブルまたは図として定義したモデルがあるとします。このモデルから、ワークフローを実行するソフトウェアを生成できます。ユーザーの要件が変わったときに、新しいワークフローについてユーザーと共に検討しやすくなります。ワークフローからコードを再生成すると、コードを手動で更新するよりも信頼性が高まります。

注意

モデルは、アプリケーションの特定の側面を記述したデータソースです。モデルはどのような形式でもかまいません。あらゆる種類のファイルまたはデータベースを使用できます。 UML モデルやドメイン固有言語モデルなどの特定の形式である必要はありません。標準的なモデルの形式は、テーブルまたは XML ファイルです。

コード生成は決して新しい概念ではありません。 Visual Studio ソリューションにある .resx ファイルでリソースを定義すると、一連のクラスおよびメソッドが自動的に生成されます。リソースの編集は、クラスやメソッドを直接編集するよりも、リソースファイルで行った方がはるかに簡単で確実です。同様に、テキストテンプレートを使用すると、独自に設計したソースからコードを生成することができます。

テキストテンプレートには、生成するテキストと、テキストの可変部分を生成するプログラムコードの組み合わせが含まれます。プログラムコードにより、生成されるテキストの一部を繰り返したり、条件に従って省略したりできるようになります。生成されるテキスト自体を、アプリケーションの一部となるプログラムコードにすることもできます。

デザイン時 T4 テキストテンプレートを作成する

Visual Studio でデザイン時 T4 テンプレートを作成するには

Visual Studio プロジェクトを作成するか、既存のプロジェクトを開きます。

たとえば、[ファイル] メニューの [新規作成] をポイントし、[プロジェクト] をクリックします。
テキストテンプレートファイルをプロジェクトに追加し、NewTemplate.tt という名前を付けます。

これを行うには、ソリューションエクスプローラーでプロジェクトを右クリックし、[追加] をポイントして [新しい項目] をクリックします。 [新しい項目の追加] ダイアログボックスで、[テンプレート] ペインの [テキストテンプレート] を選択します。このファイルに「NewTemplate.tt」という名前を付けます。

ファイルの [カスタムツール] プロパティが TextTemplatingFileGenerator となっていることに注目してください。
ファイルを開きます。既に次のディレクティブが指定されています。
```
<#@ template debug="false" hostspecific="false" language="C#" #>
<#@ output extension=".txt" #>
```
Visual Basic プロジェクトにテンプレートを追加した場合、言語属性は "VB" になります。
ファイルの最後にテキストを追加します。次に例を示します。
```
Hello, world!
```
ファイルを保存します。

テンプレートを実行してよいか確認する [セキュリティ警告] メッセージボックスが表示されます。 [OK] をクリックします。
ソリューションエクスプローラーで、NewTemplate.tt ノードを展開すると、NewTemplate.txt というファイルが見つかります。このファイルには、先ほど入力したテキストが含まれています。

注意

Visual Basic プロジェクトの場合は、[すべてのファイルを表示] をクリックしないと、NewTemplate.txt 出力ファイルが表示されません。

コードの再生成

次のいずれかの場合に、テンプレートが実行され、従属ファイルが生成されます。

テンプレートを編集した後、フォーカスを別の Visual Studio ウィンドウに切り替えたとき。
テンプレートを保存したとき。
ソリューションエクスプローラーのツールバーの [すべてのテンプレートの変換] をクリックしたとき。この場合、Visual Studio ソリューション内のすべてのテンプレートが変換されます。
ソリューションエクスプローラー内の 1 つまたは複数のファイルを右クリックし、[カスタムツールの実行] をクリックしたとき。この方法は、複数のテンプレートを選択して変換する場合に使用します。

読み取り先のデータファイルが変更されたときにテンプレートが実行されるよう、Visual Studio プロジェクトを設定することもできます。詳細については、「コードを自動的に再生成する」を参照してください。

可変テキストを生成する

テキストテンプレートから生成されるファイルのコンテンツは、プログラムコードを使用して変化させることができます。

プログラムコードを使用してテキストを生成するには

.tt ファイルの内容を次のように変更します。

<#@ template debug="false" hostspecific="false" language="C#" #>
<#@ output extension=".txt" #>
<#int top = 10;

for (int i = 0; i<=top; i++) { #>
The square of <#= i #> is <#= i*i #>
<# } #>

<#@ template debug="false" hostspecific="false" language="VB" #>
<#@ output extension=".txt" #>
<#Dim top As Integer = 10

For i As Integer = 0 To top
#>
    The square of <#= i #> is <#= i*i #>
<#
Next
#>

.tt ファイルを保存し、生成された .txt ファイルを再度確認します。 0 から 9 の数値を 2 乗した値が一覧表示されます。

複数のステートメントは <#...#> で囲まれており、単一の式は <#=...#> で囲まれていることに注意してください。詳細については、「T4 テキストテンプレートの作成」を参照してください。

Visual Basic で生成コードを記述する場合は、template ディレクティブに language="VB" を含める必要があります。 "C#" が既定値です。

ソリューションのコードまたはリソースを生成する

生成するプログラムファイルは、モデルに応じて変化させることができます。モデルは入力です。たとえば、データベース、構成ファイル、UML モデル、DSL モデルなど、各種のソースがそれに該当します。プログラムファイルは、同じモデルから複数生成するのが一般的です。そのためには、生成するプログラムファイルごとにテンプレートファイルを作成し、すべてのテンプレートで同じモデルを読み取るようにします。

プログラムコードまたはリソースを生成するには

適切な種類のファイル (.cs、.vb、.resx、.xml など) を生成するように output ディレクティブを変更します。

必要なソリューションコードを生成するためのコードを挿入します。たとえば、クラス内に整数型のフィールド宣言を 3 つ生成するには、次のようにします。

                  <#@ template debug="false" hostspecific="false" language="C#" #>
<#@ output extension=".cs" #>
<# var properties = new string [] {"P1", "P2", "P3"}; #>
class MyGeneratedClass {
<# 
  foreach (string propertyName in properties)
  { #>
  private int <#= propertyName #> = 0;
<# } #>
}

<#@ template debug="false" hostspecific="false" language="VB" #>
<#@ output extension=".cs" #>
<# Dim properties = {"P1", "P2", "P3"} #>
class MyGeneratedClass {
<# 
   For Each propertyName As String In properties
#>
  private int <#= propertyName #> = 0;
<#
   Next
#>
}

ファイルを保存し、生成されたファイルを調べると、次のコードが含まれていることがわかります。
```
class MyGeneratedClass {
  private int P1 = 0; 
  private int P2 = 0;
  private int P3 = 0;
}
```

生成コードと生成されたテキスト

プログラムコードを生成する際に最も重要なことは、テンプレート内で実行されるコード生成機構 (コードを生成するためのコード) と、結果として生成されるコード (ソリューションの一部になるコード) とを混同しないことです。 2 つの言語が必ずしも一致している必要はありません。

前の例は、2 つのバージョンで構成されています。 1 つ目のバージョンは C# のコードで生成されます。 2 つ目のバージョンは、Visual Basic のコードで生成されます。ただし、両方のコードで生成されるテキストは同じであり、C# クラスです。

同様に、Visual C# テンプレートは、どのような言語のコードでも生成できます。生成されるテキストは、プログラムコードが含まれる固有の言語である必要はありません。

テキストテンプレートの構成

ここでは、テンプレートコードを次の 2 つの部分に分けています。

構成またはデータ収集の部分。この部分では変数に値を設定しますが、テキストブロックは含まれません。前の例では、properties の初期化の部分が該当します。

この部分はインストアモデルを構築し、通常はモデルファイルを読み取るため、"モデル" セクションとも呼ばれます。
テキスト生成部分 (この例では、foreach(...){...})。この部分では変数の値を使用します。

必ずしもこのように分ける必要はありませんが、このように記述すると、テキストを含む部分の複雑さが軽減され、テンプレートが読みやすくなります。

ファイルなど各種ソースを読み取る

モデルファイルまたはモデルデータベースにアクセスするために、テンプレートコードで System.XML などのアセンブリを使用できます。これらのアセンブリにアクセスするためには、次のようなディレクティブを挿入する必要があります。

<#@ assembly name="System.Xml.dll" #>
<#@ import namespace="System.Xml" #>
<#@ import namespace="System.IO" #>

assembly ディレクティブでアセンブリを指定することによって、Visual Studio プロジェクトの [参照設定] セクションに表示されるアセンブリと同じように、指定されたアセンブリにテンプレートコードからアクセスすることができます。 System.dll への参照を含める必要はありません。System.dll は自動的に参照されます。 import ディレクティブの効果は、完全修飾名を使用せずに型を指定できるようになることです。通常のプログラムファイルで using ディレクティブを使用した場合と同様です。

たとえば、System.IO のインポート後に、次のようなコードを記述できます。

          <# var properties = File.ReadLines("C:\\propertyList.txt");#>
...
<# foreach (string propertyName in properties) { #>
...

<# For Each propertyName As String In 
             File.ReadLines("C:\\propertyList.txt")
#>

相対パス名を指定してファイルを開く

テキストテンプレートを基準とする場所からファイルを読み込むには、this.Host.ResolvePath() を使用します。 this.Host を使用するには、次のように template で hostspecific="true" を設定する必要があります。

<#@ template debug="false" hostspecific="true" language="C#" #>

これで、次のようなコードを記述できるようになります。

<# string fileName = this.Host.ResolvePath("filename.txt");
  string [] properties = File.ReadLines(filename);
#>
...
<#  foreach (string propertyName in properties { #>
...

<# Dim fileName = Me.Host.ResolvePath("propertyList.txt")
   Dim properties = File.ReadLines(filename)
#>
...
<#   For Each propertyName As String In properties
...
#>

this.Host.TemplateFile を使用して、現在のテンプレートファイルの名前を示すこともできます。

this.Host (VB の場合は Me.Host) の型は、Microsoft.VisualStudio.TextTemplating.ITextTemplatingEngineHost です。

Visual Studio からデータを取得する

Visual Studio で提供されるサービスを使用するには、hostSpecific 属性を設定し、EnvDTE アセンブリを読み込みます。次に例を示します。

<#@ template hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#
  IServiceProvider serviceProvider = (IServiceProvider)this.Host;
  EnvDTE.DTE dte = (EnvDTE.DTE) serviceProvider.GetService(typeof(EnvDTE.DTE));
#>

Number of projects in this VS solution:  <#= dte.Solution.Projects.Count #>

コードを自動的に再生成する

Visual Studio ソリューションには、1 つの入力モデルを使用して複数のファイルを生成するのが一般的です。各ファイルはそれぞれ対応するテンプレートから生成されますが、すべてのテンプレートは同じモデルを参照します。

ソースモデルが変更された場合は、ソリューションのすべてのテンプレートを再度実行する必要があります。これを手動で行うには、ソリューションエクスプローラーのツールバーにある [すべてのテンプレートの変換] をクリックします。

Visual Studio Visualization and Modeling SDK がインストールされている場合は、ビルドを実行するたびにすべてのテンプレートが自動的に変換されるように設定できます。そのためには、プロジェクトファイル (.csproj または .vbproj) をテキストエディターで編集し、ファイルの末尾付近の、他の <import> ステートメントよりも後に次のコード行を追加します。

<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\TextTemplating\v10.0\Microsoft.TextTemplating.targets" />
<PropertyGroup>
   <TransformOnBuild>true</TransformOnBuild>
   <!-- Other properties can be inserted here -->
</PropertyGroup>

詳細については、「ビルド処理でのコード生成」を参照してください。

エラーレポート

エラーメッセージおよび警告メッセージを Visual Studio のエラーウィンドウに表示するには、次のメソッドを使用します。

Error("An error message");
Warning("A warning message");

既存のファイルをテンプレートに変換する

テンプレートには、見た目は生成されるファイルとよく似ていて、そこに、プログラムコードが挿入されているという特徴があります。このことを利用すると、テンプレートを効率的に作成することができます。最初に通常のファイル (Visual C# ファイルなど) をプロトタイプとして作成し、その後、結果のファイルにバリエーションを持たせるための生成コードを徐々に適用していく方法です。

既存のファイルをデザイン時テンプレートに変換するには

.cs、.vb、.resx など、生成する種類のファイルを Visual Studio プロジェクトに追加します。
この新しいファイルをテストして、ファイルが機能することを確認します。
ソリューションエクスプローラーで、ファイル名拡張子を .tt に変更します。
.tt ファイルの次のプロパティを確認します。

カスタムツール =

TextTemplatingFileGenerator

ビルドアクション =

なし
ファイルの先頭に次の行を挿入します。
```
<#@ template debug="false" hostspecific="false" language="C#" #>
<#@ output extension=".cs" #>
```
テンプレートのコード生成機構を Visual Basic で記述する場合は、language 属性を "C#" ではなく、"VB" に設定してください。

extension 属性を、生成するファイルの種類のファイル名拡張子 (.cs、.resx、.xml など) に設定します。
ファイルを保存します。

指定された拡張子の従属ファイルが作成されます。そのプロパティは、ファイルの種類に対応します。たとえば、.cs ファイルの [ビルドアクション] プロパティは [コンパイル] になります。

生成されたファイルのコンテンツが、元のファイルと同じであることを確認します。
ファイルの可変部分を見極めます。たとえば、特定の条件を満たした場合にのみ出力する部分や、繰り返し出力する部分、特定の値をどこで変化させるかなどを決めます。コードを生成するためのコードを挿入します。ファイルを保存し、従属ファイルが正しく生成されたことを確認します。この手順を繰り返します。

コード生成のガイドライン

「T4 テキストテンプレートの記述に関するガイドライン」を参照してください。

次の手順

次の手順	トピック
補助的な関数、インクルードファイル、永続データなどを使用したコードを組み合わせて、より高度なテキストテンプレートを作成し、デバッグする。	T4 テキストテンプレートの作成
実行時にテンプレートからドキュメントを生成する。	前処理された T4 テキストテンプレートを使用した実行時テキスト生成
Visual Studio の外部でテキストの生成を行う。	TextTransform ユーティリティを使用したファイルの生成
ドメイン固有言語の形式でデータを変換する。	ドメイン固有言語からのコード生成
独自のデータソースを変換するためのディレクティブプロセッサを作成する。	T4 テキスト変換のカスタマイズ

参照

その他の技術情報

T4 テキストテンプレートの記述に関するガイドライン

履歴の変更

日付	履歴	理由
2010 年 10 月	VB のサンプルが追加されました。ガイドラインが別のトピックに移動されました。	情報の拡充

2010 年 10 月

VB のサンプルが追加されました。

ガイドラインが別のトピックに移動されました。

情報の拡充

次の方法で共有

T4 テキストテンプレートを使用したデザイン時コード生成

デザイン時 T4 テキストテンプレートを作成する

Visual Studio でデザイン時 T4 テンプレートを作成するには

コードの再生成

可変テキストを生成する

プログラムコードを使用してテキストを生成するには

ソリューションのコードまたはリソースを生成する

プログラムコードまたはリソースを生成するには

生成コードと生成されたテキスト

テキストテンプレートの構成

ファイルなど各種ソースを読み取る

相対パス名を指定してファイルを開く

Visual Studio からデータを取得する

コードを自動的に再生成する

エラーレポート

既存のファイルをテンプレートに変換する

既存のファイルをデザイン時テンプレートに変換するには

コード生成のガイドライン

次の手順

参照

その他の技術情報

履歴の変更

その他のリソース

カスタムツール =	TextTemplatingFileGenerator
ビルドアクション =	なし

次の方法で共有

T4 テキスト テンプレートを使用したデザイン時コード生成

デザイン時 T4 テキスト テンプレートを作成する

Visual Studio でデザイン時 T4 テンプレートを作成するには

コードの再生成

可変テキストを生成する

プログラム コードを使用してテキストを生成するには

ソリューションのコードまたはリソースを生成する

プログラム コードまたはリソースを生成するには

生成コードと生成されたテキスト

テキスト テンプレートの構成

ファイルなど各種ソースを読み取る

相対パス名を指定してファイルを開く

Visual Studio からデータを取得する

コードを自動的に再生成する

エラー レポート

既存のファイルをテンプレートに変換する

既存のファイルをデザイン時テンプレートに変換するには

コード生成のガイドライン

次の手順

参照

その他の技術情報

履歴の変更

その他のリソース

T4 テキストテンプレートを使用したデザイン時コード生成

デザイン時 T4 テキストテンプレートを作成する

プログラムコードを使用してテキストを生成するには

プログラムコードまたはリソースを生成するには

テキストテンプレートの構成

エラーレポート