Psaní textové šablony T4

Textová šablona obsahuje text, který se z něj vygeneruje. Například šablona, která vytvoří webovou stránku, bude obsahovat "<html>..." a všechny ostatní standardní části stránky HTML. Vložené do šablony jsou řídicí bloky, což jsou fragmenty kódu programu. Řídicí bloky poskytují různé hodnoty a umožňují, aby části textu byly podmíněné a opakované.

Tato struktura usnadňuje vývoj šablon, protože můžete začít prototypem vygenerovaného souboru a postupně vkládat řídicí bloky, které se liší od výsledku.

Textové šablony se skládají z následujících částí:

Direktivy – prvky, které řídí způsob zpracování šablony.
Bloky textu – obsah, který se zkopíruje přímo do výstupu.
Řídicí bloky – programový kód, který vloží hodnoty proměnných do textu, a řídí podmíněné nebo opakované části textu.

Pokud chcete vyzkoušet příklady v tomto tématu, zkopírujte je do souboru šablony, jak je popsáno v Design-Time generování kódu pomocí textových šablon T4. Po úpravě souboru šablony ho uložte a zkontrolujte výstupní .txt soubor.

Direktivy

Direktivy textové šablony poskytují obecné pokyny modulu šablon textu o tom, jak vygenerovat transformační kód a výstupní soubor.

Například následující direktiva určuje, že výstupní soubor by měl mít příponu .txt:

<#@ output extension=".txt" #>

Další informace o direktivách naleznete v tématu T4 Text Template Directives.

Bloky textu

Blok textu vloží text přímo do výstupního souboru. Pro bloky textu neexistuje žádné zvláštní formátování. Například následující textová šablona vytvoří textový soubor, který obsahuje slovo "Hello":

<#@ output extension=".txt" #>
Hello

Řídicí bloky

Řídicí bloky jsou oddíly kódu programu, které slouží k transformaci šablon. Výchozí jazyk je C#, ale pokud chcete použít Visual Basic, můžete na začátek souboru napsat tuto direktivu:

<#@ template language="VB" #>

Jazyk, ve kterém píšete kód v řídicích blocích, nesouvisí s jazykem vygenerovaného textu.

Standardní řídicí bloky

Standardní řídicí blok je část kódu programu, která generuje část výstupního souboru.

V souboru šablony můžete kombinovat libovolný počet textových bloků a standardních řídicích bloků. Nemůžete však umístit jeden řídicí blok do jiného. Každý standardní řídicí blok je oddělen symboly <# ... #>.

Například následující řídicí blok a blok textu způsobí, že výstupní soubor bude obsahovat řádek 0, 1, 2, 3, 4 Hello!:

<#
    for(int i = 0; i < 4; i++)
    {
        Write(i + ", ");
    }
    Write("4");
#> Hello!

Místo použití explicitních Write() příkazů můžete prokládat text a kód. Následující příklad čtyřikrát vytiskne text "Hello!":

<#
    for(int i = 0; i < 4; i++)
    {
#>
Hello!
<#
    }
#>

Blok textu můžete vložit všude tam, kde by byl v kódu povolen příkaz Write();.

Poznámka:

Když vložíte blok textu do složeného příkazu, jako je smyčka nebo podmínka, vždy použijte složené závorky {...} k uzavření bloku textu.

Řídicí bloky výrazů

Blok ovládacího prvku výrazu vyhodnotí výraz a převede ho na řetězec. Vloží se do výstupního souboru.

Řídicí bloky výrazů jsou ohraničené symboly <#= ... #>.

Například následující řídicí blok způsobí, že výstupní soubor bude obsahovat hodnotu 5:

<#= 2 + 3 #>

Všimněte si, že počáteční symbol má tři znaky "<#=".

Výraz může obsahovat libovolnou proměnnou, která je v oboru. Tento blok například vytiskne řádky s čísly:

<#@ output extension=".txt" #>
<#
    for(int i = 0; i < 4; i++)
    {
#>
This is hello number <#= i+1 #>: Hello!
<#
    }
#>

Řídicí bloky funkcí třídy

Řídicí blok funkce třídy definuje vlastnosti, metody nebo jakýkoli jiný kód, který by neměl být zahrnut do hlavní transformace. Bloky funkcí tříd se často používají pro pomocné funkce. Bloky funkcí třídy jsou obvykle umístěny do samostatných souborů, aby je bylo možné zahrnout do více než jedné textové šablony.

Řídicí bloky funkcí třídy jsou oddělené symboly <#+ ... #>.

Například následující soubor šablony deklaruje a používá metodu:

<#@ output extension=".txt" #>
Squares:
<#
    for(int i = 0; i < 4; i++)
    {
#>
    The square of <#= i #> is <#= Square(i+1) #>.
<#
    }
#>
That is the end of the list.
<#+   // Start of class feature block
private int Square(int i)
{
    return i*i;
}
#>

Funkce třídy musí být umístěny na konci souboru, ve kterém jsou zapsány. Můžete ale <#@include#> soubor, který obsahuje vlastnost třídy, i v případě, že include direktiva následuje za standardními bloky a textem.

Další informace o řídicích blocích naleznete v tématu Textové šablony Řídicí bloky.

Bloky funkcí třídy můžou obsahovat textové bloky.

Můžete napsat metodu, která generuje text. Například:

List of Squares:
<#
   for(int i = 0; i < 4; i++)
   {  WriteSquareLine(i); }
#>
End of list.
<#+   // Class feature block
private void WriteSquareLine(int i)
{
#>
   The square of <#= i #> is <#= i*i #>.
<#+
}
#>

Je zvlášť užitečné umístit metodu, která generuje text do samostatného souboru, který může být zahrnut více než jednou šablonou.

Použití externích definic

Assemblies

Bloky kódu vaší šablony mohou používat typy, které jsou definovány v nejčastěji používaných sestaveních .NET, jako je System.dll. Kromě toho můžete odkazovat na jiná sestavení .NET nebo na vlastní sestavení. Můžete zadat cestu k souboru nebo silný název sestavení:

<#@ assembly name="System.Xml" #>

V názvu cesty byste měli použít absolutní názvy cest nebo standardní názvy maker používat přímo v názvu cesty. Například:

<#@ assembly name="$(SolutionDir)library\MyAssembly.dll" #>

Direktiva assembly nemá žádný vliv na předzpracovanou textovou šablonu.

Další informace naleznete v tématu T4 Assembly Directive.

Jmenné prostory

Direktiva importu je stejná jako klauzule using v jazyce C# nebo klauzule imports v jazyce Visual Basic. Umožňuje odkazovat na typy v kódu bez použití plně kvalifikovaného názvu:

<#@ import namespace="System.Xml" #>

Můžete použít libovolný počet assembly direktiv a import direktiv. Musíte je umístit před text a řídicí bloky.

Další informace najdete v direktivě T4 Import.

Zahrnutí kódu a textu

Direktiva include vloží text z jiného souboru šablony. Například tato direktiva vloží obsah test.txt.

<#@ include file="c:\test.txt" #>

Zahrnutý obsah se zpracovává téměř jako kdyby byl součástí textové šablony. Můžete však zahrnout soubor, který obsahuje blok funkce třídy <#+...#>, i když následuje za direktivou include běžný text a standardní řídicí bloky.

Další informace naleznete v tématu T4 Include – direktiva.

Pomocné metody

V řídicím bloku máte k dispozici několik metod, například Write(), které jsou vždy dostupné. Obsahují metody, které vám pomohou při odsazení výstupu a hlášení chyb.

Můžete také napsat vlastní sadu pomocných metod.

Další informace naleznete v části Metody nástroje Textové šablony.

Transformace dat a modelů

Nejužitečnější aplikací textové šablony je generovat materiál na základě obsahu zdroje, jako je model, databáze nebo datový soubor. Šablona extrahuje a přeformátuje data. Kolekce šablon může takový zdroj transformovat na více souborů.

Ke čtení zdrojového souboru existuje několik přístupů.

Čtení souboru v textové šabloně Toto je nejjednodušší způsob, jak získat data do šablony:

<#@ import namespace="System.IO" #>
<# string fileContent = File.ReadAllText(@"C:\myData.txt"); ...

Načtěte soubor jako navigovatelný model. Výkonnější metodou je číst data jako model, v němž může kód textové šablony navigovat. Můžete například načíst soubor XML a procházet ho pomocí výrazů XPath. Můžete také použít xsd.exe k vytvoření sady tříd, pomocí kterých můžete číst data XML.

Upravte soubor modelu v diagramu nebo formuláři. Domain-Specific Jazykové nástroje poskytují nástroje, které umožňují upravit model jako diagram nebo formulář Windows. To usnadňuje diskuzi o modelu s uživateli vygenerované aplikace. Nástroje pro doménově specifické jazyky také vytvoří sadu silně typovaných tříd, které odrážejí strukturu modelu. Další informace naleznete v tématu Generování kódu z jazyka Domain-Specific.

Relativní cesty k souborům v šablonách během návrhu

V šabloně textu v době návrhu, pokud chcete odkazovat na soubor v umístění vzhledem k textové šabloně, použijte this.Host.ResolvePath(). Musíte také nastavit hostspecific="true" v direktivě template :

<#@ template hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ import namespace="System.IO" #>
<#
 // Find a path within the same project as the text template:
 string myFile = File.ReadAllText(this.Host.ResolvePath("MyFile.txt"));
#>
Content of MyFile.txt is:
<#= myFile #>

Můžete také získat další služby, které poskytuje hostitel. Další informace naleznete v části Přístup k aplikaci Visual Studio nebo k jiným hostitelům ze šablony.

Textové šablony v době návrhu se spouštějí v samostatné doméně AppDomain.

Měli byste vědět, že textová šablona návrhu se spouští v doméně AppDomain, která je oddělená od hlavní aplikace. Ve většině případů to není důležité, ale v některých složitých případech můžete zjistit omezení. Pokud například chcete předávat data ze samostatné služby nebo z této šablony, musí služba poskytovat serializovatelné rozhraní API.

(To neplatí pro textovou šablonu za běhu, která poskytuje kód zkompilovaný společně se zbytkem kódu.)

Úpravy šablon

Specializované editory textových šablon lze stáhnout z online galerie Správce rozšíření. V nabídce Nástroje klikněte na Správce rozšíření. Klikněte na Online galerii a pak použijte vyhledávací nástroj.

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-10-31