T4 – direktiva Include

V sadě Visual Studio můžete do textové šablony vložit text z jiného souboru pomocí direktivy <#@include#>.Direktivy include lze do textové šablony umístit kamkoli před první blok funkcí třídy <#+ ... #>.Vkládané soubory mohou rovněž obsahovat direktivy include a jiné direktivy.Díky tomu můžete kód šablony a často používaný text sdílet mezi šablonami.

Použití direktiv include

<#@ include file="filePath" [once="true"] #>

• filePath může být absolutní nebo relativní k aktuálnímu souboru šablony.

  Navíc lze pomocí specifických rozšíření sady Visual Studio určit vlastní adresáře, kde se mají hledat vkládané soubory.Pokud jste například nainstalovali sadu Visualization and Modeling SDK (DSL Tools), přidá se do seznamu vkládaných souborů následující složka: Program Files\Microsoft Visual Studio 10.0\Common7\IDE\Extensions\Microsoft\DSL SDK\DSL Designer\11.0\TextTemplates.

  Tyto další složky vkládaných souborů mohou záviset na příponě vkládaného souboru.Například složka vkládaných souborů nástrojů DSL je přístupná pouze pro vkládání souborů s příponou .tt.

• filePath může obsahovat proměnné prostředí oddělené znakem %.Příklad:

  <#@ include file="%HOMEPATH%\MyIncludeFile.t4" #>
  

• Název vkládaného souboru nemusí mít příponu ".tt".

  Pro vkládané soubory můžete použít jinou příponu, například ".t4".Pokud totiž do projektu přidáte soubor .tt, Visual Studio automaticky nastaví jeho vlastnost Vlastní nástroj na TextTemplatingFileGenerator.Vkládané soubory obvykle nechcete transformovat individuálně.

  Na druhé straně byste měli vědět, že v některých případech přípona souboru ovlivňuje, v jakých dalších složkách se budou hledat vkládané soubory.To může být důležité, pokud máte vkládaný soubor, který obsahuje jiné soubory.

• Vložený obsah se zpracuje téměř jako kdyby byl součástí textové šablony, která ho vkládá.Můžete však vložit soubor obsahující blok funkcí třídy <#+...#>, i když za direktivou include následuje běžný text a standardní řídicí bloky.

• Pomocí hodnoty once="true" zajistěte, aby byla šablona vložena pouze jednou, i když je volána z více než jednoho jiného vkládaného souboru.

  Tato funkce usnadňuje sestavení knihovny opakovaně použitelných fragmentů T4, které můžete vložit bez obav, že již byly vloženy jinými fragmenty kódu. Předpokládejme, že máte knihovnu jemně odstupňovaných fragmentů kódu, které zajišťují zpracování šablon a generování jazyka C#. Ty jsou pro změnu používány některými úlohově orientovanými nástroji, například ke generování výjimek, které pak můžete použít z libovolné aplikačně orientované šablony.Pokud si nakreslíte graf závislostí, uvidíte, že některé fragmenty kódu budou vloženy několikrát.Parametr once ale zabraňuje následným vložením.

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:

   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:

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

Výsledný vygenerovaný soubor 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).

Používání vlastností projektu v nástroji MSBuild a sadě Visual Studio

Ačkoli v direktivě include lze používat makra sady Visual Studio, například $(SolutionDir), v nástroji MSBuild nefungují.Chcete-li transformovat šablony v sestavovacím počítači, je nutné místo toho použít vlastnosti projektu.

Úpravou souboru .csproj nebo .vbproj definujte vlastnost projektu.Tento příklad definuje vlastnost s názvem 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>

Tuto vlastnost projektu nyní můžete použít v textových šablonách, které se správně transformují jak v sadě Visual Studio, tak v nástroji MSBuild:

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