T4 テキスト テンプレートを使用した実行時テキスト生成Run-Time Text Generation with T4 Text Templates

実行時に、Visual Studio ランタイムテキストテンプレートを使用して、アプリケーションにテキスト文字列を生成できます。You can generate text strings in your application at run time by using Visual Studio runtime text templates. アプリケーションを実行するコンピューターに Visual Studio がインストールされている必要はありません。The computer where the application executes does not have to have Visual Studio. ランタイムテンプレートは、コンパイル時にテンプレートによって実行時に実行されるコードが生成されるため、"前処理されたテキストテンプレート" と呼ばれることがあります。Runtime templates are sometimes called "preprocessed text templates" because at compile time, the template generates code that is executed at run time.

各テンプレートは、生成された文字列とプログラムコードのフラグメントに表示されるテキストを組み合わせたものです。Each template is a mixture of the text as it will appear in the generated string, and fragments of program code. プログラムフラグメントでは、文字列の変数部分の値を指定すると共に、条件と反復部分も制御します。The program fragments supply values for the variable parts of the string, and also control conditional and repeated parts.

たとえば、HTML レポートを作成するアプリケーションでは、次のテンプレートを使用できます。For example, the following template could be used in an application that creates an HTML report.

<#@ template language="C#" #>
<html><body>
<h1>Sales for Previous Month</h2>
<table>
    <# for (int i = 1; i <= 10; i++)
       { #>
         <tr><td>Test name <#= i #> </td>
             <td>Test value <#= i * i #> </td> </tr>
    <# } #>
 </table>
This report is Company Confidential.
</body></html>

テンプレートは HTML ページであり、変数部分がプログラムコードに置き換えられていることに注意してください。Notice that the template is an HTML page in which the variable parts have been replaced with program code. このようなページのデザインを開始するには、HTML ページの静的なプロトタイプを作成します。You could begin the design of such a page by writing a static prototype of the HTML page. 次に、テーブルやその他の変数部分を、1つの場合によって異なる内容を生成するプログラムコードに置き換えることができます。You could then replace the table and other variable parts with program code that generates the content that varies from one occasion to the next.

アプリケーションでテンプレートを使用すると、出力の最終的な形式を簡単に確認できるようになります。たとえば、長い一連の write ステートメントのようになります。Using a template in your application makes it is easier to see the final form of the output than you could in, for example, a long series of write statements. 出力形式を変更することは、より簡単で信頼性が高くなります。Making changes to the form of the output is easier and more reliable.

任意のアプリケーションでのランタイムテキストテンプレートの作成Creating a Run-Time Text Template in any Application

実行時テキストテンプレートを作成するにはTo create a run-time text template

  1. ソリューションエクスプローラーのプロジェクトのショートカットメニューで、[ Add > 新しい項目の追加] を選択します。In Solution Explorer, on the shortcut menu of your project, choose Add > New Item.

  2. [新しい項目の追加] ダイアログボックスで、[ランタイムテキストテンプレート] を選択します。In the Add New Item dialog box, select Runtime Text Template. (Visual Basic共通項目 > の表示 [全般]。)(In Visual Basic look under Common Items > General.)

  3. テンプレートファイルの名前を入力します。Type a name for your template file.

    注意

    テンプレートファイル名は、生成されたコードでクラス名として使用されます。The template file name will be used as a class name in the generated code. したがって、スペースや句読点を指定することはできません。Therefore, it should not have spaces or punctuation.

  4. [追加] をクリックします。Choose Add.

    拡張子が .ttの新しいファイルが作成されます。A new file is created that has extension .tt. そのカスタムツールプロパティは、 Texttemplatingfilepreprocessor プロセッサに設定されています。Its Custom Tool property is set to TextTemplatingFilePreprocessor. 次の行が含まれています。It contains the following lines:

    <#@ template language="C#" #>
    <#@ assembly name="System.Core" #>
    <#@ import namespace="System.Linq" #>
    <#@ import namespace="System.Text" #>
    <#@ import namespace="System.Collections.Generic" #>
    

既存のファイルを実行時テンプレートに変換するConverting an Existing File to a Run-Time Template

テンプレートを作成するには、出力の既存の例を変換することをお勧めします。A good way to create a template is to convert an existing example of the output. たとえば、アプリケーションで HTML ファイルを生成する場合は、プレーン HTML ファイルを作成することから始めます。For example, if your application will generate HTML files, you can start by creating a plain HTML file. 正しく動作し、その外観が正しいことを確認します。Make sure that it works correctly and that its appearance is correct. 次に、それを Visual Studio プロジェクトに追加し、テンプレートに変換します。Then include it into your Visual Studio project and convert it to a template.

既存のテキストファイルを実行時テンプレートに変換するにはTo convert an existing text file to a run-time template

  1. ファイルを Visual Studio プロジェクトに含めます。Include the file into your Visual Studio project. ソリューションエクスプローラーのプロジェクトのショートカットメニューで、[ Add > 既存項目の追加] を選択します。In Solution Explorer, on the shortcut menu of the project, choose Add > Existing Item.

  2. ファイルのカスタムツールプロパティをTexttemplatingfilepreprocessor プロセッサに設定します。Set the file's Custom Tools property to TextTemplatingFilePreprocessor. ソリューションエクスプローラーのファイルのショートカットメニューで、[プロパティ] を選択します。In Solution Explorer, on the shortcut menu of the file, choose Properties.

    注意

    プロパティが既に設定されている場合は、Texttemplatingfilepreprocessor ではTextTemplatingFileGeneratorなくtexttemplatingfilepreprocessorであることを確認します。If the property is already set, make sure that it is TextTemplatingFilePreprocessor and not TextTemplatingFileGenerator. これは、既に拡張子が .tt のファイルをインクルードした場合に発生する可能性がありますThis can happen if you include a file that already has the extension .tt.

  3. ファイル名拡張子を .ttに変更します。Change the file name extension to .tt. この手順は省略可能ですが、正しくないエディターでファイルを開くことを避けるのに役立ちます。Although this step is optional, it helps you avoid opening the file in an incorrect editor.

  4. ファイル名のメイン部分から、スペースまたは句読点を削除します。Remove any spaces or punctuation from the main part of the file name. たとえば、"My Web Page.tt" は正しくありませんが、"MyWebPage.tt" は正しいです。For example "My Web Page.tt" would be incorrect, but "MyWebPage.tt" is correct. ファイル名は、生成されたコードでクラス名として使用されます。The file name will be used as a class name in the generated code.

  5. ファイルの先頭に次の行を挿入します。Insert the following line at the beginning of the file. Visual Basic のプロジェクトで作業している場合は、"C#" を "VB" に置き換えます。If you are working in a Visual Basic project, replace "C#" with "VB".

    <#@ template language="C#" #>

ランタイムテンプレートの内容The Content of the Run-Time Template

テンプレートディレクティブTemplate directive

ファイルを作成したときと同じように、テンプレートの最初の行を保持します。Keep the first line of the template as it was when you created the file:

<#@ template language="C#" #>

言語パラメーターは、プロジェクトの言語によって異なります。The language parameter will depend on the language of your project.

プレーンコンテンツPlain content

アプリケーションで生成するテキストが含まれるように .tt ファイルを編集しますEdit the .tt file to contain the text that you want your application to generate. 次に例を示します。For example:

<html><body>
<h1>Sales for January</h2>
<!-- table to be inserted here -->
This report is Company Confidential.
</body></html>

埋め込みプログラムコードEmbedded program code

プログラムコードは、との間に挿入でき <# #> ます。You can insert program code between <# and #>. 次に例を示します。For example:

<table>
    <# for (int i = 1; i <= 10; i++)
       { #>
         <tr><td>Test name <#= i #> </td>
             <td>Test value <#= i * i #> </td> </tr>
    <# } #>
 </table>
<table>
<#
    For i As Integer = 1 To 10
#>
    <tr><td>Test name <#= i #> </td>
      <td>Test value <#= i*i #> </td></tr>
<#
    Next
#>
</table>

との間に式が挿入されることに注意 <# ... #> して <#= ... #> ください。Notice that statements are inserted between <# ... #> and expressions are inserted between <#= ... #>. 詳細については、「 T4 テキストテンプレートの作成」を参照してください。For more information, see Writing a T4 Text Template.

テンプレートの使用Using the Template

テンプレートから作成されたコードThe code built from the template

.Ttファイルを保存すると、関連する .csまたは .vbファイルが生成されます。When you save the .tt file, a subsidiary .cs or .vb file is generated. このファイルをソリューションエクスプローラーで表示するには、[.tt ファイル] ノードを展開しますTo see this file in Solution Explorer, expand the .tt file node. Visual Basic プロジェクトで、最初に [ソリューションエクスプローラー ] ツールバーの [すべてのファイルを表示] を選択します。In a Visual Basic project, first choose Show All Files in the Solution Explorer toolbar.

この場合、関連するファイルには、というメソッドを含む部分クラスが含まれていることに注意 TransformText() してください。Notice that the subsidiary file contains a partial class that contains a method called TransformText(). このメソッドは、アプリケーションから呼び出すことができます。You can call this method from your application.

生成 (実行時にテキストを)Generating text at run time

アプリケーションコードでは、次のような呼び出しを使用して、テンプレートのコンテンツを生成できます。In your application code, you can generate the content of your template using a call like this:

MyWebPage page = new MyWebPage();
String pageContent = page.TransformText();
System.IO.File.WriteAllText("outputPage.html", pageContent);
Dim page = New My.Templates.MyWebPage
Dim pageContent = page.TransformText()
System.IO.File.WriteAllText("outputPage.html", pageContent)

生成されたクラスを特定の名前空間に配置するには、テキストテンプレートファイルの "カスタムツールの名前空間" プロパティを設定します。To place the generated class in a particular namespace, set the Custom Tool Namespace property of the text template file.

ランタイムテキストテンプレートのデバッグDebugging Runtime Text Templates

通常のコードと同じ方法で、ランタイムテキストテンプレートをデバッグおよびテストします。Debug and test runtime text templates in the same way as ordinary code.

テキストテンプレートにブレークポイントを設定できます。You can set a breakpoint in a text template. Visual Studio からデバッグモードでアプリケーションを起動する場合は、通常の方法でコードをステップ実行し、ウォッチ式を評価できます。If you start the application in debugging mode from Visual Studio, you can step through the code and evaluate watch expressions in the usual way.

コンストラクターでパラメーターを渡すPassing parameters in the constructor

通常、テンプレートでは、アプリケーションの他の部分からデータをインポートする必要があります。Usually a template must import some data from other parts of the application. これを簡単にするために、テンプレートによって作成されたコードは部分クラスです。To make this easy, the code built by the template is a partial class. プロジェクト内の別のファイルに、同じクラスの別の部分を作成することができます。You can create another part of the same class in another file in your project. このファイルには、パラメーター、プロパティ、および関数を含むコンストラクターを含めることができます。このコンストラクターには、テンプレートに埋め込まれているコードと、アプリケーションの残りの部分の両方でアクセスできます。That file can include a constructor with parameters, properties and functions that can be accessed both by the code that is embedded in the template, and by the rest of the application.

たとえば、 MyWebPageCode.csという別のファイルを作成できます。For example, you could create a separate file MyWebPageCode.cs:

partial class MyWebPage
{
    private MyData m_data;
    public MyWebPage(MyData data) { this.m_data = data; }}

テンプレートファイルMyWebPage.ttで、次のように記述できます。In your template file MyWebPage.tt, you could write:

<h2>Sales figures</h2>
<table>
<# foreach (MyDataItem item in m_data.Items)
   // m_data is declared in MyWebPageCode.cs
   { #>
      <tr><td> <#= item.Name #> </td>
          <td> <#= item.Value #> </td></tr>
<# } // end of foreach
#>
</table>

アプリケーションでこのテンプレートを使用するには、次のようにします。To use this template in the application:

MyData data = ...;
MyWebPage page = new MyWebPage(data);
String pageContent = page.TransformText();
System.IO.File.WriteAllText("outputPage.html", pageContent);

Visual Basic のコンストラクターパラメーターConstructor parameters in Visual Basic

Visual Basic では、個別のファイルMywebpagecodeに次のものが含まれます。In Visual Basic, the separate file MyWebPageCode.vb contains:

Namespace My.Templates
  Partial Public Class MyWebPage
    Private m_data As MyData
    Public Sub New(ByVal data As MyData)
      m_data = data
    End Sub
  End Class
End Namespace

テンプレートファイルには次のものが含まれます。The template file could contain:

<#@ template language="VB" #>
<html><body>
<h1>Sales for January</h2>
<table>
<#
    For Each item In m_data.Items
#>
    <tr><td>Test name <#= item.Name #> </td>
      <td>Test value <#= item.Value #> </td></tr>
<#
    Next
#>
</table>
This report is Company Confidential.
</body></html>

テンプレートは、コンストラクターでパラメーターを渡すことによって呼び出すことができます。The template can invoked by passing the parameter in the constructor:

Dim data = New My.Templates.MyData
    ' Add data values here ....
Dim page = New My.Templates.MyWebPage(data)
Dim pageContent = page.TransformText()
System.IO.File.WriteAllText("outputPage.html", pageContent)

テンプレートプロパティでデータを渡すPassing data in template properties

テンプレートにデータを渡す別の方法として、部分クラス定義でテンプレートクラスにパブリックプロパティを追加する方法があります。An alternative way of passing data to the template is to add public properties to the template class in a partial class definition. アプリケーションでは、を呼び出す前にプロパティを設定でき TransformText() ます。Your application can set the properties before invoking TransformText().

また、部分定義でテンプレートクラスにフィールドを追加することもできます。You can also add fields to your template class in a partial definition. これにより、テンプレートの連続実行の間でデータを渡すことができます。This enables you to pass data between successive executions of the template.

コードに部分クラスを使用するUse partial classes for code

多くの開発者は、大規模なコード本体をテンプレートに記述することを避けたいと思います。Many developers prefer to avoid writing large bodies of code in templates. 代わりに、テンプレートファイルと同じ名前を持つ部分クラスでメソッドを定義できます。Instead, you can define methods in a partial class that has the same name as the template file. これらのメソッドをテンプレートから呼び出します。Call those methods from the template. このようにして、テンプレートでは、ターゲットの出力文字列がどのように表示されるかがより明確に示されます。In this way, the template shows more clearly what the target output string will look like. 結果の外観に関するディスカッションは、表示されるデータを作成するロジックから分離できます。Discussions about the appearance of the result can be separated from the logic of creating the data that it displays.

アセンブリと参照Assemblies and references

テンプレートコードで .NET またはその他のアセンブリ ( System.Xml.dllなど) を参照する場合は、通常の方法でプロジェクトの参照に追加します。If you want your template code to reference a .NET or other assembly such as System.Xml.dll, add it to your project's References in the usual manner.

ステートメントと同じ方法で名前空間をインポートする場合は、 using ディレクティブを使用してこれを行うことができ import ます。If you want to import a namespace in the same way as a using statement, you can do this with the import directive:

<#@ import namespace="System.Xml" #>

これらのディレクティブは、ディレクティブの直後にあるファイルの先頭に配置する必要があり <#@template ます。These directives must be placed at the beginning of the file, immediately after the <#@template directive.

共有コンテンツShared content

複数のテンプレート間で共有されるテキストがある場合は、それを別のファイルに配置し、表示される各ファイルに含めることができます。If you have text that is shared between several templates, you can place it in a separate file and include it in each file in which it should appear:

<#@include file="CommonHeader.txt" #>

含まれているコンテンツには、プログラムコードとプレーンテキストの任意の組み合わせを含めることができ、他のインクルードディレクティブやその他のディレクティブを含めることができます。The included content can contain any mixture of program code and plain text, and it can contain other include directives and other directives.

Include ディレクティブは、テンプレートファイルまたはインクルードファイルのテキスト内の任意の場所で使用できます。The include directive can be used anywhere within the text of a template file or an included file.

実行時テキストテンプレート間の継承Inheritance between Run-Time Text Templates

基本クラステンプレートを記述することによって、実行時テンプレート間でコンテンツを共有できます。これは抽象クラスです。You can share content between run-time templates by writing a base class template, which can be abstract. inherits <@#template#> 別のランタイムテンプレートクラスを参照するには、ディレクティブのパラメーターを使用します。Use the inherits parameter of the <@#template#> directive to reference another runtime template class.

継承パターン: 基本メソッドのフラグメントInheritance pattern: Fragments in Base Methods

次の例で使用しているパターンでは、次の点に注意してください。In the pattern used in the example that follows, notice the following points:

  • 基底クラスは、 SharedFragments クラス機能ブロック内のメソッドを定義し <#+ ... #> ます。The base class SharedFragments defines methods within class feature blocks <#+ ... #>.

  • 基底クラスには自由テキストは含まれません。The base class contains no free text. 代わりに、すべてのテキストブロックはクラスの機能メソッド内で発生します。Instead, all of its text blocks occur inside the class feature methods.

  • 派生クラスは、で定義されているメソッドを呼び出し SharedFragments ます。The derived class invokes the methods defined in SharedFragments.

  • アプリケーションは TextTransform() 派生クラスのメソッドを呼び出しますが、基底クラスを変換しません SharedFragmentsThe application calls the TextTransform() method of the derived class, but does not transform the base class SharedFragments.

  • 基本クラスと派生クラスは、どちらもランタイムテキストテンプレートです。つまり、カスタムツールプロパティはTexttemplatingfilepreprocessor プロセッサに設定されます。Both the base and derived classes are runtime text templates; that is, the Custom Tool property is set to TextTemplatingFilePreprocessor.

SharedFragments.tt:SharedFragments.tt:

<#@ template language="C#" #>
<#+
protected void SharedText(int n)
{
#>
   Shared Text <#= n #>
<#+
}
// Insert more methods here if required.
#>

MyTextTemplate1.tt:MyTextTemplate1.tt:

<#@ template language="C#" inherits="SharedFragments" #>
begin 1
   <# SharedText(2); #>
end 1

MyProgram.cs:MyProgram.cs:

...
MyTextTemplate1 t1  = new MyTextTemplate1();
string result = t1.TransformText();
Console.WriteLine(result);

結果の出力は次のようになります。The resulting output:

begin 1
    Shared Text 2
end 1

継承パターン: ベース本文のテキストInheritance Pattern: Text in Base Body

この別の方法でテンプレートの継承を使用する場合、テキストの大部分は基本テンプレートで定義されます。In this alternative approach to using template inheritance, the bulk of the text is defined in the base template. 派生テンプレートでは、基本コンテンツに適したデータとテキストフラグメントが提供されます。The derived templates provide data and text fragments that fit into the base content.

AbstractBaseTemplate1.tt:AbstractBaseTemplate1.tt:

<#@ template language="C#" #>

Here is the description for this derived template:
  <#= this.Description #>

Here is the fragment specific to this derived template:
<#
  this.PushIndent("  ");
  SpecificFragment(42);
  this.PopIndent();
#>
End of common template.
<#+
  // State set by derived class before calling TextTransform:
  protected string Description = "";
  // 'abstract' method to be defined in derived classes:
  protected virtual void SpecificFragment(int n) { }
#>

DerivedTemplate1.tt:DerivedTemplate1.tt:

<#@ template language="C#" inherits="AbstractBaseTemplate1" #>
<#
  // Set the base template properties:
  base.Description = "Description for this derived class";

  // Run the base template:
  base.TransformText();

#>
End material for DerivedTemplate1.

<#+
// Provide a fragment specific to this derived template:

protected override void SpecificFragment(int n)
{
#>
   Specific to DerivedTemplate1 : <#= n #>
<#+
}
#>

アプリケーションコード:Application code:

...
DerivedTemplate1 t1 = new DerivedTemplate1();
string result = t1.TransformText();
Console.WriteLine(result);

結果の出力:Resulting output:

Here is the description for this derived template:
  Description for this derived class

Here is the fragment specific to this derived template:
     Specific to DerivedTemplate1 : 42
End of common template.
End material for DerivedTemplate1.

デザイン時テンプレート: テンプレートを使用して、アプリケーションの一部となるコードを生成する場合は、「 T4 テキストテンプレートを使用したデザイン時のコード生成」を参照してください。Design-time templates: If you want to use a template to generate code that becomes part of your application, see Design-Time Code Generation by using T4 Text Templates.

ランタイムテンプレートは、コンパイル時にテンプレートとその内容が決定されるすべてのアプリケーションで使用できます。Run-time templates can be used in any application where the templates and their content are determined at compile time. ただし、実行時に変更されるテンプレートからテキストを生成する Visual Studio 拡張機能を作成する場合は、「 VS 拡張機能でのテキスト変換の呼び出し」を参照してください。But if you want to write a Visual Studio extension that generates text from templates that change at run time, see Invoking Text Transformation in a VS Extension.

関連項目See also