Udostępnij za pośrednictwem

Dyrektywa T4 dotycząca szablonu

  • Artykuł

Szablon tekstowy programu Visual Studio T4 zwykle rozpoczyna się od template dyrektywy, która określa sposób przetwarzania szablonu. Powinna istnieć nie więcej niż jedna dyrektywa szablonu w szablonie tekstowym i wszystkich plikach, które on uwzględnia.

Aby zapoznać się z ogólnym omówieniem pisania szablonów tekstu, zobacz Pisanie szablonu tekstowego T4.

Używanie dyrektywy Template

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

Dyrektywa template ma kilka atrybutów, które umożliwiają określenie różnych aspektów transformacji. Wszystkie atrybuty są opcjonalne.

Atrybut compilerOptions

Przykład:

compilerOptions="optimize+"

Prawidłowe wartości:

Wszystkie prawidłowe opcje kompilatora.

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

Te opcje są stosowane, gdy szablon został przekonwertowany na język Visual C# lub Visual Basic, a wynikowy kod jest kompilowany.

Atrybut culture

Przykład:

culture="de-CH"

Prawidłowe wartości:

"", niezmienna kultura, co jest ustawieniem domyślnym.

Kultura jest wyrażona jako ciąg w postaci xx-XX. Na przykład en-US, ja-JP, de-CH, de-DE. W celu uzyskania więcej informacji, zobacz następujący temat: System.Globalization.CultureInfo.

Atrybut culture określa kulturę, jaka ma zostać użyta w przypadku konwersji bloku wyrażenia na tekst.

Atrybut debug

Przykład:

debug="true"

Prawidłowe wartości:

true

false (domyślne)

debug Jeśli atrybut to true, plik kodu pośredniego będzie zawierać informacje, które umożliwiają debugerowi dokładniejsze zidentyfikowanie pozycji w szablonie, w którym wystąpił podział lub wyjątek.

W przypadku szablonów czasu projektowania plik kodu pośredniego zostanie zapisany w katalogu %TEMP%.

Aby uruchomić szablon czasu projektowania w debugerze, zapisz szablon tekstowy, a następnie otwórz menu skrótów szablonu tekstowego w Eksplorator rozwiązań, a następnie wybierz pozycję Debuguj szablon T4.

Atrybut hostspecific

Przykład:

hostspecific="true"

Prawidłowe wartości:

true

false (domyślne)

trueFromBase

Jeśli ustawisz wartość tego atrybutu na true, właściwość o nazwie Host zostanie dodana do klasy wygenerowanej przez szablon tekstowy. Właściwość jest odwołaniem do hosta aparatu przekształcania i jest zadeklarowana jako ITextTemplatingEngineHost. Jeśli został zdefiniowany niestandardowy host, można go rzutować na niestandardowy typ hosta.

Ponieważ typ tej właściwości zależy od typu hosta, jest to przydatne wyłącznie podczas pisania szablonu tekstu, który działa tylko z określonym hostem. Ma zastosowanie do szablonów czasu projektowania, ale nie szablonów czasu wykonywania.

Gdy hostspecific używasz true programu Visual Studio i używasz go, możesz rzutować this.Host do dostawcy IServiceProvider, aby uzyskać dostęp do funkcji programu Visual Studio. Można również użyć Host.ResolvePath(filename) polecenia , aby uzyskać ścieżkę bezwzględną pliku w projekcie. Na przykład:

<#@ template debug="false" hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#@ import namespace="EnvDTE" #>
<#@ import namespace="System.IO" #>
<#@ import namespace="Microsoft.VisualStudio.TextTemplating" #>
<# // 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 używasz inherits atrybutów i hostspecific razem, określ host="trueFromBase" w klasie pochodnej i host="true" w klasie bazowej. Pozwala to uniknąć podwójnej definicji Host właściwości w wygenerowanym kodzie.

Atrybut language

Przykład:

language="VB"

Prawidłowe wartości:

C# (domyślne)

VB

Atrybut language określa język (Visual Basic lub Visual C#), który ma być używany dla kodu źródłowego w instrukcjach i blokach wyrażeń. Pliku kodu pośredniego, z którego jest generowane wyjście, użyje tego języka. Język ten nie jest powiązany z językiem generowanym przez szablon, który może być dowolnym rodzajem 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
#>

Atrybut inherits

Można określić, aby kod szablonu dziedziczył z innej klasy, która również może być generowana z szablonu tekstu.

Dziedziczenie w szablonie tekstowym czasu wykonywania (wstępnie przetworzonym)

Można użyć dziedziczenia między szablonami tekstowymi czasu wykonywania, aby utworzyć podstawowy szablon, który ma kilka wariantów pochodnych. Szablony czasu wykonywania to szablony, które mają właściwość Custom Tool ustawioną na TextTemplatingFilePreprocessor. Szablon czasu wykonywania generuje kod, który można wywoływać w aplikacji, aby tworzyć tekst zdefiniowany w szablonie. Aby uzyskać więcej informacji, zobacz Generowanie tekstu w czasie wykonywania przy użyciu szablonów tekstu T4.

Jeśli nie określisz atrybutu inherits , klasa bazowa i klasa pochodna zostaną wygenerowane na podstawie szablonu tekstowego. Po określeniu atrybutu inherits zostanie wygenerowana tylko klasa pochodna. Klasa bazowa może być napisana odręcznie, ale musi mieć metody, które są używane w klasie pochodnej.

Zazwyczaj można określić inny wstępnie przetworzony szablon jako klasę bazową. Szablon podstawowy dostarcza wspólne bloki tekstu, które mogą się przeplatać z tekstem z szablonów pochodnych. Bloki <#+ ... #> funkcji klasy umożliwiają definiowanie metod zawierających fragmenty tekstu. Na przykład można umieścić strukturę tekstu wyjściowego w szablonie podstawowym, zapewniającym wirtualne metody, które mogą zostać zastąpione w szablonach pochodnych:

Szablon tekstowy (wstępnie przetworzony) czasu wykonywania 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 tekstowy (wstępnie przetworzony) czasu wykonywania 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 do wywołania 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 podstawowe i pochodne w różnych projektach. Pamiętaj, aby dodać projekt podstawowy lub zestaw do odwołań projektu pochodnego.

Można również użyć zwykłej klasy odręcznej jako klasy bazowej. Klasa bazowa musi dostarczać metody stosowane w klasie pochodnej.

Ostrzeżenie

Jeśli używasz inherits atrybutów i hostspecific razem, określ hostpecific="trueFromBase" w klasie pochodnej i host="true" w klasie bazowej. Pozwala to uniknąć podwójnej definicji Host właściwości w wygenerowanym kodzie.

Dziedziczenie w szablonie tekstowym czasu projektowania

Szablon tekstowy czasu projektowania to plik, dla którego narzędzie niestandardowe ma ustawioną wartość TextTemplatingFileGenerator. Szablon generuje plik wyjściowy kodu lub tekstu, który stanowi część projektu programu Visual Studio. Aby wygenerować plik wyjściowy, szablon najpierw jest tłumaczony na plik kodu programu pośredniego, którego zwykle nie widać. Atrybut inherits określa klasę bazową dla tego kodu pośredniego.

W przypadku szablonu tekstowego czasu projektowania można określić dowolną klasę bazową pochodzącą z Microsoft.VisualStudio.TextTemplating.TextTransformationklasy . Użyj dyrektywy , <#@assembly#> aby załadować zestaw lub projekt zawierający klasę bazową.

Aby uzyskać więcej informacji, zobacz "Dziedziczenie w szablonach tekstowych" w blogu Garetha Jonesa.

linePragmas, atrybut

Przykład:

linePragmas="false"

Prawidłowe wartości:

true (domyślne)

false

Ustawienie tego atrybutu na false powoduje usunięcie znaczników, które identyfikują numery wierszy w wygenerowanym kodzie. Oznacza to, że kompilator będzie zgłaszał błędy, używając numerów wierszy wygenerowanego kodu. Daje to więcej opcji debugowania, ponieważ można wybrać debugowanie szablonu tekstu lub wygenerowanego kodu.

Ten atrybut może również pomóc, jeśli znajdujesz bezwzględne nazwy plików w pragmas powoduje rozpraszanie scalania w ramach kontroli kodu źródłowego.

atrybut widoczności

Przykład:

visibility="internal"

Prawidłowe wartości:

public (domyślne)

internal

W szablonie tekstowym czasu wykonywania, ustawia atrybut widoczności wygenerowanej klasy. Domyślnie klasa jest częścią publicznego interfejsu API kodu, ale ustawiając visibility="internal" ustawienie, możesz upewnić się, że tylko kod może używać klasy generowania tekstu.