Wywoływanie przekształcenia tekstu w procesie kompilacji

Przekształcanie tekstu można wywołać w ramach procesu kompilacji rozwiązania programu Visual Studio. Istnieją zadania kompilacji, które są przeznaczone do przekształcania tekstu. Zadania kompilacji T4 uruchamiają szablon tekstowy czasu projektowania, a także kompilują szablony tekstowe czasu wykonywania (wstępnie przetworzone).

Istnieją pewne różnice w czynnościach, które mogą wykonać zadania kompilacji, wszystko zależy od użytego aparatu kompilacji. Podczas tworzenia rozwiązania w programie Visual Studio szablon tekstowy może uzyskać dostęp do interfejsu API programu Visual Studio (EnvDTE), jeśli atrybut hostspecific="true" jest ustawiony. Nie jest to jednak prawdą podczas kompilowanie rozwiązania z poziomu wiersza polecenia lub inicjowania kompilacji serwera za pomocą programu Visual Studio. W tych przypadkach kompilację wykonuje MSBuild i użyty zostaje inny host T4. Oznacza to, że podczas tworzenia szablonu tekstowego przy użyciu programu MSBuild nie można uzyskać dostępu do takich elementów jak nazwy plików projektu. Można jednak przekazać informacje o środowisku do szablonów tekstu i procesorów dyrektywy przy użyciu parametrów kompilacji.

Konfigurowanie maszyn

Aby włączyć zadania kompilacji na komputerze dewelopera, zainstaluj zestaw SDK modelowania dla programu Visual Studio.

Uwaga

Składnik Przekształcanie szablonu tekstu jest automatycznie instalowany w ramach obciążenia programistycznego rozszerzenia programu Visual Studio. Można go również zainstalować na karcie Poszczególne składniki Instalator programu Visual Studio w kategorii Zestawy SDK, biblioteki i struktury. Zainstaluj składnik Zestawu SDK modelowania na karcie Poszczególne składniki.

Jeśli serwer kompilacji działa na komputerze, na którym nie zainstalowano programu Visual Studio, skopiuj następujące pliki na komputer kompilacji z komputera dewelopera:

• %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VisualStudio\v16.0\TextTemplating

  • Microsoft.VisualStudio.TextTemplating.Sdk.Host.15.0.dll
  • Microsoft.TextTemplating.Build.Tasks.dll
  • Microsoft.TextTemplating.targets

• %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Community\VSSDK\VisualStudioIntegration\Common\Assemblies\v4.0

  • Microsoft.VisualStudio.TextTemplating.15.0.dll
  • Microsoft.VisualStudio.TextTemplating.Interfaces.15.0.dll
  • Microsoft.VisualStudio.TextTemplating.VSHost.15.0.dll

• %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Community\Common7\IDE\PublicAssemblies

  • Microsoft.VisualStudio.TextTemplating.Modeling.15.0.dll

Napiwek

Jeśli otrzymasz MissingMethodException element dla metody Microsoft.CodeAnalysis podczas uruchamiania obiektów docelowych kompilacji TextTemplating na serwerze kompilacji, upewnij się, że zestawy Roslyn znajdują się w katalogu o nazwie Roslyn , który znajduje się w tym samym katalogu co plik wykonywalny kompilacji (na przykład msbuild.exe).

Edytowanie pliku projektu

Edytuj plik projektu, aby skonfigurować niektóre funkcje w programie MSBuild, na przykład importując cele przekształcania tekstu.

W Eksplorator rozwiązań wybierz pozycję Zwolnij z menu prawym przyciskiem myszy projektu. Pozwala to na edycję pliku .csproj lub .vbproj w edytorze XML. Po zakończeniu edycji wybierz pozycję Załaduj ponownie.

Importowanie elementów docelowych przekształcania tekstu

W pliku vbproj lub csproj znajdź ostatni Import Project wiersz.

Po tym wierszu, jeśli istnieje, wstaw import szablonu tekstowego:

<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets" />

Przekształcanie szablonów w kompilacji

Istnieje kilka właściwości, które można wstawić do pliku projektu, aby móc kontrolować zadanie przekształcenia:

• Należy uruchomić zadanie przekształceń na początku każdej kompilacji:

  <PropertyGroup>
      <TransformOnBuild>true</TransformOnBuild>
  </PropertyGroup>
  

• Zastąp pliki tylko do odczytu, na przykład dlatego, że nie są wyewidencjonowane:

  <PropertyGroup>
      <OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>
  </PropertyGroup>
  

• Za każdym razem przekształcaj każdy szablon:

  <PropertyGroup>
      <TransformOutOfDateOnly>false</TransformOutOfDateOnly>
  </PropertyGroup>
  

  Domyślnie zadanie T4 MSBuild ponownie generuje plik wyjściowy, jeśli jest starszy niż:

  • jego plik szablonu
  • wszystkie dołączone pliki
  • wszystkie pliki, które zostały wcześniej odczytane przez szablon lub przez procesor dyrektywy, którego używa

  Jest to bardziej zaawansowany test zależności niż jest używany przez polecenie Przekształć wszystkie szablony w programie Visual Studio, które porównuje tylko daty szablonu i pliku wyjściowego.

Aby wykonać tylko przekształcenia tekstu w projekcie, należy wywołać zadanie TransformAll:

msbuild myProject.csproj /t:TransformAll

Aby przekształcić określony szablon tekstowy:

msbuild myProject.csproj /t:Transform /p:TransformFile="Template1.tt"

Można używać symboli wieloznacznych w TransformFile:

msbuild dsl.csproj /t:Transform /p:TransformFile="GeneratedCode\**\*.tt"

Kontrola źródła

Nie ma żadnych szczególnych wbudowanych funkcji integracji z systemem kontroli źródła. Możesz jednak dodać własne rozszerzenia, na przykład, aby wyewidencjonować i zaewidencjonować wygenerowany plik. Domyślnie zadanie przekształcania tekstu unika zastępowania pliku oznaczonego jako tylko do odczytu. Po napotkaniu takiego pliku na liście błędów programu Visual Studio jest rejestrowany błąd i zadanie kończy się niepowodzeniem.

Aby określić, że pliki tylko do odczytu powinny być zastąpione, wstaw tę właściwość:

<OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>

O ile nie dostosujesz kroku przetwarzania po przetworzeniu, ostrzeżenie zostanie zarejestrowane na liście błędów, gdy plik zostanie zastąpiony.

Dostosowywanie procesu kompilacji

Transformacja tekstu ma miejsce przed innymi zadaniami w procesie kompilacji. Zadania wywoływane przed przekształceniem i po nim można zdefiniować, ustawiając właściwości $(BeforeTransform) i $(AfterTransform):

<PropertyGroup>
    <BeforeTransform>CustomPreTransform</BeforeTransform>
    <AfterTransform>CustomPostTransform</AfterTransform>
</PropertyGroup>
<Target Name="CustomPreTransform">
    <Message Text="In CustomPreTransform..." Importance="High" />
</Target>
<Target Name="CustomPostTransform">
    <Message Text="In CustomPostTransform..." Importance="High" />
</Target>

W AfterTransformprogramie można odwoływać się do list plików:

• GeneratedFiles — lista plików zapisanych przez proces. W przypadku tych plików, które zastępują istniejące pliki tylko do odczytu, %(GeneratedFiles.ReadOnlyFileOverwritten) będą prawdziwe. Pliki te można wyewidencjonować z kontroli źródła.

• NonGeneratedFiles — lista plików tylko do odczytu, które nie zostały nadpisane.

Na przykład, można zdefiniować zadanie do wyewidencjonowania GeneratedFiles.

OutputFilePath i OutputFileName

Właściwości te są stosowane tylko przez program MSBuild. Nie wpływają one na generowanie kodu w programie Visual Studio. Przekierowują one wygenerowany plik wyjściowy do innego folderu lub pliku. Folder docelowy musi już istnieć.

<ItemGroup>
  <None Include="MyTemplate.tt">
    <Generator>TextTemplatingFileGenerator</Generator>
    <OutputFilePath>MyFolder</OutputFilePath>
    <LastGenOutput>MyTemplate.cs</LastGenOutput>
  </None>
</ItemGroup>

Przydatnym folderem do przekierowania do jest $(IntermediateOutputPath).

Jeśli określisz nazwę pliku wyjściowego, pierwszeństwo ma rozszerzenie określone w dyrektywie wyjściowej w szablonach.

<ItemGroup>
  <None Include="MyTemplate.tt">
    <Generator>TextTemplatingFileGenerator</Generator>
    <OutputFileName>MyOutputFileName.cs</OutputFileName>
    <LastGenOutput>MyTemplate.cs</LastGenOutput>
  </None>
</ItemGroup>

Określenie parametru OutputFileName lub OutputFilePath nie jest zalecane, jeśli przekształcasz również szablony w programie Visual Studio przy użyciu polecenia Przekształć wszystko lub uruchamiasz generator pojedynczego pliku. Będziesz mieć różne ścieżki plików w zależności od sposobu wyzwolenia transformacji. Może to być mylące.

Dodawanie odwołania i dołączanie ścieżek

Host ma domyślny zestaw ścieżek wyszukiwania zestawów, do których odwołują się szablony. Aby dodać do tego zestawu:

<ItemGroup>
    <T4ReferencePath Include="$(VsIdePath)PublicAssemblies\" />
    <!-- Add more T4ReferencePath items here -->
</ItemGroup>

Aby ustawić foldery, w których będą wyszukiwane pliki nagłówkowe, należy dostarczyć listę oddzieloną średnikami. Zwykle dodaje się je do istniejącej listy folderów.

<PropertyGroup>
    <IncludeFolders>
$(IncludeFolders);$(MSBuildProjectDirectory)\Include;AnotherFolder;And\Another</IncludeFolders>
</PropertyGroup>

Przekazywanie danych kontekstu kompilacji do szablonów

Można ustawić wartości parametrów w pliku projektu. Można na przykład przekazać właściwości kompilacji i zmienne środowiskowe:

<ItemGroup>
  <T4ParameterValues Include="ProjectFolder">
    <Value>$(ProjectDir)</Value>
    <Visible>false</Visible>
  </T4ParameterValues>
</ItemGroup>

W szablonie tekstowym ustaw hostspecific dyrektywę szablonu. Użyj dyrektywy parametru, aby uzyskać wartości:

<#@template language="c#" hostspecific="true"#>
<#@ parameter type="System.String" name="ProjectFolder" #>
The project folder is: <#= ProjectFolder #>

W procesorze dyrektywy można wywołać metodę ITextTemplatingEngineHost.ResolveParameterValue:

C#

string value = Host.ResolveParameterValue("-", "-", "parameterName");

VB

Dim value = Host.ResolveParameterValue("-", "-", "parameterName")

Uwaga

ResolveParameterValue pobiera dane tylko T4ParameterValues wtedy, gdy używasz programu MSBuild. Podczas przekształcania szablonu przy użyciu programu Visual Studio parametry mają wartości domyślne.

Używanie właściwości projektu w zestawach i dyrektywach dołączania

Makra programu Visual Studio, takie jak $(SolutionDir), nie działają w programie MSBuild. Zamiast tego można użyć właściwości projektu.

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

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

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

Teraz możesz korzystać ze swojej właściwości projektu w dyrektywach zestawu i dołączania:

<#@ assembly name="$(myLibFolder)\MyLib.dll" #>
<#@ include file="$(myLibFolder)\MyIncludeFile.t4" #>

Te dyrektywy pobierają wartości z T4parameterValues zarówno w hostach MSBuild, jak i Visual Studio.

Pytania i odpowiedzi

Dlaczego chcę przekształcić szablony na serwerze kompilacji? Szablony zostały już przekształcone w programie Visual Studio przed zaewidencjonowane w kodzie.

Jeśli zaktualizujesz dołączony plik lub inny plik odczytany przez szablon, program Visual Studio nie przekształci pliku automatycznie. Przekształcanie szablonów w ramach kompilacji gwarantuje, że wszystko jest aktualne.

Jakie są inne opcje przekształcania szablonów tekstu?

• Narzędzie TextTransform może być używane w skryptach poleceń. W większości przypadków łatwiej jest używać programu MSBuild.

• Wywołaj przekształcenie tekstu w rozszerzeniu programu Visual Studio.

• Szablony tekstu w czasie projektowania są przekształcane przez program Visual Studio.

• Szablony tekstu w czasie wykonywania są przekształcane w czasie wykonywania w aplikacji.

Powiązana zawartość

• W szablonie T4 MSbuild znajdują się dobre wskazówki %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\MSBuild\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets

• Pisanie szablonu tekstowego T4