Sdílet prostřednictvím

Tvorba textové šablony T4

  • Článek

Textová šablona obsahuje text, který z ní bude vygenerován. 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 lze začít s prototypem generovaného souboru a postupně vkládat řídicí bloky, které změní výsledek.

Textové šablony se skládají z těchto čá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 ve generování kódu v době návrhu pomocí textových šablon T4. Po úpravě souboru šablony ho uložte a zkontrolujte výstupní soubor .txt .

Direktivy

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

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

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

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

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 části programového kódu, 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 textu, který je generován.

Standardní řídicí bloky

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

V souboru šablony lze používat libovolný počet textových bloků se standardními řídicími bloky. Nelze však umístit jeden řídicí blok uvnitř jiného. Každý standardní řídicí blok je ohraničen 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!

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

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

Blok textu lze vložit všude, kde je 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íněná smyčka, vždy použijte složené závorky {...} k zahrnutí bloku textu.

Řídicí bloky výrazu

Řídicí blok výrazu vyhodnotí výraz a převede jej na řetězec. Ten je vložen do výstupního souboru.

Řídicí bloky výrazu jsou odděleny symboly <#= ... #>.

Například následující řídicí blok způsobí, že výstupní soubor obsahuje text „5“:

<#= 2 + 3 #>

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

Výraz může obsahovat jakoukoli proměnnou, která je v rozsahu. 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 s funkcí třídy

Řídicí blok s funkcí třídy definuje vlastnosti, metody nebo jiný kód, který by neměl být zařazen do hlavní transformace. Bloky s funkcí třídy jsou často používány 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 s funkcí třídy jsou ohraničeny pomocí symbolů <#+ ... #>.

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. Lze však provést <#@include#> souboru, který obsahuje funkce třídy, i když je direktiva include následována standardními bloky a textem.

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

Bloky s funkcí třídy mohou obsahovat textové bloky.

Lze zapsat metodu, která generuje text. Pří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 #>.
<#+
}
#>

Metodu, která generuje text, je vhodné umístit do samostatného souboru, který může obsahovat více než jedna šablona.

Použití externích definic

Sestavení

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

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

Měli byste používat absolutní názvy cest nebo v názvu cesty použít standardní názvy maker. Pří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 Direktiva.

Obory názvů

Direktiva import 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 tolik direktiv assembly a import, kolik chcete. Je nutné je umístit před textové a řídicí bloky.

Další informace naleznete v tématu T4 Import Direktiva.

Zahrnutí kódu a textu

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

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

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 s funkcí třídy <#+...#>, i když za direktivou include následuje běžný text a standardní řídicí bloky.

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

Pomocné metody

Existuje několik metod, jako je Write(), které jsou v řídicím bloku vždy k dispozici. Patří sem metody, které napomáhají odsadit výstup a oznamovat chyby.

Lze 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ším použitím textových šablon je generování materiálu na základě obsahu zdroje, jako je model, databáze nebo datový soubor. Šablona extrahuje a přeformátuje data. Pomocí sady šablon lze tyto zdroje transformovat do více souborů.

Existuje několik způsobů čtení zdrojového souboru.

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

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

Načtěte soubor jako model navigace. Výkonnější metodou je načíst data jako model, kterým kód textové šablony může procházet. Lze například načíst soubor XML a procházet jím 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. Jazykové nástroje specifické pro doménu poskytují nástroje, které umožňují upravit model jako diagram nebo formulář Systému Windows. Můžete tak tento model snáze prodiskutovat s uživateli generované aplikace. Jazykové nástroje specifické pro doménu také vytvoří sadu tříd silného typu, které odrážejí strukturu modelu. Další informace naleznete v tématu Generování kódu z jazyka specifického pro doménu.

Relativní cesty k souborům v návrhových šablonách

Pokud chcete odkazovat na soubor v umístění vzhledem k textové šabloně v době návrhu, použijte this.Host.ResolvePath(). Je také nutné nastavit hodnotu 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 #>

Lze také získat další služby, které jsou poskytovány tímto hostitelem. Další informace najdete v tématu Přístup k sadě Visual Studio nebo jiným hostitelům ze šablony.

Návrhové textové šablony běží v oddělené 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 lze narazit na omezení. Pokud například chcete předat data do nebo ze šablony ze samostatné služby, musí tato 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

Speciální 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.

Související obsah