T4 Dyrektywy szablonu

A Visual Studio T4 tekst szablonu rozpoczyna się zwykle z template dyrektywy, która określa sposób przetwarzania szablon.Powinien to być nie więcej niż jedną dyrektywą szablonu w szablonie tekst i wszystkie pliki, które zawiera.

Ogólny przegląd pisanie tekstu szablonów, zobacz Zapisywanie szablonu tekst T4.

Za pomocą dyrektywy szablonu

<#@ template [language="VB"] [compilerOptions="options"] [culture="code"] [debug="true"] [hostspecific="true"] [inherits="templateBaseClass"] [visibility="internal"] [linePragmas="false"] #>

template Dyrektywy ma kilka atrybutów, które pozwalają określić różne aspekty transformacji.Wszystkie atrybuty są opcjonalne.

Atrybut compilerOptions

• Przykład:
  compilerOptions="optimize+"

• Prawidłowe wartości:
  Wszystkie opcje kompilatora prawidłowy.Aby uzyskać więcej informacji, zobacz Opcje kompilatora C# wyświetlane według kategorii i Opcje kompilatora Visual Basic, wymienionych według kategorii.

  Ignorowane dla wykonywania szablonów (wstępnie).

Te opcje są stosowane, gdy szablon został przekształcony w Visual C# lub Visual Basic, i jest skompilowany kod wynikowy.

Atrybut kultury

• Przykład:
  culture="de-CH"

• Prawidłowe wartości:
  "", niezmienna kultura, które jest ustawieniem domyślnym.

  Kultury, wyrażone jako ciąg w postaci xx-XX.Na przykład en US, ja-JP, de-CH, de-DE.Aby uzyskać więcej informacji, zobacz System.Globalization.CultureInfo.

Atrybut kultury określa kulturę podczas bloku wyrażenie jest konwertowana na tekst.

Atrybut debugowania

• Przykład:

  debug="true"
  

• Prawidłowe wartości:
  true, false.Domyślnym jest wartość false.

Jeśli debug atrybut jest true, pośredni kod będzie zawierał informacje, które włącza debuger do identyfikowania dokładniej pozycji w szablonie miejsce wystąpienia przerwy lub wyjątek.

Projektowania szablonów plik pośredni kod zostanie zapisany do katalogu % TEMP %.

Aby uruchomić debugera szablonu projektowania, otwórz menu skrótów tekstu szablonu w oknie Solution Explorer i wybierz polecenie Debugowania szablon T4.

Atrybut hostspecific

• Przykład:

  hostspecific="true"
  

• Prawidłowe wartości:
  true, false, trueFromBase.Domyślnym jest wartość false.

Jeśli wartość tego atrybutu dla true, właściwość o nazwie Host jest dodawana do klasy generowane przez szablon tekstu.Właściwość jest odwołaniem do hosta silnika transformacji i jest zadeklarowana jako Microsoft.VisualStudio.TextTemplating.ITextTemplatingEngineHost.Jeśli zostały zdefiniowane niestandardowe hosta, może to rzutować typu niestandardowego hosta.

Ponieważ typ tej właściwości zależy od typu host, jest tylko przydatne podczas pisania szablon tekst, który działa tylko z określonego hosta.

Gdy hostspecific jest true i za pomocą Visual Studio, można rzutować this.Host do IServiceProvider dostęp do Visual Studio funkcji.Można również użyć Host.ResolvePath(filename) uzyskać ścieżkę bezwzględną pliku projektu.Na przykład:

<#@ template debug="false" hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#@ import namespace="EnvDTE" #>
<#@ import namespace="System.IO" #>
<# // Get the Visual Studio API as a service:
 DTE dte = ((IServiceProvider)this.Host).GetCOMService(typeof(DTE)) as DTE;  
#>
Number of projects in this solution: <#=  dte.Solution.Projects.Count #>

<#
 // Find a path within the current project:
 string myFile = File.ReadAllText(this.Host.ResolvePath("MyFile.txt"));
#>
Content of myFile is:
<#= myFile #>

Jeśli korzystasz z inherits i hostspecific atrybuty wspólnie określić hosta = "trueFromBase" w klasie pochodnej i host = "true" w klasie podstawowej.Pozwala to uniknąć podwójnego definicja Host właściwość w wygenerowanym kodzie.

Atrybut Language

• Przykład:
  language="VB"

• Prawidłowe wartości:
  C#(domyślnie)

  VB

Atrybut language określa język (Visual Basic lub Visual C#) na potrzeby kodu źródłowego w bloki instrukcji i wyrażenie.Pliku kodu pośredniego, z którego jest generowane dane wyjściowe będą używać tego języka.Język ten nie jest powiązany język generuje szablonu, w którym może być dowolny rodzaj tekstu.

Na przykład:

<#@ template language="VB" #>
<#@ output extension=".txt" #>
Squares of numbers:
<#
  Dim number As Integer
  For number = 1 To 4
#>
  Square of <#= number #> is <#= number * number #>
<#
  Next number
#>

dziedziczy atrybut

Można określić, że kod programu szablonu może dziedziczyć z innej klasy, które również mogą być generowane z szablonu.

Dziedziczenie w run-time (wstępnie) szablonu

Można użyć dziedziczenie między szablonami tekst w czasie wykonywania, aby utworzyć podstawowy szablon, który ma kilka wariantów pochodnych.Szablony wykonania są te, które mają Niestandardowego narzędzia właściwość zestaw do TextTemplatingFilePreprocessor.Szablon wykonywania generuje kod, który można zadzwonić w aplikacji, aby utworzyć tekst zdefiniowany w szablonie.Aby uzyskać więcej informacji, zobacz Generowanie tekstu Run-Time z szablonami tekst T4.

Jeśli nie określisz inherits atrybut, klasą i klasy pochodne są generowane na podstawie szablonu tekstu.Po określeniu inherits jest generowany atrybut, tylko w klasie pochodnej.Klasa podstawowa można napisać ręcznie, ale musi przedstawić metody, które są używane w klasie pochodnej.

Więcej zazwyczaj określenia innego szablonu wstępnie jako klasa podstawowa.Podstawowy szablon zawiera typowe bloki tekstu, który może być z przeplotem z tekstu z pochodnych szablony.Można użyć klasy bloki funkcji <#+ ... #> do zdefiniowania metody, które zawierają fragmenty tekstu.Na przykład można umieścić ramach tekstu wyjściowego w szablonie bazowym, zapewniając wirtualny metody, które może być zastąpiona w szablonach pochodnych:

• Szablon Run-time (wstępnie) tekst BaseTemplate.tt:

  This is the common header.
  <# 
    SpecificFragment1(); 
  #>
  A common central text.
  <# 
    SpecificFragment2(); 
  #>
  This is the common footer.
  <#+ 
    // Declare abstract methods
    protected virtual void SpecificFragment1() { }
    protected virtual void SpecificFragment2() { }
  #>
  

• Szablon Run-time (wstępnie) tekst DerivedTemplate1.tt:

  <#@ template language="C#" inherits="BaseTemplate" #>
  <# 
    // Run the base template:
    base.TransformText();
  #>
  <#+
  // Provide fragments specific to this derived template:
  protected override void SpecificFragment1()
  {
  #>
     Fragment 1 for DerivedTemplate1
  <#+
  }
  protected override void SpecificFragment2()
  {
  #>
     Fragment 2 for DerivedTemplate1
  <#+
  }
  #>
  

• Kod aplikacji, aby wywołać DerivedTemplate1:

  Console.WriteLine(new DerivedTemplate().TransformText());
  

• Dane wyjściowe:

  This is the common header.
     Fragment 1 for DerivedTemplate1
  A common central text.
     Fragment 2 for DerivedTemplate1
  This is the common footer.
  

Można utworzyć klasy podstawowej i pochodnych w różnych projektach.Pamiętaj dodać bazowy projektu lub zestawu do odwołania projektu pochodnej.

Umożliwia także zwykłym klasy odręcznie jako klasa podstawowa.Klasy podstawowej należy podać metody stosowane w klasie pochodnej.

Przestroga
Jeśli korzystasz z inherits i hostspecific atrybuty wspólnie określić hostspecific = "trueFromBase" w klasie pochodnej i host = "true" w klasie podstawowej.Pozwala to uniknąć podwójnego definicja Host właściwość w wygenerowanym kodzie.

Dziedziczenie w szablonu projektowania

Szablonu projektowania jest plik, dla którego Niestandardowego narzędzia jest ustawiona na TextTemplatingFileGenerator.W szablonie zostanie wygenerowany plik wyjściowy kodu lub tekstu, która stanowi część swojej Visual Studio projektu.Do generowania pliku wyjściowego, szablonu najpierw jest tłumaczona na pliku kodu pośredniego program, który zwykle nie widać.inherits Atrybut określa klasa podstawowa dla tego kodu pośredniego.

Do projektowania szablonu, można określić klasy podstawowej, pochodzącej z Microsoft.VisualStudio.TextTemplating.TextTransformation.Użycie <#@assembly#> dyrektywy załadować zestawu lub projektu, który zawiera klasy podstawowej.

Aby uzyskać więcej informacji, zobacz "dziedziczenia w tekst szablony" w blogu Gareth Jones.

Atrybut LinePragmas

• Przykład:
  linePragmas="false"

• Prawidłowe wartości:
  true(domyślnie)

  false

Ustawienie tego atrybutu na false powoduje usunięcie znaczników, które identyfikują swoje numery linii w wygenerowanym kodzie.Oznacza to, że kompilator zgłosi błędy za pomocą numerów wierszy wygenerowanego kodu.Daje to więcej opcji debugowania, jak można wybrać do debugowania tekst szablonu lub wygenerowany kod.

Atrybut ten może także pomóc, jeśli masz absolutną nazwy plików w pragmy są przyczyną rozpraszać scalenia kontroli kodu źródłowego.

Atrybut Widoczność

• Przykład:
  visibility="internal"

• Prawidłowe wartości:
  public(domyślnie)

  internal

W szablonie runtime to ustawia atrybut Widoczność wygenerowanej klasy.Domyślnie, klasa jest częścią publicznej API kodu, ale przez ustawienie visibility="internal" można się upewnić, że tylko kodu można użyć klasy generowania tekstu.