Tvorba textové šablony T4
Textová šablona obsahuje text, který z ní bude vygenerován.Můžete například šablonu, která vytvoří na webové stránce bude obsahovat "< html >..." a všechny ostatní standardní části stránky HTML.Do šablony se vkládají ří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é určují způsob zpracování šablony.
Textové bloky – obsah, který je zkopírován přímo do výstupu.
Řídicí bloky – programový kód, který do textu vloží hodnoty proměnných a řídí podmíněné nebo opakované části textu.
Chcete-li vyzkoušet příklady v tomto tématu, zkopírujte je do souboru šablony podle postupu popsaného v tématu Vytvoření kódu v době návrhu pomocí textových šablon T4.Po úpravě souboru šablony jej uložte a poté 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 – direktivy textových šablon.
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 chcete-li použít jazyk Visual Basic, lze tuto direktivu napsat na začátku souboru:
<#@ 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 vytiskne čtyřikrát „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]
Při vložení textového bloku do složeného příkazu, jako jsou například smyčky nebo podmínky, vždy používejte složené závorky {...} obsahující textový blok.
Ří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 #>
Oznámení, ž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.Obvykle jsou bloky s funkcí třídy umístěny do samostatných souborů tak, aby mohly být zahrnuty ve více než jedné textové šabloně.
Ří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 Řídicí bloky textových šablon.
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" #>
Seznam maker naleznete v tématu Makra pro příkazy a vlastnosti sestavení.
Direktiva assembly nemá žádný účinek na předzpracované textové šablony.
Další informace naleznete v tématu T4 – direktiva Assembly.
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 – direktiva Import.
Vložení 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 – direktiva Include.
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 tématu Pomocné metody textových šablon.
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čtení souboru jako modelu, který lze procházetVý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 Chcete-li vytvořit sadu tříd, se kterými je možné číst XML data.
Úprava souboru modelu ve formuláři nebo diagramu Jazykové nástroje specifické pro doménu poskytuje nástroje, které umožňují upravit model, jako je 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 typově silných tříd, které odrážejí strukturu modelu.Další informace naleznete v tématu Vytváření kódu z jazyka specifického pro doménu.
Použití modelu UMLLze generovat kód z modelu UML.Výhodou je, že model lze upravit jako diagram se známými notacemi.Navíc není nutné diagram navrhovat.Další informace naleznete v tématu Postupy: Generování souborů z modelu UML.
Relativní cesty k souborům v návrhových šablonách
Pokud chcete v návrhových textových šablonách odkazovat na soubor v relativním umístění vzhledem k textu šablony, použijte metodu 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 naleznete v tématu Accessing Visual Studio or other Hosts from a Template.
Návrhové textové šablony běží v oddělené doméně AppDomain.
Je třeba si uvědomit, že návrhová textová šablona běží 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í u návrhových textových šablon obsahujících kód, který je sestaven společně se zbytkem kódu.)
Úpravy šablon
Speciální editory textových šablon lze stáhnout z online galerie správce rozšíření.Na nástroje nabídky, klikněte na tlačítko Správce rozšíření.Klikněte na položku Online galerie a poté použijte nástroj pro hledání.
Související témata
Úloha |
Téma |
|---|---|
Vytvoření šablony |
|
Generování textu pomocí kódu programu |
|
Generování souborů v řešení systému Visual Studio |
|
Spuštění generování textu mimo Visual Studio. |
|
Transformujte data ve formě jazyka specifické pro doménu. |
|
Napište direktivy procesory k transformaci zdroje dat.. |