Директива Include T4T4 Include Directive

В текстовом шаблоне в Visual Studio, можно включить текст из другого файла с помощью <#@include#> директива.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.

Использование директив IncludeUsing 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 Tools) следующую папку добавляется в список включения: Program Files\Microsoft Visual Studio 10.0\Common7\IDE\Extensions\Microsoft\DSL SDK\DSL Designer\11.0\TextTemplates.For 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 Tools доступна только для включающих файлов с расширением .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.

  • Используйте once="true" чтобы убедиться, что шаблон включен только один раз, даже если он вызывается из нескольких других файлов include.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.txt:The 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 StudioUsing project properties in MSBuild and Visual Studio

Несмотря на то, что в директиве include можно использовать макросы Visual Studio, такие как $ (solutiondir), они не работают в 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" #>