T4 – direktiva Template

Textová šablona T4 sady Visual Studio obvykle začíná direktivou template, která určuje způsob, jakým má být tato šablona zpracována.V textové šabloně a v žádném souboru, který zahrnuje, by neměla existovat více než jedna direktiva šablony.

Obecný přehled o psaní textových šablon lze nalézt v tématu Tvorba textové šablony T4.

Použití direktivy šablony

<#@ template [language="VB"] [compilerOptions="options"] [culture="code"] [debug="true"] [hostspecific="true"] [inherits="templateBaseClass"] [visibility="internal"] [linePragmas="false"] #>

Direktiva template má několik atributů, které umožňují určit různé aspekty transformace.Všechny tyto atributy jsou volitelné.

Atribut compilerOptions

• Příklad:
  compilerOptions="optimize+"

• Platné hodnoty:
  Všechny platné parametry kompilátoru.Další informace najdete v tématech Možnosti kompilátoru C# uvedené podle kategorie a Možnosti kompilátoru jazyka Visual Basic uvedené podle kategorie.

  U šablon běhu (předzpracovaných) se ignoruje.

Tyto parametry platí v případě, že šablona byla převedena na Visual C# nebo Visual Basic a výsledný kód je zkompilován.

Atribut culture

• Příklad:
  culture="de-CH"

• Platné hodnoty:
  "", invariantní jazyková verze, která je výchozí hodnotou.

  Jazyková verze vyjádřená jako řetězec ve formátu xx-XX.Příklad: en US, ja-JP, de-CH, de-DE.Další informace naleznete v tématu CultureInfo.

Atribut culture určuje jazykovou verzi použitou při převedení bloku výrazu na text.

Atribut debug

• Příklad:

  debug="true"
  

• Platné hodnoty:
  true, false.Výchozí hodnota je false.

Pokud atribut debug nabývá hodnoty true, bude soubor mezikódu obsahovat informace, které umožňují ladicímu programu přesněji určit pozici v šabloně, kde došlo k přerušení nebo se vyskytla výjimka.

U šablon návrhu bude soubor mezikódu zapsán do složky %TEMP%.

Pokud chcete šablonu návrhu spustit v ladicím programu, textovou šablonu uložte, poté otevřete místní nabídku textové šablony v Průzkumníku řešení a klikněte na příkaz Ladit šablonu T4.

Atribut hostspecific

• Příklad:

  hostspecific="true"
  

• Platné hodnoty:
  true, false, trueFromBase.Výchozí hodnota je false.

Pokud nastavíte hodnotu tohoto atributu na true, bude do třídy vygenerované textovou šablonou přidána vlastnost s názvem Host.Tato vlastnost je odkazem na hostitelský modul transformace a je deklarována jako ITextTemplatingEngineHost.Pokud jste definovali vlastního hostitele, lze jej přetypovat na typ vlastního hostitele.

Protože typ této vlastnosti závisí na typu hostitele, je užitečný pouze při psaní textové šablony, která funguje pouze s konkrétním hostitelem.Vztahuje se na šablony návrhu, ale ne na šablony běhu.

Pokud má hostspecific hodnotu true a používáte Visual Studio, pak lze pro přístup k funkcím sady Visual Studio přetypovat this.Host na IServiceProvider.K získání absolutní cesty souboru v projektu lze rovněž použít Host.ResolvePath(filename).Příklad:

<#@ template debug="false" hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#@ import namespace="EnvDTE" #>
<#@ import namespace="System.IO" #>
<# // Get the Visual Studio API as a service:
 DTE dte = ((IServiceProvider)this.Host).GetCOMService(typeof(DTE)) as DTE;  
#>
Number of projects in this solution: <#=  dte.Solution.Projects.Count #>

<#
 // Find a path within the current project:
 string myFile = File.ReadAllText(this.Host.ResolvePath("MyFile.txt"));
#>
Content of myFile is:
<#= myFile #>

Použijete-li atribut inherits společně s atributem hostspecific, definujte v odvozené třídě atribut host="trueFromBase" a v základní třídě atribut host="true".To zabraňuje dvojité definici vlastnosti Host ve vygenerovaném kódu.

Atribut language

• Příklad:
  language="VB"

• Platné hodnoty:
  C# (výchozí)

  VB

Atribut language určuje jazyk (Visual Basic nebo Visual C#) použitý pro zdrojový kód v blocích příkazů a výrazů.Soubor mezikódu, ze kterého je výstup vygenerován, bude používat tento jazyk.Tento jazyk nesouvisí s jazykem, který generuje šablona, což může být libovolný typ textu.

Příklad:

<#@ template language="VB" #>
<#@ output extension=".txt" #>
Squares of numbers:
<#
  Dim number As Integer
  For number = 1 To 4
#>
  Square of <#= number #> is <#= number * number #>
<#
  Next number
#>

Atribut inherits

Můžete určit, že programový kód šablony může dědit z jiné třídy, která může být rovněž vygenerována z textové šablony.

Dědičnost v textových šablonách běhu (předzpracovaných)

Dědičnost lze použít mezi textovými šablonami běhu k vytvoření základní šablony, která má několik odvozených variant.Šablony běhu jsou ty, jejichž vlastnost Custom Tool je nastavena na hodnotu TextTemplatingFilePreprocessor.Šablona běhu generuje kód, který lze v aplikaci volat pro vytvoření textu definovaného v šabloně.Další informace naleznete v tématu Generování textu za běhu pomocí textových šablon T4.

Pokud atribut inherits není zadán, jsou základní a odvozená třída vygenerovány z textové šablony.Bude-li atribut inherits zadán, je vygenerována pouze odvozená třída.Základní třídu můžete napsat ručně, ale musí poskytovat metody, které jsou používány odvozenou třídou.

Obvykleji se jako základní třída určuje jiná předzpracovaná šablona.Základní šablona poskytuje běžné bloky textu, které mohou být proloženy textem z odvozených šablon.K definici metod obsahujících textové fragmenty lze použít bloky funkcí tříd <#+ ... #>.Do základní šablony lze například umístit rámec výstupního textu a poskytnout tak virtuální metody, které lze v odvozených třídách přepsat:

• Textová šablona běhu (předzpracovaná) BaseTemplate.tt:

  This is the common header.
  <# 
    SpecificFragment1(); 
  #>
  A common central text.
  <# 
    SpecificFragment2(); 
  #>
  This is the common footer.
  <#+ 
    // Declare abstract methods
    protected virtual void SpecificFragment1() { }
    protected virtual void SpecificFragment2() { }
  #>
  

• Textová šablona běhu (předzpracovaná) DerivedTemplate1.tt:

  <#@ template language="C#" inherits="BaseTemplate" #>
  <# 
    // Run the base template:
    base.TransformText();
  #>
  <#+
  // Provide fragments specific to this derived template:
  protected override void SpecificFragment1()
  {
  #>
     Fragment 1 for DerivedTemplate1
  <#+
  }
  protected override void SpecificFragment2()
  {
  #>
     Fragment 2 for DerivedTemplate1
  <#+
  }
  #>
  

• Kód aplikace pro vyvolání DerivedTemplate1:

  Console.WriteLine(new DerivedTemplate().TransformText());
  

• Výsledný výstup:

  This is the common header.
     Fragment 1 for DerivedTemplate1
  A common central text.
     Fragment 2 for DerivedTemplate1
  This is the common footer.
  

Základní a odvozené třídy lze sestavit v různých projektech.Nezapomeňte k odkazům odvozených projektů přidat základní projekt nebo sestavení.

Jako základní třídu lze také použít běžnou ručně psanou třídu.Základní třída musí poskytovat metody používané v odvozené třídě.

Upozornění
Použijete-li atribut inherits společně s atributem hostspecific, definujte v odvozené třídě atribut hostspecific="trueFromBase" a v základní třídě atribut host="true".To zabraňuje dvojité definici vlastnosti Host ve vygenerovaném kódu.

Dědičnost v textové šabloně návrhu

Textová šablona návrhu je soubor, jehož vlastnost Custom Tool je nastavena na hodnotu TextTemplatingFileGenerator.Tato šablona vygeneruje výstupní soubor kódu nebo textu, který tvoří součást projektu Visual Studio.Při vygenerování výstupního souboru je šablona nejdříve přeložena do souboru programového mezikódu, který není obvykle vidět.Atribut inherits určuje základní třídu pro tento mezikód.

Pro textovou šablonu návrhu lze zadat libovolnou základní třídu, která je odvozena od TextTransformation.K načtení sestavení nebo projektu, který obsahuje základní třídu, použijte direktivu <#@assembly#>.

Další informace lze nalézt v článku o dědičnosti v textových šablonách na blogu Garetha Jonese.

Atribut LinePragmas

• Příklad:
  linePragmas="false"

• Platné hodnoty:
  true (výchozí)

  false

Nastavení tohoto atributu na hodnotu false odstraní značky, které identifikují čísla řádků ve vygenerovaném kódu.To znamená, že kompilátor nahlásí jakékoli chyby pomocí čísel řádků generovaného kódu. To vám dává další možnosti ladění, protože se můžete rozhodnout pro ladění textové šablony nebo vygenerovaného kódu.

Tento atribut může také pomoci, pokud absolutní názvy souborů v direktivách programu způsobují rušivá sloučení ve správě zdrojového kódu.

Atribut visibility

• Příklad:
  visibility="internal"

• Platné hodnoty:
  public (výchozí)

  internal

V textové šabloně běhu se tímto nastavuje atribut visibility vygenerované třídy.Ve výchozím nastavení je tato třída součástí veřejného rozhraní API kódu, ale nastavením atributu visibility="internal" zajistíte, že pouze váš kód může použít třídu generování textu.