Dyrektywa T4 Include

W szablonie tekstowym w programie Visual Studio można dołączyć tekst z innego pliku przy użyciu <#@include#> dyrektywy . Dyrektywy można umieszczać include w dowolnym miejscu w szablonie tekstowym przed blokiem <#+ ... #>funkcji pierwszej klasy . Dołączone pliki mogą również zawierać include dyrektywy i inne dyrektywy. To pozwala na udostępnianie kodu szablonu i standardowych wzorców tekstu szablonu między szablonami.

Używanie dyrektyw Include

<#@ include file="filePath" [once="true"] #>

• filePath może być bezwzględny lub względny względem bieżącego pliku szablonu.

  Ponadto określone rozszerzenia programu Visual Studio mogą określać własne katalogi, aby wyszukiwać pliki dołączane. Na przykład po zainstalowaniu zestawu SDK wizualizacji i modelowania (DSL Tools) do listy dołączania zostanie dodany następujący folder: Program Files\Microsoft Visual Studio 10.0\Common7\IDE\Extensions\Microsoft\DSL SDK\DSL Designer\11.0\TextTemplates.

  Te dodatkowe foldery dołączania mogą zależeć od rozszerzenia dołączanego pliku. Na przykład folder dołączania narzędzi DSL jest dostępny tylko do dołączania plików, które mają rozszerzenie pliku .tt

• filePath może zawierać zmienne środowiskowe rozdzielane ciągiem "%". Na przykład:

  <#@ include file="%HOMEPATH%\MyIncludeFile.t4" #>
  

• Nazwa dołączonego pliku nie musi używać rozszerzenia ".tt".

  Możesz użyć innego rozszerzenia, takiego jak ".t4" w przypadku dołączonych plików. Dzieje się tak dlatego, że po dodaniu .tt pliku do projektu program Visual Studio automatycznie ustawia jego właściwość Custom Tool na TextTemplatingFileGeneratorwartość . Zwykle nie chcesz, żeby dołączone pliki były przekształcane indywidualnie.

  Z drugiej strony należy pamiętać, że w niektórych przypadkach rozszerzenie pliku wpływa na to, w których dodatkowych folderach będą wyszukiwane dołączane pliki. Może to być ważne, gdy masz dołączony plik, który zawiera inne pliki.

• 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 <#+...#> funkcji klasy, nawet jeśli include dyrektywa jest przestrzegana zwykłym tekstem i standardowymi blokami sterowania.

• Użyj once="true" polecenia , aby upewnić się, że szablon jest dołączany tylko raz, nawet jeśli jest wywoływany z więcej niż jednego innego pliku dołączanego.

  Ta funkcja ułatwia tworzenie biblioteki fragmentów kodu T4 wielokrotnego użytku, które można uwzględnić bez obaw, że niektóre inne fragmenty kodu już je uwzględniły. Załóżmy na przykład, że masz bibliotekę bardzo precyzyjnych fragmentów kodu, które zajmują się przetwarzaniem szablonów i generowaniem języka C#. Z kolei są one używane przez niektóre bardziej specyficzne dla zadań narzędzia, takie jak generowanie wyjątków, których można następnie użyć z bardziej specyficznego szablonu aplikacji. Jeśli narysujesz wykres zależności, zobaczysz, że niektóre wstawki kodu programu byłyby dołączone kilka razy. once Jednak parametr uniemożliwia kolejne dołączania.

  MyTextTemplate.tt:

<#@ output extension=".txt" #>
Output message 1 (from top template).
<#@ include file="TextFile1.t4"#>
Output message 5 (from top template).
<#
   GenerateMessage(6); // defined in TextFile1.t4
   AnotherGenerateMessage(7); // defined in TextFile2.t4
#>

TextFile1.t4:

   Output Message 2 (from included file).
<#@ include file="TextFile2.t4" #>
   Output Message 4 (from included file).
<#+ // Start of class feature control block.
void GenerateMessage(int n)
{
#>
   Output Message <#= n #> (from GenerateMessage method).
<#+
}
#>

TextFile2.t4:

        Output Message 3 (from included file 2).
<#+ // Start of class feature control block.
void AnotherGenerateMessage(int n)
{
#>
       Output Message <#= n #> (from AnotherGenerateMessage method).
<#+
}
#>

Wynikowy wygenerowany plik MyTextTemplate.txt:

Output message 1 (from top template).
   Output Message 2 (from included file).
        Output Message 3 (from included file 2).

   Output Message 4 (from included file).

Output message 5 (from top template).
   Output Message 6 (from GenerateMessage method).
       Output Message 7 (from AnotherGenerateMessage method).

Korzystanie z właściwości projektu w programie MSBuild i programie Visual Studio

Chociaż w dyrektywie include można używać makr programu Visual Studio, takich jak $(SolutionDir), nie działają one w programie MSBuild. Aby przekształcić szablony w komputerze kompilacji, musisz użyć właściwości projektu.

Wyedytuj plik .csproj lub .vbproj, aby zdefiniować właściwość projektu. W tym przykładzie zdefiniowano właściwość o nazwie myIncludeFolder:

<!-- Define a project property, myIncludeFolder: -->
<PropertyGroup>
    <myIncludeFolder>$(MSBuildProjectDirectory)\..\libs</myIncludeFolder>
</PropertyGroup>

<!-- Tell the MSBuild T4 task to make the property available: -->
<ItemGroup>
    <T4ParameterValues Include="myIncludeFolder">
      <Value>$(myIncludeFolder)</Value>
    </T4ParameterValues>
  </ItemGroup>

Teraz można używać właściwości projektu w szablonach tekstowych, które są prawidłowo przekształcane w Visual Studio i MSBuild:

<#@ include file="$(myIncludeFolder)\defs.tt" #>