T4 インクルード ディレクティブT4 Include Directive

<#@include#>ディレクティブにより、Visual Studio でのテキスト テンプレートにおいて、別のファイルからテキストをインクルードすることができます。In a text template in Visual Studio, you can include text from another file by using an <#@include#> directive. include ディレクティブは、テキスト テンプレートに含まれる最初のクラス機能ブロック (<#+ ... #>) の前の任意の場所に配置できます。You can place include directives anywhere in a text template before the first class feature block <#+ ... #>. インクルード ファイルに、include ディレクティブや他のディレクティブを含めることもできます。The included files can also contain include directives, and other directives. これにより、テンプレート間でテンプレート コードや定型句を共有できるようになります。This allows you to share template code and boilerplate text between templates.

include ディレクティブの使用Using Include Directives

<#@ include file="filePath" [once="true"] #>
  • filePath は、絶対パスでも、現在のテンプレートファイルからの相対パスでもかまいません。filePath can be absolute, or relative to the current template file.

    さらに、特定の Visual Studio 拡張機能は、インクルード ファイルを検索する独自のディレクトリを指定することがあります。In addition, specific Visual Studio extensions can specify their own directories to search for include files. たとえば、Visualization and Modeling SDK (DSL) ツールをインストールしたら、次のフォルダーがインクルード一覧に追加されます:Program Files\Microsoft Visual Studio 10.0\Common7\IDE\Extensions\Microsoft\DSL SDK\DSL Designer\11.0\TextTemplatesFor example, when you have installed the Visualization and Modeling SDK (DSL Tools), the following folder is added to the include list: Program Files\Microsoft Visual Studio 10.0\Common7\IDE\Extensions\Microsoft\DSL SDK\DSL Designer\11.0\TextTemplates.

    追加されるこれらのインクルード フォルダーは、インクルード ファイルの拡張子によって異なります。These additional include folders might depend on the file extension of the including file. たとえば、DSL ツールのインクルード フォルダーは、インクルード ファイルの拡張子が .tt の場合にのみ追加されます。For example, the DSL Tools include folder is only accessible to including files that have the file extension .tt

  • filePath には、"%" で区切られた環境変数を含めることもできます。filePath can include environment variables delimited with "%". 例:For example:

    <#@ include file="%HOMEPATH%\MyIncludeFile.t4" #>
    
  • インクルード ファイルの名前に、拡張子 ".tt" を使用する必要はありません。The name of an included file does not have to use the extension ".tt".

    必要に応じて、インクルード ファイルには、".t4" など別の拡張子を使用できます。You might want to use another extension such as ".t4" for included files. これは、.ttファイルをプロジェクトに追加すると、Visual Studio が自動的に、カスタム ツールプロパティをTextTemplatingFileGeneratorに設定するためです。This is because, when you add a .tt file to a project, Visual Studio automatically sets its Custom Tool property to TextTemplatingFileGenerator. 通常、インクルード ファイルを個別に変換することは望ましくありません。You do not usually want included files to be transformed individually.

    一方、ファイルの拡張子によって、インクルード ファイルの検索先となる追加フォルダーが決まる場合があることに注意してください。On the other hand, you should be aware that in some cases, the file extension affects which additional folders will be searched for include files. これは、インクルード ファイルに他のファイルが含まれている場合に重要となります。This might be important when you have an included file that includes other files.

  • インクルードされたコンテンツは、インクルード先のテキスト テンプレートに元から含まれていた場合とほとんど同じように処理されます。The included content is processed almost as if it were part of the including text template. ただし、<#+...#> ディレクティブの後に通常のテキスト ブロックと標準コントロール ブロックが続く場合でも、クラス機能ブロック (include) を含むファイルをインクルードすることができます。However, you can include a file that contains a class feature block <#+...#> even if the include directive is followed by ordinary text and standard control blocks.

  • 1 つ以上のインクルード ファイルが呼び出された場合でも、テンプレートが 1 回だけインクルードされることを確実にするためには、once="true"を使用します。Use once="true" to ensure that a template is included only once, even if it's invoked from more than one other include file.

    この機能により、その他のいくつかのスニペットが既に含まれていることを気にせずに、再利用可能な T4 スニペットのライブラリを構築することが容易になります。This feature makes it easy to build up a library of reusable T4 snippets that you can include at will without worrying that some other snippet has already included them. たとえば、テンプレートを処理し C# コードの生成を処理する非常に短いスニペットのライブラリがあるとします。For example, suppose you have a library of very fine-grained snippets that deal with template processing and C# generation. これらは、例外を生成するなどのタスク固有なユーティリティによって使用され、複数のアプリケーション固有の任意のテンプレートから使用されます。In turn, these are used by some more task-specific utilities such as generating exceptions, which you can then use from any more application-specific template. 依存関係グラフを描画すると、何回もインクルードされるスニペットがあることがわかります。If you draw the dependency graph, you see that some snippets would be included several times. ただし、once パラメーターが指定されると、以降はインクルードが無効になります。But the once parameter prevents the subsequent inclusions.

    MyTextTemplate.tt:MyTextTemplate.tt:

<#@ output extension=".txt" #>
Output message 1 (from top template).
<#@ include file="TextFile1.t4"#>
Output message 5 (from top template).
<#
   GenerateMessage(6); // defined in TextFile1.t4
   AnotherGenerateMessage(7); // defined in TextFile2.t4
#>

TextFile1.t4:TextFile1.t4:

   Output Message 2 (from included file).
<#@ include file="TextFile2.t4" #>
   Output Message 4 (from included file).
<#+ // Start of class feature control block.
void GenerateMessage(int n)
{
#>
   Output Message <#= n #> (from GenerateMessage method).
<#+
}
#>

TextFile2.t4:TextFile2.t4:

        Output Message 3 (from included file 2).
<#+ // Start of class feature control block.
void AnotherGenerateMessage(int n)
{
#>
       Output Message <#= n #> (from AnotherGenerateMessage method).
<#+
}
#>

生成されたファイル:MyTextTemplate.txtThe resulting generated file, MyTextTemplate.txt:

Output message 1 (from top template).
   Output Message 2 (from included file).
        Output Message 3 (from included file 2).

   Output Message 4 (from included file).

Output message 5 (from top template).
   Output Message 6 (from GenerateMessage method).
       Output Message 7 (from AnotherGenerateMessage method).

MSBuild および Visual Studio でのプロジェクト プロパティの使用Using project properties in MSBuild and Visual Studio

include ディレクティブで $ (solutiondir) などの Visual Studio マクロを使用できますが、MSBuild では動作しません。Although you can use Visual Studio macros like $(SolutionDir) in an include directive, they don't work in MSBuild. ビルド コンピューターでテンプレートを変換する場合、代わりにプロジェクトのプロパティを使用する必要があります。If you want to transform templates in your build machine, you have to use project properties instead.

.csproj ファイルまたは .vbproj ファイルを編集してプロジェクトのプロパティを定義します。Edit your .csproj or .vbproj file to define a project property. この例では、myIncludeFolder という名前のプロパティを定義します。This example defines a property named myIncludeFolder:

<!-- Define a project property, myIncludeFolder: -->
<PropertyGroup>
    <myIncludeFolder>$(MSBuildProjectDirectory)\..\libs</myIncludeFolder>
</PropertyGroup>

<!-- Tell the MSBuild T4 task to make the property available: -->
<ItemGroup>
    <T4ParameterValues Include="myIncludeFolder">
      <Value>$(myIncludeFolder)</Value>
    </T4ParameterValues>
  </ItemGroup>

これで、Visual Studio および MSBuild の両方で正しく変換できるテキスト テンプレートでプロジェクトのプロパティを使用できます。Now you can use your project property in text templates, which transform correctly in both Visual Studio and MSBuild:

<#@ include file="$(myIncludeFolder)\defs.tt" #>