Freigeben über

Aufrufen der Texttransformation im Buildprozess

Die Texttransformation kann als Teil des Buildprozesses einer Visual Studio-Lösung aufgerufen werden. Es gibt Buildaufgaben, die auf die Texttransformation spezialisiert sind. Die T4-Buildaufgaben führen Entwurfstextvorlagen aus und kompilieren auch vorverarbeitete Textvorlagen für die Laufzeit.

Je nachdem, welche Build-Engine Sie verwenden, gibt es einige Unterschiede bei den Aufgaben, die die Build-Tasks ausführen können. Wenn Sie die Projektmappe in Visual Studio erstellen, kann eine Textvorlage auf die Visual Studio-API (EnvDTE) zugreifen, wenn das Attribut "hostspecific="true" festgelegt ist. Das trifft jedoch nicht zu, wenn Sie die Lösung über die Befehlszeile erstellen oder einen Serverbuild über Visual Studio ausführen. In diesen Fällen wird der Build von MSBuild ausgeführt und ein anderer T4-Host verwendet. Dies bedeutet, dass Sie nicht auf Elemente wie Projektdateinamen auf die gleiche Weise zugreifen können, wenn Sie eine Textvorlage mit MSBuild erstellen. Sie können Umgebungsinformationen jedoch mithilfe von Buildparametern an Textvorlagen und Direktivenprozessoren übergeben.

Konfigurieren Ihrer Computer

Um Buildaufgaben auf Ihrem Entwicklungscomputer zu aktivieren, installieren Sie das Modeling SDK für Visual Studio.

Hinweis

Die Textvorlagentransformationskomponente wird automatisch als Teil der Visual Studio-Erweiterungsentwicklungsworkloads installiert. Sie können es auch auf der Registerkarte "Einzelne Komponenten " von Visual Studio Installer unter der Kategorie SDKs, Bibliotheken und Frameworks installieren. Installieren Sie die Modellierungs-SDK-Komponente auf der Registerkarte "Einzelne Komponenten ".

Wenn ihr Buildserver auf einem Computer ausgeführt wird, auf dem Visual Studio nicht installiert ist, kopieren Sie die folgenden Dateien von Ihrem Entwicklungscomputer auf den Buildcomputer:

  • %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

Tipp

Wenn Sie eine MissingMethodException Microsoft.CodeAnalysis-Methode beim Ausführen von TextTemplating-Buildzielen auf einem Buildserver erhalten, stellen Sie sicher, dass sich die Roslyn-Assemblys in einem Verzeichnis mit dem Namen Roslyn befinden, das sich im selben Verzeichnis wie die ausführbare Builddatei befindet (z. B. msbuild.exe).

Bearbeiten der Projektdatei

Bearbeiten Sie Ihre Projektdatei, um einige der Features in MSBuild zu konfigurieren, z. B. das Importieren der Texttransformationsziele.

Wählen Sie im Projektmappen-Explorer im Kontextmenü Ihres Projekts "Entladen" aus. Auf diese Weise können Sie die CSPROJ- oder VBPROJ-Datei im XML-Editor bearbeiten. Wenn Sie die Bearbeitung abgeschlossen haben, wählen Sie "Neu laden" aus.

Importieren der Texttransformationsziele

Suchen Sie in der .vbproj- oder CSPROJ-Datei die letzte Import Project Zeile.

Fügen Sie nach dieser Zeile, sofern vorhanden, den Textvorlage-Import ein.

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

Transformieren von Vorlagen in einem Build

Es gibt einige Eigenschaften, die Sie in die Projektdatei einfügen können, um die Transformationsaufgabe zu steuern:

  • Führen Sie die Transformationsaufgabe am Anfang jedes Builds aus:

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

  • Überschreiben Sie Dateien, die schreibgeschützt sind, z. B. weil sie nicht zur Bearbeitung freigegeben sind.

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

  • Jede Vorlage jedes Mal transformieren:

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

    Standardmäßig generiert die T4 MSBuild-Aufgabe eine Ausgabedatei, wenn sie älter als:

    • die Vorlagendatei
    • alle dateien, die enthalten sind
    • Alle Dateien, die zuvor von der Vorlage gelesen wurden, oder von einem direktiven Prozessor, der von ihr verwendet wird

    Dies ist ein leistungsstärkerer Abhängigkeitstest, als vom Befehl "Alle Vorlagen transformieren" in Visual Studio verwendet wird, der nur die Datumswerte der Vorlage und ausgabedatei vergleicht.

Rufen Sie die TransformAll-Aufgabe auf, um nur die Texttransformationen in Ihrem Projekt auszuführen:

msbuild myProject.csproj /t:TransformAll

So transformieren Sie eine bestimmte Textvorlage:

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

Sie können In TransformFile Wildcards verwenden:

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

Quellcodeverwaltung

Es gibt keine spezifische integrierte Integration in ein Quellcodeverwaltungssystem. Sie können jedoch eigene Erweiterungen hinzufügen, um z. B. eine generierte Datei auszuchecken und einzuchecken. Standardmäßig vermeidet die Texttransformationsaufgabe das Überschreiben einer Datei, die als schreibgeschützt gekennzeichnet ist. Wenn eine solche Datei auftritt, wird ein Fehler in der Visual Studio-Fehlerliste protokolliert, und die Aufgabe schlägt fehl.

Um anzugeben, dass schreibgeschützte Dateien überschrieben werden sollen, fügen Sie diese Eigenschaft ein:

<OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>

Wenn Sie den Schritt nach der Verarbeitung nicht anpassen, wird eine Warnung in der Fehlerliste protokolliert, wenn eine Datei überschrieben wird.

Anpassen des Buildprozesses

Die Texttransformation erfolgt vor anderen Aufgaben im Buildprozess. Sie können Aufgaben definieren, die vor und nach der Transformation aufgerufen werden, indem Sie die Eigenschaften $(BeforeTransform) festlegen und $(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>

In AfterTransform, können Sie auf Listen von Dateien verweisen:

  • GeneratedFiles - eine Liste von Dateien, die vom Prozess geschrieben wurden. Für Dateioperationen, bei denen vorhandene schreibgeschützte Dateien überschrieben werden, wird %(GeneratedFiles.ReadOnlyFileOverwritten) "true" sein. Diese Dateien können aus der Quellcodeverwaltung ausgecheckt werden.

  • NonGeneratedFiles – eine Liste schreibgeschützter Dateien, die nicht überschrieben wurden.

Beispielsweise definieren Sie eine Aufgabe zum Auschecken von GeneratedFiles.

OutputFilePath und OutputFileName

Diese Eigenschaften werden nur von MSBuild verwendet. Sie wirken sich nicht auf die Codegenerierung in Visual Studio aus. Sie leiten die generierte Ausgabedatei an einen anderen Ordner oder eine andere Datei um. Der Zielordner muss bereits vorhanden sein.

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

Ein nützlicher Ordner für die Umleitung ist $(IntermediateOutputPath).

Wenn Sie einen Ausgabedateinamen angeben, hat sie Vorrang vor der erweiterung, die in der Ausgabedirektive in den Vorlagen angegeben ist.

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

Die Angabe eines OutputFileName- oder OutputFilePath-Elements wird nicht empfohlen, wenn Sie auch Vorlagen in Visual Studio mithilfe von Transform All transformieren oder den einzelnen Dateigenerator ausführen. Je nachdem, wie Sie die Transformation ausgelöst haben, erhalten Sie unterschiedliche Dateipfade. Dies kann verwirrend sein.

Hinzufügen von Verweisen und Einbindung von Pfaden

Der Host verfügt über einen Standardsatz von Pfaden, in denen er nach Assemblys sucht, auf die in Vorlagen verwiesen wird. So fügen Sie dieses Set hinzu:

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

Um die Ordner festzulegen, die nach Include-Dateien durchsucht werden sollen, geben Sie eine durch Semikolons getrennte Liste an. In der Regel erweitern Sie die vorhandene Ordnerliste.

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

Übergeben von Buildkontextdaten an die Vorlagen

Sie können Parameterwerte in der Projektdatei festlegen. Sie können beispielsweise Build-Eigenschaften und Umgebungsvariablen übergeben:

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

Legen Sie hostspecific in der Vorlagendirektive einer Textvorlage fest. Verwenden Sie die Parameterdirektive, um Werte abzurufen.

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

In einem Direktivenprozessor können Sie ITextTemplatingEngineHost.ResolveParameterValue aufrufen:

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

Hinweis

ResolveParameterValue ruft Daten nur von T4ParameterValues ab, wenn Sie MSBuild verwenden. Wenn Sie die Vorlage mit Visual Studio transformieren, weisen die Parameter Standardwerte auf.

Verwenden von Projekteigenschaften in der Assembly und Einschließen von Direktiven

Visual Studio-Makros wie $(SolutionDir) funktionieren in MSBuild nicht. Sie können stattdessen Projekteigenschaften verwenden.

Bearbeiten Sie ihre CSPROJ - oder VBPROJ-Datei , um eine Projekteigenschaft zu definieren. In diesem Beispiel wird eine Eigenschaft namens "myLibFolder" definiert:

<!-- 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>

Jetzt können Sie Ihre Projekteigenschaft in assembly verwenden und Direktiven einschließen:

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

Diese Direktiven erhalten Werte von T4parameterValues sowohl in MSBuild als auch in Visual Studio-Hosts.

Fragen und Antworten

Warum möchte ich Vorlagen auf dem Buildserver transformieren? Ich habe Vorlagen bereits in Visual Studio transformiert, bevor ich meinen Code eingecheckt habe.

Wenn Sie eine eingeschlossene Oder eine andere Datei aktualisieren, die von der Vorlage gelesen wird, transformiert Visual Studio die Datei nicht automatisch. Durch das Transformieren von Vorlagen als Teil des Builds wird sichergestellt, dass alles auf dem neuesten Stand ist.

Welche weiteren Optionen gibt es zum Transformieren von Textvorlagen?

Verwandte Inhalte

  • Es gibt eine gute Anleitung in der Vorlage "T4 MSbuild" unter %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\MSBuild\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets
  • Last updated on