Pisanie szablonu tekstowego T4

Szablon tekstu zawiera tekst, który zostanie z niego wygenerowany.Na przykład szablon, który tworzy strony sieci web będzie zawierał "< html >..." i wszystkich innych standardowych części strony HTML.Do szablonu są wstawione bloki sterujące, które stanowią fragmenty kodu programu.Bloki sterujące zawierają zmienne wartości i umożliwiają warunkowość oraz powtarzalność części tekstu.

Ta struktura ułatwia tworzenie szablonu, ponieważ można zacząć od prototypu wygenerowanego pliku, po czym stopniowo wstawiać bloki sterujące, które różnicują wynik.

Szablony tekstu składają się z następujących elementów:

• Dyrektywy — elementy, które określają sposób przetwarzania w szablonie.

• Bloki tekstu — zawartość kopiowana bezpośrednio do danych wyjściowych.

• Bloki sterujące — kod programu, który wstawia zmienne wartości do tekstu oraz kontroluje jego warunkowe lub powtarzające się części.

Aby wypróbować przykłady zamieszczone w tym temacie, skopiuj je do pliku szablonu w sposób opisany w temacie Generowanie kodu czasu projektowania przy użyciu szablonów tekstowych T4.Po zmodyfikowaniu pliku szablonu zapisz go, a następnie sprawdź plik wyjściowy .txt.

Dyrektyw

Dyrektywy szablonów tekstu przekazują do silnika tworzenia szablonów tekstu ogólne instrukcje o sposobach generowania kodu przekształcenia oraz pliku wyjściowego.

Na przykład następująca dyrektywa określa, że plik wyjściowy powinien mieć rozszerzenie .txt:

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

Aby uzyskać więcej informacji dotyczących dyrektyw, zobacz Dyrektywy T4 dotyczące szablonu tekstowego.

Bloki tekstu

Blok tekstu wstawia tekst bezpośrednio do pliku wyjściowego.Nie istnieje żadne specjalne formatowanie bloków tekstu.Na przykład następujący szablon tekstu będzie generował plik tekstowy zawierający wyraz „Hello”:

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

Bloki sterujące

Bloki sterujące to sekcje kodu programu służące do przekształcania szablonów.Domyślnym językiem jest C#. Chcąc używać języka Visual Basic, można napisać następującą dyrektywę na początku pliku:

<#@ template language="VB" #>

Język, w którym jest pisany kod źródłowy bloków sterujących, nie ma związku z językiem generowanego tekstu.

Standardowe bloki sterujące

Standardowy blok sterujący to sekcja kodu programu, która generuje część pliku wyjściowego.

W pliku szablonu można połączyć dowolną liczbę bloków tekstu i standardowych bloków sterujących .Nie można jednak umieścić jednego bloku sterującego w innym.Każdy blok sterujący jest ujęty w symbole <# ... #>.

Na przykład następujące bloki sterujący i tekstu spowodują, że plik wyjściowy będzie zawierał wiersz „0, 1, 2, 3, 4 Hello!”:

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

Zamiast używać jawnych instrukcji Write(), można przeplatać tekst i kod.Kod w przykładzie poniżej spowoduje wyświetlenie czterech napisów „Hello!”:

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

Blok tekstu można wstawić w każdym miejscu kodu, gdzie jest dozwolona instrukcja Write();.

[!UWAGA]

Blok tekstu osadzany wewnątrz instrukcji złożonej, na przykład w pętli lub warunku, zawsze należy ujmować w nawiasy klamrowe {...}.

Bloki sterowania wyrażeniami

Blok sterowania wyrażeniem oblicza wartość wyrażenia i konwertuje ją na ciąg.Powstały ciąg jest wstawiany do pliku wyjściowego.

Bloki sterowania wyrażeniami są ujmowane w symbole <#= ... #>.

Na przykład następujący blok sterujący spowoduje, że plik wyjściowy będzie zawierał cyfrę „5”:

<#= 2 + 3 #>

Powiadomienia, że symbol otwierania ma trzy znaki "< #=".

Wyrażenie może zawierać dowolną zmienną znajdującą się w jego zakresie.Na przykład ten blok spowoduje wyświetlanie wierszy z następującymi liczbami:

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

Bloki sterowania cechami klas

Blok sterowania cechami klasy definiuje właściwości, metody i wszelki inny kod, który nie powinien być objęty głównym przekształceniem.Bloki cech klas są często używane do funkcji pomocników.Zazwyczaj bloki cech klas umieszcza się w osobnych plikach, dzięki czemu mogą być dołączane przez wiele szablonów tekstu.

Bloki sterowania cechami klas są ujęte w symbole <#+ ... #>.

Na przykład następujący plik szablonu deklaruje i wykorzystuje metodę:

<#@ 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;
}
#>

Cechy klas muszą być umieszczone na końcu pliku, w którym są zapisywane.Można jednak dołączyć (<#@include#>) plik, który zawiera cechę klasy, nawet jeśli po dyrektywie include następują standardowe bloki i tekst.

Aby uzyskać więcej informacji dotyczących bloków sterujących, zobacz Bloki formantów szablonów tekstowych.

Bloki cech klas mogą zawierać bloki tekstu

Można napisać metodę, która generuje tekst.Na przykład:

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 #>.
<#+   
}
#>

Szczególnie przydatne jest umieszczenie metody generującej tekst w oddzielnym pliku, który może być dołączony przez więcej niż jeden szablon.

Używanie zewnętrznych definicji

Zestawy

Bloki kodu szablonu mogą wykorzystywać typy zdefiniowane w najczęściej używanych zestawach środowiska .NET, takich jak System.dll.Ponadto mogą się odwoływać do innych zestawów środowiska .NET oraz zestawów utworzonych przez użytkownika.Jako lokalizację zestawu można podać ścieżkę albo silną nazwę:

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

W nazwach ścieżek należy używać ich bezwzględnych nazw lub standardowych nazw makr.Na przykład:

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

Lista makr znajduje się w temacie Makra dla poleceń kompilacji oraz właściwości.

Dyrektywa zestawu nie ma wpływu na wstępnie przetworzony szablon tekstu.

Aby uzyskać więcej informacji, zobacz Dyrektywa T4 dotycząca zestawu.

Namespaces

Dyrektywa „import” działa tak samo jak klauzula using w języku C# lub klauzula imports w języku Visual Basic.Umożliwia odwoływanie się z kodu do typów bez podawania w pełni kwalifikowanej nazwy:

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

Można użyć tylu dyrektyw assembly i import, ilu trzeba.Trzeba je umieścić przed blokami tekstu i sterującymi.

Aby uzyskać więcej informacji, zobacz Dyrektywa T4 dotycząca importowania.

Dołączanie kodu i tekstu

Dyrektywa include wstawia tekst z innego pliku szablonu.Na przykład poniższa dyrektywa spowoduje wstawienie zawartości pliku test.txt.

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

Dołączona zawartość jest przetwarzana prawie tak, jakby była częścią dołączającego szablonu tekstu.Można jednak dołączyć plik, który zawiera blok cech klasy <#+...#>, nawet jeśli po dyrektywie „include” następuje zwykły tekst i standardowe bloki sterujące.

Aby uzyskać więcej informacji, zobacz Dyrektywa T4 Include.

Metody narzędziowe

Istnieją różne metody, np. Write(), które są zawsze dostępne w bloku sterującym.Są wśród nich m.in. metody do stosowania wcięć w danych wyjściowych oraz zgłaszania błędów.

Można także napisać własny zestaw metod narzędziowych.

Aby uzyskać więcej informacji, zobacz Metody korzystania z szablonów tekstowych.

Przekształcanie danych i modeli

Najbardziej przydatnym zastosowaniem szablonu tekstu jest generowanie materiału na podstawie zawartości źródła takiego jak model, baza danych lub plik danych.Szablon wyodrębnia i reformatuje dane.Kolekcja szablonów może przekształcić takie źródło w wiele plików.

Istnieją różne techniki odczytywania pliku źródłowego.

Odczyt pliku w szablonie tekstu.Jest to najprostszy sposób wprowadzenia danych do szablonu:

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

Wczytanie pliku jako modelu z nawigacją.Bardziej zaawansowaną metodą jest odczyt danych jako modelu, po którym może się poruszać kod źródłowy szablonu tekstu.Na przykład można wczytać plik XML i nawigować po nim przy użyciu wyrażeń XPath.Można także użyć xsd.exe można utworzyć zestaw klas, z którymi można odczytać danych XML.

Edycja pliku modelu w diagramie lub formularzu. Pakiet Narzędzia językowe właściwe dla domeny zawiera narzędzia umożliwiające edytowanie modelu jako diagramu lub formularza systemu Windows.Ułatwia to przedyskutowanie modelu z użytkownikami wygenerowanej aplikacji.Narzędzia językowe właściwe dla domeny tworzy również zestaw silnie typizowanych klas, które odzwierciedlają strukturę modelu.Aby uzyskać więcej informacji, zobacz Generowanie kodu z języka specyficznego dla domeny.

Użycie modelu UML.Kod można wygenerować z modelu UML.Rozwiązanie ma tę zaletę, że model można edytować jako diagram w znanej notacji.Ponadto nie trzeba projektować diagramu.Aby uzyskać więcej informacji, zobacz Porady: generowanie plików z modelu UML.

Względne ścieżki plików w szablonach czasu projektowania

Aby w szablonie tekstu czasu projektowania utworzyć odwołanie do pliku w lokalizacji względnej wobec szablonu tekstu, należy użyć metody this.Host.ResolvePath().Ponadto w dyrektywie template trzeba ustawić wartość hostspecific="true":

<#@ 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 #>

Można również wykorzystywać inne usługi udostępniane przez hosta.Aby uzyskać więcej informacji, zobacz Accessing Visual Studio or other Hosts from a Template.

Szablony tekstu czasu projektowania uruchamiane w oddzielnej domenie aplikacji

Należy pamiętać, że szablon tekstu czasu projektowania działa w domenie aplikacji, która jest odseparowana od głównej aplikacji.W większości przypadków nie ma to znaczenia, jednak w pewnych skomplikowanych przypadkach mogą wystąpić ograniczenia.Na przykład aby można było przekazać dane między szablonem a osobną usługą, usługa musi udostępniać interfejs API obsługujący serializację.

Nie dotyczy to szablonu tekstu w czasie wykonywania, ponieważ zawiera on kod kompilowany wraz z resztą kodu.

Edytowanie szablonów

Z internetowej galerii menedżera rozszerzeń można pobrać wyspecjalizowane edytory szablonów tekstu.Na narzędzia menu, kliknij przycisk Menedżera rozszerzeń.Kliknij opcję Galeria w trybie online i użyj narzędzia wyszukiwania.

Tematy pokrewne