Share via

Pisanie szablonu tekstowego T4

  • Artykuł

Szablon tekstu zawiera tekst, który zostanie z niego wygenerowany. Na przykład szablon, który tworzy stronę internetową, będzie zawierać tekst "<html>..." i wszystkie pozostałe standardowe części strony HTML. Wstawione do szablonu to bloki sterujące, które są fragmentami 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 kontrolujące sposób przetwarzania szablonu.

  • Bloki tekstowe — zawartość skopiowana bezpośrednio do danych wyjściowych.

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

Aby wypróbować przykłady w tym temacie, skopiuj je do pliku szablonu zgodnie z opisem w temacie Generowanie kodu w czasie projektowania przy użyciu szablonów tekstowych T4. Po edycji pliku szablonu zapisz go, a następnie sprawdź wyjściowy plik 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 na temat dyrektyw, zobacz T4 Dyrektywy 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. Język domyślny to C#, ale aby używać języka Visual Basic, możesz napisać tę 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. Poniższy przykład wyświetla cztery razy tekst "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

W przypadku osadzania bloku tekstowego w instrukcji złożonej, takiej jak pętla lub warunkowa, zawsze używaj nawiasów klamrowych {...}, aby zawierać blok tekstu.

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

Zwróć uwagę, że symbol otwierający 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 funkcji klasy są umieszczane w osobnych plikach, dzięki czemu mogą być dołączane przez więcej niż jeden szablon tekstowy.

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 na temat bloków sterowania, zobacz Bloki kontrolek szablonu tekstu.

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

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

Aby uzyskać więcej informacji, zobacz T4 Assembly Directive (Dyrektywa zestawu T4).

Przestrzenie nazw

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 T4 Import Directive (Dyrektywa importu T4).

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 T4 Include Dyrektywa.

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 narzędzi szablonu tekstowego.

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.

Odczytywanie pliku w szablonie tekstowym. Jest to najprostszy sposób wprowadzenia danych do szablonu:

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

Załaduj plik jako model nawigacji. 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żesz również użyć pliku xsd.exe , aby utworzyć zestaw klas, za pomocą których można odczytywać dane XML.

Edytuj plik modelu na diagramie lub formularzu. Narzędzia językowe specyficzne dla domeny udostępniają 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 specyficzne dla domeny tworzą również zestaw silnie typiowanych klas, które odzwierciedlają strukturę modelu. Aby uzyskać więcej informacji, zobacz Generowanie kodu z języka specyficznego dla domeny.

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

Jeśli chcesz odwołać się do pliku w lokalizacji względem szablonu tekstowego w czasie projektowania, użyj polecenia this.Host.ResolvePath(). Ponadto w dyrektywie hostspecific="true" trzeba ustawić wartość 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 #>

Można również wykorzystywać inne usługi udostępniane przez hosta. Aby uzyskać więcej informacji, zobacz Uzyskiwanie dostępu do programu Visual Studio lub innych hostów z szablonu.

Szablony tekstu czasu projektowania uruchamiane w oddzielnej domenie aplikacji

Należy pamiętać, że szablon tekstowy w czasie projektowania jest uruchamiany w domenie AppDomain, która jest oddzielona 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, który zawiera kod skompilowany wraz z resztą kodu).

Edytowanie szablonów

Z internetowej galerii menedżera rozszerzeń można pobrać wyspecjalizowane edytory szablonów tekstu. W menu Narzędzia kliknij pozycję Menedżer rozszerzeń. Kliknij pozycję Galeria online, a następnie użyj narzędzia wyszukiwania.

Powiązana zawartość