Udostępnij za pośrednictwem

Dyrektywa T4 Include

  • Artykuł

W szablonie tekstowym w programie Visual Studio można dołączyć tekst z innego pliku za pomocą dyrektywy <#@include#>.Możesz umieścić dyrektywy include w dowolnym miejscu w szablonie tekstowym przed pierwszym blokiem funkcji klasy <#+ ... #>.Dołączone pliki mogą również zawierać dyrektywy include oraz 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ć ścieżką bezwzględną lub względną do bieżącego pliku szablonu.

    Ponadto, określone rozszerzenia programu Visual Studio mogą określić własne katalogi do wyszukiwania plików dołączanych.Na przykład, jeśli zainstalowano zestaw SDK do wizualizacji i modelowania (narzędzia DSL), następujący folder zostanie dodany do listy dołączania: 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, narzędzia DSL zawierają folder dostępny tylko dla dołączania plików, które mają rozszerzenie .tt.

  • filePath może zawierać zmienne środowiskowe oddzielane za pomocą znaku „%”.Na przykład:

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

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

    Możesz potrzebować innego rozszerzenia, takiego jak ".t4", dla dołączonych plików.To dlatego, że podczas dodawania pliku .tt do projektu, Visual Studio automatycznie ustawia jego właściwość Narzędzie niestandardowe na TextTemplatingFileGenerator.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.Jednakże można dołączyć plik, który zawiera blok funkcji klasy <#+...#>, nawet jeśli po dyrektywie include następuje zwykły tekst i standardowe bloki kontrolne.

  • Użyj once="true", aby zapewnić, że szablon jest uwzględniany tylko raz, nawet jeśli jest wywoływany z więcej niż jednego pliku dołączonego.

    Ta funkcja sprawia, że łatwo jest budować biblioteki wstawek T4 wielokrotnego użytku, które można dołączać swobodnie, bez obawy, że zostały już one dołączone w innych wstawkach. Na przykład załóżmy, że istnieje biblioteka bardzo drobnych wstawek, które zajmują się przetwarzaniem szablonu i generowaniem C#. Z kolei są one używane przez niektóre narzędzia do wykonywania bardziej specyficznych zadań, takich jak generowanie wyjątków, których następnie można używać z szablonów bardziej specyficznych dla aplikacji.Jeśli narysujesz wykres zależności, zobaczysz, że niektóre wstawki kodu programu byłyby dołączone kilka razy.Ale parametr once uniemożliwia późniejsze dołączanie.

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 MSBuild i Visual Studio

Chociaż można używać makr Visual Studio, takich jak $(SolutionDir), w dyrektywie include, nie działają one w 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.Ten przykład definiuje 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" #>