T4 – direktiva Template
Textová šablona sady Visual Studio T4 obvykle začíná direktivou template , která určuje způsob zpracování šablony. V textové šabloně a v žádném souboru, který zahrnuje, by neměla existovat více než jedna direktiva šablony.
Obecný přehled psaní textových šablon najdete v tématu Psaní 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.
U šablon běhu (předzpracovaných) se ignoruje.
Tyto možnosti se použijí, když byla šablona převedena na Visual C# nebo Visual Basic a výsledný kód se zkompiluje.
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 najdete na webu System.Globalization.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í)
debug Pokud je trueatribut , soubor zprostředkujícího kódu bude obsahovat informace, které ladicímu programu umožní zjistit přesnější pozici v šabloně, kde došlo k přerušení nebo výjimce.
V případě šablon návrhu se soubor zprostředkujícího kódu zapíše do adresáře %TEMP% .
Pokud chcete v ladicím programu spustit šablonu návrhu, uložte textovou šablonu, otevřete místní nabídku textové šablony v Průzkumník řešení a zvolte Ladit šablonu T4.
Atribut hostspecific
Příklad:
hostspecific="true"
Platné hodnoty:
true
false (výchozí)
trueFromBase
Pokud nastavíte hodnotu tohoto atributu na true, vlastnost pojmenovaná Host se přidá do třídy vygenerované vaší textovou šablonou. Vlastnost je odkaz na hostitele transformačního modulu a je deklarován 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 v době návrhu, ale ne šablony za běhu.
Pokud hostspecific používáte true Sadu Visual Studio, můžete přetypovat this.Host na IServiceProvider pro přístup k funkcím sady Visual Studio. Můžete také použít Host.ResolvePath(filename) k získání absolutní cesty k souboru v projektu. Příklad:
<#@ template debug="false" hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#@ import namespace="EnvDTE" #>
<#@ import namespace="System.IO" #>
<#@ import namespace="Microsoft.VisualStudio.TextTemplating" #>
<# // 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 #>
Pokud společně používáte inherits atributy a hostspecific atributy, zadejte host="trueFromBase" v odvozené třídě a host="true" v základní třídě. Tím se vygenerovanému Host kódu zabrání dvojité definici vlastnosti.
Atribut language
Příklad:
language="VB"
Platné hodnoty:
C# (výchozí)
VB
Atribut language určuje jazyk (Visual Basic nebo Visual C#), který se má použít 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 za běhu jsou šablony, které mají vlastnost Custom Tool nastavenou na TextTemplatingFilePreprocessor. Šablona běhu generuje kód, který lze v aplikaci volat pro vytvoření textu definovaného v šabloně. Další informace najdete v tématu Generování textu za běhu pomocí textových šablon T4.
Pokud nezadáte inherits atribut, základní třída a odvozená třída se vygenerují z textové šablony. Při zadání atributu inherits se vygeneruje 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. Bloky <#+ ... #> funkcí třídy můžete použít k definování metod obsahujících fragmenty textu. 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 přidat základní projekt nebo sestavení do odkazů odvozeného projektu.
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ě.
Upozorňující
Pokud použijete inherits společně atributy a hostspecific atributy, zadejte hostspecific="trueFromBase" v odvozené třídě a host="true" v základní třídě. Tím se vygenerovanému Host kódu zabrání dvojité definici vlastnosti.
Dědičnost v textové šabloně návrhu
Textová šablona návrhu je soubor, pro který je vlastní nástroj nastavený na TextTemplatingFileGenerator. Šablona vygeneruje výstupní soubor kódu nebo textu, který je součástí projektu sady 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 zprostředkující kód.
Pro návrhovou textovou šablonu můžete zadat libovolnou základní třídu odvozenou z Microsoft.VisualStudio.TextTemplating.TextTransformation. Direktivu <#@assembly#> použijte k načtení sestavení nebo projektu, který obsahuje základní třídu.
Další informace naleznete v tématu "Dědičnost v textových šablonách" v Gareth Jones' Blog.
linePragmas – atribut
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é pomoct, pokud hledáte absolutní názvy souborů v pragmas, což způsobuje rušivé sloučení pod správou 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 třída součástí veřejného rozhraní API vašeho kódu, ale nastavením visibility="internal" můžete zajistit, aby text generující třídu používal pouze váš kód.