Codegenerierung in einem Buildprozess

Artikel
07/20/2011

Sie können Texttransformation als Teil des Buildprozesses einer Visual Studio-Lösung aufrufen. Sie können damit sicherstellen, dass von den Vorlagen generierte Dateien auf dem neuesten Stand sind, bevor sie kompiliert werden. Dadurch können Sie Situationen vermeiden, in denen der Benutzer vergisst, auf Alle Vorlagen transformieren zu klicken, bevor das Projekt erstellt oder Code eingecheckt wird. Texttransformationsaufgaben können sowohl von Visual Studio oder MSBuild als auch auf einem Buildserver ausgeführt werden.

Einschließen von Texttransformationsaufgaben in Projektdateien

Installieren des Visualisierungs- und Modellierungs-SDKs

Um Buildaufgaben auf dem Entwicklungscomputer zu aktivieren, installieren Sie das Visual Studio-Visualisierungs- und -Modellierungs-SDK.

Wenn Sie Buildaufgaben auf einem Buildserver ausführen möchten, finden Sie im Thema Texttransformation auf einem Buildserver weitere Informationen.

Bearbeiten der Projektdatei

Zum Aufrufen der Texttransformation müssen Sie die Datei bearbeiten, die das Projekt definiert. Diese Eigenschaften können nicht im Projekteigenschaften-Editor bearbeitet werden. Das Projekt muss daher geschlossen und als Textdatei bearbeitet werden.

So bearbeiten Sie den Text der Projektdatei

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und klicken Sie dann auf Projekt entladen.
Klicken Sie erneut mit der rechten Maustaste auf das Projekt, und klicken Sie dann auf Projekt bearbeiten.

Der Text der Projektdatei wird im XML-Editor angezeigt.

So öffnen Sie das Projekt erneut nach der Bearbeitung

Schließen Sie den XML-Editor.
Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und klicken Sie dann auf Projekt erneut laden.

Importieren der Texttransformationsziele

Die Buildaufgaben für die Texttransformation werden in einer einzelnen Datei definiert. Die Datei muss nach den standardmäßigen C#- oder Visual Basic-Zielen importiert werden.

So importieren Sie die Texttransformationsziele

Suchen Sie in der Datei nach einer Zeile, die einer der folgenden Zeilen ähnelt:

<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />

- oder -

<Import Project="$(MSBuildToolsPath)\Microsoft.VisualBasic.targets" />
Fügen Sie nach dieser Zeile den Textvorlagenimport ein:

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

Festlegen von Eigenschaften zum Steuern der Buildausführung

Fügen Sie den folgenden Text in der Projektdatei ein. In den folgenden Abschnitten finden Sie Informationen zu anderen Eigenschaften, die in dieser Eigenschaftengruppe eingefügt werden können.

<PropertyGroup>
 <TransformOnBuild>true</TransformOnBuild>
 <!-- Other properties can be inserted here -->
</PropertyGroup>

Durch TransformOnBuild werden alle Vorlagen im Projekt ausgeführt, wenn Sie das Projekt erstellen.

Aufrufen einer Transformation

Transformieren aller Vorlagen in einem Projektbuild

Wenn Sie die folgende Eigenschaft in die Projektdatei einschließen, werden alle Textvorlagen im Projekt bei jeder Erstellung des Projekts ausgeführt (abhängig von der Funktion "Inkrementeller Build").

Sie können Transformationen aufrufen, indem Sie in Visual Studio F5 drücken oder MSBuild verwenden. Beispiel:

msbuild myproject.csproj

Wenn Sie TransformOnBuild weglassen oder auf false festlegen, werden Vorlagen nicht automatisch im Rahmen des Projektbuilds transformiert.

Hinzufügen von Verweispfaden

Sie können dem Satz von Pfaden, an denen der Host nach in Vorlagen referenzierten Assemblys sucht, Pfade hinzufügen. Beispiel:

<ItemGroup>
    <!-- Add VS\...\PublicAssemblies to the list of places
         to look for assemblies used by templates. -->
    <T4ReferencePath Include="$(VsIdePath)PublicAssemblies\" />
</ItemGroup>

Transformieren spezifischer Vorlagen

Sie können angegebene Dateien transformieren, indem Sie die Transform-Aufgabe mit dem msbuild-Hilfsprogramm aufrufen. Diese Aufgabe ist unabhängig von der TransformOnBuild-Eigenschaft und kompiliert die Projektdateien nicht. Sie müssen die Datei mit den Textvorlagenzielen wie oben beschrieben importieren.

Gehen Sie zum Transformieren einer bestimmten Datei z. B. wie folgt vor:

msbuild myproj.proj /t:Transform /p:TransformFile=MyTemplate.tt

Sie können auch Platzhalterzeichen im TransformFile-Parameter verwenden. Durch den folgenden Befehl werden z. B. alle TT-Dateien im Ordner "GeneratedCode" transformiert:

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

Inkrementeller Build

Standardmäßig versucht der Build-Manager die Ausführung einer Vorlage zu umgehen, wenn die Ausgabedatei aktuell ist. Zu diesem Zweck überwacht er das Dateisystem, um festzustellen, welche Dateien vom Vorlagencode gelesen werden. Das Änderungsdatum dieser Dateien wird dann mit dem Datum der Ausgabedatei verglichen. Die Vorlage wird ausgeführt, wenn das Änderungsdatum einer Eingabedatei neuer ist als das der Ausgabedatei. Die Vorlage wird auch ausgeführt, wenn keine Informationen zu vorherigen Ausführungen dieser Vorlage vorhanden sind.

Die Ausgabedatei wird somit erneut generiert, wenn sie älter als eine der folgenden Dateien ist:

Die Textvorlagendatei
In <#@include#>-Direktiven angegebene Dateien
Dateien, die vom Code in der Vorlage gelesen werden
Dateien, die von einem in der Vorlage verwendeten Direktivenprozessor eingeschlossen oder gelesen werden

Fügen Sie die folgende Eigenschaft ein, wenn Sie sicherstellen möchten, dass alle Vorlagen in jedem Build ausgeführt werden:

<TransformOutOfDateOnly>false</TransformOutOfDateOnly>

Quellcodeverwaltung

Es besteht keine spezifische integrierte Integration in ein Quellcodeverwaltungssystem. Sie können jedoch eigene Erweiterungen hinzufügen, z. B. zum Aus- und Einchecken einer generierten Datei.

Beim Standardverhalten umgeht die Texttransformationsaufgabe das Überschreiben von Dateien, die als schreibgeschützt markiert sind. Wenn eine solche Datei gefunden wird, wird ein Fehler in der Visual Studio-Fehlerliste protokolliert, und die Aufgabe schlägt fehl.

Fügen Sie die folgende Eigenschaft ein, um anzugeben, dass schreibgeschützte Dateien überschrieben werden sollen:

Sofern Sie den Nachverarbeitungsschritt nicht anpassen, wird eine Warnung in der Fehlerliste protokolliert, wenn eine Datei überschrieben wird.

Anpassen des Buildprozesses

Sie können den Buildprozess anpassen, z. B. um überschriebene Dateien auszuchecken. Es sind zwei Anpassungspunkte verfügbar, die vor und nach der Transformation aufgerufen werden.

Konfigurieren Sie zum Definieren dieser Punkte die Eigenschaften $(BeforeTransform) und $(AfterTransform).

Beispiel:

<PropertyGroup>
    <BeforeTransform>CustomPreTransform</BeforeTransform>
    <AfterTransform>CustomPostTransform;$(AfterTransform)</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 die folgenden Listen verweisen:

GeneratedFiles – Eine Liste von Dateien, die vom Prozess geschrieben werden. Für die Dateien, durch die vorhandene schreibgeschützte Dateien überschrieben wurden, ist %(GeneratedFiles.ReadOnlyFileOverwritten) true. Diese Dateien können aus der Quellcodeverwaltung ausgecheckt werden.
NonGeneratedFiles– Eine Liste von schreibgeschützten Dateien, die nicht überschrieben wurden.

Anhand dieser Listen können Sie z. B. überschriebene Dateien auschecken.

Texttransformation auf einem Buildserver

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

\Programme\Microsoft Visual Studio 2010 SDK\VisualStudioIntegration\Common\Assemblies\v4.0\
- Microsoft.VisualStudio.TextTemplating.10.0.dll
- Microsoft.VisualStudio.TextTemplating.Interfaces.10.0.dll
- Microsoft.VisualStudio.TextTemplating.VSHost.10.0.dll
\Program Files\MSBuild\Microsoft\VisualStudio\TextTemplating\v10.0\
- Microsoft.VisualStudio.TextTemplating.Sdk.Host.10.0.dll
\Programme\Microsoft Visual Studio 10.0\Common7\IDE\PublicAssemblies\
- Microsoft.VisualStudio.TextTemplating.Modeling.10.0.dll

Weitere Informationen finden Sie unter Erstellen und Verwenden eines Buildcontrollers.

Siehe auch

Weitere Ressourcen

Visual Studio 2010-Visualisierungs- und Modellierungs-SDK

Freigeben über