Sdílet prostřednictvím

Vytvoření kódu v době návrhu pomocí textových šablon T4

  • Článek

Textové šablony T4 v době návrhu umožňují vygenerovat kód programu a další soubory v projektu sady Visual Studio. Šablony obvykle napíšete tak, aby se liší kód, který vygenerují podle dat z modelu. Model je soubor nebo databáze obsahující klíčové informace o požadavcích vaší aplikace.

Můžete mít například model, který definuje pracovní postup, a to buď jako tabulku, nebo diagram. Z modelu můžete vygenerovat software, který spouští pracovní postup. Když se požadavky uživatelů změní, je snadné probrat nový pracovní postup s uživateli. Opětovné vygenerování kódu z pracovního postupu je spolehlivější než ruční aktualizace kódu.

Poznámka:

Model je zdroj dat, který popisuje konkrétní aspekt aplikace. Může to být jakýkoliv formulář v libovolném druhu souboru nebo databáze. Nemusí být v žádném konkrétním tvaru, například v modelu UML nebo v jazyce specifickém pro doménu. Typické modely jsou ve formě tabulek nebo souborů XML.

Pravděpodobně už znáte generování kódu. Když v řešení sady Visual Studio definujete prostředky v souboru .resx , automaticky se vygeneruje sada tříd a metod. Soubor prostředků usnadňuje a spolehlivější úpravu prostředků, než kdybyste museli upravovat třídy a metody. Pomocí textových šablon můžete kód vygenerovat stejným způsobem ze zdroje vlastního návrhu.

Textová šablona obsahuje kombinaci textu, který chcete vygenerovat, a programový kód, který generuje proměnné části textu. Programový kód umožňuje opakovat nebo podmíněně vynechat části generovaného textu. Vygenerovaný text může být samotný programový kód, který bude tvořit součást vaší aplikace.

Vytvoření textové šablony T4 v době návrhu

  1. Vytvořte nový projekt sady Visual Studio nebo otevřete existující projekt.

  2. Přidejte do projektu textový soubor šablony a pojmenujte ho s příponou .tt.

    Uděláte to tak, že v Průzkumník řešení v místní nabídce projektu zvolíte Přidat>novou položku. V dialogovém okně Přidat novou položku vyberte v prostředním podokně textovou šablonu .

    Všimněte si, že vlastnost Custom Tool souboru je TextTemplatingFileGenerator.

  3. Otevřete soubor . Bude již obsahovat následující direktivy:

    <#@ template hostspecific="false" language="C#" #>
<#@ output extension=".txt" #>

    Pokud jste přidali šablonu do projektu jazyka Visual Basic, atribut jazyka bude "VB".

  4. Na konec souboru přidejte nějaký text. Příklad:

    Hello, world!

  5. Uložte soubor.

    Může se zobrazit okno s upozorněním zabezpečení, které vás vyzve k potvrzení, že chcete šablonu spustit. Klikněte na OK.

  6. V Průzkumník řešení rozbalte uzel souboru šablony a najdete soubor s příponou .txt. Soubor obsahuje text vygenerovaný ze šablony.

    Poznámka:

    Pokud je projekt projektem jazyka Visual Basic, musíte kliknout na Zobrazit všechny soubory , aby se zobrazil výstupní soubor.

Znovu vygenerujte kód.

Šablona se spustí a vygeneruje soubor podřízené společnosti v některém z následujících případů:

  • Upravte šablonu a pak změňte fokus na jiné okno sady Visual Studio.

  • Uložte šablonu.

  • V nabídce Sestavení klikněte na Transformovat všechny šablony. Tím se transformují všechny šablony v řešení sady Visual Studio.

  • V Průzkumník řešení v místní nabídce libovolného souboru zvolte Spustit vlastní nástroj. Pomocí této metody můžete transformovat vybranou podmnožinu šablon.

Můžete také nastavit projekt sady Visual Studio tak, aby se šablony spouštěly, když se změnily datové soubory, které čtou. Další informace naleznete v tématu Automatické opětovné vygenerování kódu.

Generování textu proměnné

Textové šablony umožňují používat programový kód k různým obsahu vygenerovaného souboru.

  1. Změňte obsah .tt souboru:

    <#@ template hostspecific="false" language="C#" #>
<#@ output extension=".txt" #>
<#int top = 10;

for (int i = 0; i<=top; i++)
{ #>
   The square of <#= i #> is <#= i*i #>
<# } #>

  2. .tt Uložte soubor a znovu zkontrolujte vygenerovaný .txt soubor. Vypíše čtverce čísel od 0 do 10.

    Všimněte si, že příkazy jsou uzavřeny uvnitř <#...#>a jednotlivé výrazy uvnitř <#=...#>. Další informace naleznete v tématu Psaní textové šablony T4.

    Pokud napíšete vygenerující kód v jazyce Visual Basic, direktiva template by měla obsahovat language="VB". "C#" je výchozí možnost.

Ladění textové šablony T4 v době návrhu

Ladění textové šablony:

  • Vložte debug="true" do direktivy template . Příklad:

    <#@ template debug="true" hostspecific="false" language="C#" #>

  • Nastavte v šabloně zarážky stejným způsobem jako u běžného kódu.

  • V místní nabídce souboru textové šablony v Průzkumník řešení zvolte Ladit šablonu T4.

    Šablona se spustí a zastaví na zarážkách. Proměnné můžete zkoumat a procházet kód obvyklým způsobem.

Tip

debug="true" zpřesňuje mapování vygenerovaného kódu na textovou šablonu vložením více direktiv číslování řádků do vygenerovaného kódu. Pokud ho vynecháte, zarážky můžou zastavit spuštění ve špatném stavu.

Klauzuli ale můžete ponechat v direktivě šablony i v případě, že neladíte. To způsobuje pouze velmi malý pokles výkonu.

Generování kódu nebo prostředků pro vaše řešení

V závislosti na modelu můžete generovat programové soubory, které se liší. Model je vstup, jako je databáze, konfigurační soubor, model UML, model DSL nebo jiný zdroj. Obvykle vygenerujete několik programových souborů ze stejného modelu. Abyste toho dosáhli, vytvoříte soubor šablony pro každý vygenerovaný programový soubor a všechny šablony budou číst stejný model.

Generování kódu nebo prostředků programu

  1. Změňte výstupní direktivu tak, aby vygenerovala soubor odpovídajícího typu, například .cs, .vb, .resx nebo .xml.

  2. Vložte kód, který vygeneruje požadovaný kód řešení. Pokud například chcete vygenerovat tři celočíselné deklarace polí ve třídě:

    
<#@ template debug="false" hostspecific="false" language="C#" #>
<#@ output extension=".cs" #>
<# var properties = new string [] {"P1", "P2", "P3"}; #>
// This is generated code:
class MyGeneratedClass {
<# // This code runs in the text template:
  foreach (string propertyName in properties)  { #>
  // Generated code:
  private int <#= propertyName #> = 0;
<# } #>
}

  3. Uložte soubor a zkontrolujte vygenerovaný soubor, který teď obsahuje následující kód:

    class MyGeneratedClass {
  private int P1 = 0;
  private int P2 = 0;
  private int P3 = 0;
}

Generování kódu a vygenerovaného textu

Při generování kódu programu je nejdůležitější vyhnout se matoucímu generování kódu, který se spustí v šabloně, a výsledný vygenerovaný kód, který se stane součástí vašeho řešení. Oba jazyky nemusí být stejné.

Předchozí příklad má dvě verze. V jedné verzi je generování kódu v jazyce C#. V druhé verzi je vygenerující kód jazyka Visual Basic. Ale text vygenerovaný oběma je stejný a je to třída jazyka C#.

Stejným způsobem můžete k vygenerování kódu v libovolném jazyce použít šablonu Visual C#. Vygenerovaný text nemusí být v žádném konkrétním jazyce a nemusí to být kód programu.

Strukturování textových šablon

V rámci osvědčených postupů obvykle kód šablony oddělujeme do dvou částí:

  • Část konfigurace nebo shromažďování dat, která nastavuje hodnoty v proměnných, ale neobsahuje textové bloky. V předchozím příkladu je tato část inicializace properties.

    Tato část se někdy nazývá "model", protože vytváří model v úložišti a obvykle čte soubor modelu.

  • Část generování textu (foreach(...){...} v příkladu), která používá hodnoty proměnných.

    Nejedná se o nezbytné oddělení, ale jde o styl, který usnadňuje čtení šablony snížením složitosti části, která obsahuje text.

Čtení souborů nebo jiných zdrojů

Pro přístup k souboru modelu nebo databázi může kód šablony používat sestavení, jako je System.XML. Chcete-li získat přístup k těmto sestavením, musíte vložit direktivy, jako jsou tyto:

<#@ assembly name="System.Xml.dll" #>
<#@ import namespace="System.Xml" #>
<#@ import namespace="System.IO" #>

Tato direktiva assembly zpřístupní zadané sestavení kódu šablony stejným způsobem jako oddíl Reference projektu sady Visual Studio. Není nutné zahrnout odkaz na System.dll, na který se odkazuje automaticky. Direktiva import umožňuje používat typy bez použití jejich plně kvalifikovaných názvů stejným způsobem jako direktiva using v běžném souboru programu.

Například po importu System.IO můžete napsat:


<# var properties = File.ReadLines("C:\\propertyList.txt");#>
...
<# foreach (string propertyName in properties) { #>
...

Otevření souboru s relativní cestou

Pokud chcete načíst soubor z umístění vzhledem k textové šabloně, můžete použít this.Host.ResolvePath(). Chcete-li použít this.Host, je nutné nastavit hostspecific="true" v :template

<#@ template debug="false" hostspecific="true" language="C#" #>

Pak můžete napsat například:

<# string filename = this.Host.ResolvePath("filename.txt");
  string [] properties = File.ReadLines(filename);
#>
...
<#  foreach (string propertyName in properties { #>
...

Můžete také použít this.Host.TemplateFile, který identifikuje název aktuálního souboru šablony.

Typ this.Host (v VB, Me.Host) je Microsoft.VisualStudio.TextTemplating.ITextTemplatingEngineHost.

Získávání dat ze sady Visual Studio

Pokud chcete používat služby poskytované v sadě Visual Studio, nastavte hostspecific atribut a načtěte EnvDTE sestavení. Import Microsoft.VisualStudio.TextTemplating, který obsahuje rozšiřující metodu GetCOMService() . Pak můžete použít IServiceProvider.GetCOMService() pro přístup k DTE a dalším službám. Příklad:

<#@ template hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#@ import namespace="Microsoft.VisualStudio.TextTemplating" #>
<#
  IServiceProvider serviceProvider = (IServiceProvider)this.Host;
  EnvDTE.DTE dte = (EnvDTE.DTE) serviceProvider.GetCOMService(typeof(EnvDTE.DTE));
#>

Number of projects in this VS solution:  <#= dte.Solution.Projects.Count #>

Tip

Textová šablona běží ve vlastní doméně aplikace a ke službám se přistupuje zařazováním. V tomto případě je GetCOMService() spolehlivější než GetService().

Automatické opětovné vygenerování kódu

V řešení sady Visual Studio se obvykle vygeneruje několik souborů s jedním vstupním modelem. Každý soubor se generuje z vlastní šablony, ale všechny šablony odkazují na stejný model.

Pokud se zdrojový model změní, měli byste znovu spustit všechny šablony v řešení. Chcete-li to provést ručně, zvolte v nabídce Sestavení možnost Transformovat všechny šablony.

Pokud jste nainstalovali sadu Visual Studio Modeling SDK, můžete všechny šablony automaticky transformovat při každém provedení sestavení. Uděláte to tak, že upravíte soubor projektu (.csproj nebo .vbproj) v textovém editoru a za jakékoli další <import> příkazy přidáte následující řádky na konec souboru. V projektu ve stylu sady SDK může přejít kamkoli do souboru projektu.

Poznámka:

Sada SDK pro transformaci textových šablon a sada Visual Studio Modeling SDK se nainstalují automaticky při instalaci konkrétních funkcí sady Visual Studio.

<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets" />
<PropertyGroup>
   <TransformOnBuild>true</TransformOnBuild>
   <!-- Other properties can be inserted here -->
</PropertyGroup>

Další informace najdete v tématu Generování kódu v procesu sestavení.

Zasílání zpráv o chybách

K umístění chybových a upozorňujících zpráv v okně chyby sady Visual Studio můžete použít tyto metody:

Error("An error message");
Warning("A warning message");

Převod existujícího souboru na šablonu

Užitečnou funkcí šablon je, že vypadají velmi podobně jako soubory, které generují, společně s vloženým programovým kódem. To naznačuje užitečnou metodu vytvoření šablony. Nejprve vytvořte běžný soubor jako prototyp, například soubor Visual C#, a pak postupně zaveďte kód generování, který se liší od výsledného souboru.

Převod existujícího souboru na šablonu návrhu

  1. Do projektu sady Visual Studio přidejte soubor typu, který chcete vygenerovat, například .cs, .vbnebo .resx soubor.

  2. Otestujte nový soubor a ujistěte se, že funguje.

  3. V Průzkumník řešení změňte příponu názvu souboru na .tt.

  4. Ověřte následující vlastnosti souboru .tt :

    Vlastnost Nastavení
    Vlastní nástroj = TextTemplatingFileGenerator
    Akce sestavení = Nic

  5. Na začátek souboru vložte následující řádky:

    <#@ template debug="false" hostspecific="false" language="C#" #>
<#@ output extension=".cs" #>

    Pokud chcete napsat vygenerující kód šablony v jazyce Visual Basic, nastavte language atribut namísto "VB""C#".

    extension Nastavte atribut na příponu názvu souboru pro typ souboru, který chcete vygenerovat, například .cs, nebo .resx.xml.

  6. Uložte soubor.

    Vytvoří se podřízený soubor se zadanou příponou. Jeho vlastnosti jsou správné pro typ souboru. Například vlastnost Akce sestavení souboru .cs by byla Kompilace.

    Ověřte, že vygenerovaný soubor obsahuje stejný obsah jako původní soubor.

  7. Určete část souboru, kterou chcete změnit. Například část, která se zobrazuje pouze za určitých podmínek, nebo část, která se opakuje nebo kde se konkrétní hodnoty liší. Vložte vygenerující kód. Uložte soubor a ověřte, že je podřízený soubor správně vygenerován. Tento krok opakujte.

Pokyny pro generování kódu

Přečtěte si pokyny pro psaní textových šablon T4.

Související obsah