Delen via

Teksttransformatie aanroepen in het buildproces

Teksttransformatie kan worden aangeroepen als onderdeel van het buildproces van een Visual Studio-oplossing. Er zijn buildtaken die speciaal zijn voor teksttransformatie. De T4-buildtaken voeren ontwerp-tijdtekstsjablonen uit en ze compileren ook runtime-tekstsjablonen (vooraf verwerkt).

Er zijn enkele verschillen in wat de buildtaken kunnen doen, afhankelijk van de build-engine die u gebruikt. Wanneer u de oplossing in Visual Studio bouwt, heeft een tekstsjabloon toegang tot de Visual Studio-API (EnvDTE) als het kenmerk hostspecific="true" is ingesteld. Maar dat geldt niet wanneer u de oplossing bouwt vanaf de opdrachtregel of wanneer u een serverbuild initieert via Visual Studio. In die gevallen wordt de build uitgevoerd door MSBuild en wordt een andere T4-host gebruikt. Dit betekent dat u geen toegang hebt tot zaken zoals projectbestandsnamen op dezelfde manier wanneer u een tekstsjabloon maakt met BEHULP van MSBuild. U kunt echter omgevingsinformatie doorgeven aan tekstsjablonen en instructieprocessors met behulp van buildparameters.

Uw machines configureren

Als u buildtaken op uw ontwikkelcomputer wilt inschakelen, installeert u de Modeling SDK voor Visual Studio.

Opmerking

Het onderdeel Text Template Transformation wordt automatisch geïnstalleerd als onderdeel van de ontwikkelworkload van de Visual Studio-extensie . U kunt deze ook installeren op het tabblad Afzonderlijke onderdelen van Visual Studio Installer, onder de categorie SDK's, bibliotheken en frameworks . Installeer het Modeling SDK-onderdeel op het tabblad Afzonderlijke onderdelen .

Als uw buildserver wordt uitgevoerd op een computer waarop Visual Studio niet is geïnstalleerd, kopieert u de volgende bestanden naar de buildcomputer vanaf uw ontwikkelcomputer:

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

Aanbeveling

Als u een MissingMethodException methode voor Microsoft.CodeAnalysis krijgt bij het uitvoeren van TextTemplating-builddoelen op een buildserver, controleert u of de Roslyn-assembly's zich in een map bevinden met de naam Roslyn die zich in dezelfde map bevindt als het uitvoerbare buildbestand (bijvoorbeeld msbuild.exe).

Het projectbestand bewerken

Bewerk uw projectbestand om enkele van de functies in MSBuild te configureren, bijvoorbeeld het importeren van de teksttransformatiedoelen.

Kies in Solution Explorer de optie Ontladen uit het snelmenu van uw project. Hiermee kunt u het .csproj- of VBPROJ-bestand bewerken in de XML-editor. Wanneer u klaar bent met bewerken, kiest u Opnieuw laden.

De teksttransformatiedoelen importeren

Zoek in het bestand .vbproj of .csproj de laatste Import Project regel.

Voeg na deze regel, als deze bestaat, de import Text Templating in:

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

Sjablonen in een build transformeren

Er zijn enkele eigenschappen die u in uw projectbestand kunt invoegen om de transformatietaak te beheren:

  • Voer de transformatietaak uit aan het begin van elke build:

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

  • Overschrijf bestanden die alleen-lezen zijn, bijvoorbeeld omdat ze niet zijn uitgecheckt:

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

  • Elke sjabloon elke keer transformeren:

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

    De T4 MSBuild-taak genereert standaard een uitvoerbestand opnieuw als deze ouder is dan:

    • het sjabloonbestand
    • bestanden die zijn inbegrepen
    • bestanden die eerder door het templatesysteem of door een directiveprocessor die het gebruikt zijn gelezen

    Dit is een krachtigere afhankelijkheidstest dan wordt gebruikt door de opdracht Alle sjablonen transformeren in Visual Studio, waarmee alleen de datums van de sjabloon en het uitvoerbestand worden vergeleken.

Als u alleen de teksttransformaties in uw project wilt uitvoeren, roept u de taak TransformAll aan:

msbuild myProject.csproj /t:TransformAll

Een specifieke tekstsjabloon transformeren:

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

U kunt jokertekens gebruiken in TransformFile:

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

Bronbeheer

Er is geen specifieke ingebouwde integratie met een broncodebeheersysteem. U kunt echter uw eigen extensies toevoegen, bijvoorbeeld om een gegenereerd bestand uit te checken en in te checken. De teksttransformatietaak vermijdt standaard het overschrijven van een bestand dat is gemarkeerd als alleen-lezen. Wanneer een dergelijk bestand wordt aangetroffen, wordt er een fout vastgelegd in de Visual Studio-foutenlijst en mislukt de taak.

Als u wilt opgeven dat alleen-lezenbestanden moeten worden overschreven, voegt u deze eigenschap in:

<OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>

Tenzij u de stap voor naverwerking aanpast, wordt een waarschuwing in de foutenlijst geregistreerd wanneer een bestand wordt overschreven.

Het buildproces aanpassen

Teksttransformatie vindt plaats vóór andere taken in het buildproces. U kunt taken definiëren die vóór en na transformatie worden aangeroepen door de eigenschappen $(BeforeTransform) en $(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 AfterTransformkunt u verwijzen naar lijsten met bestanden:

  • GeneratedFiles: een lijst met bestanden die door het proces zijn geschreven. Voor bestanden die bestaande alleen-lezenbestanden overschreven hebben, %(GeneratedFiles.ReadOnlyFileOverwritten) is dit waar. Deze bestanden kunnen worden uitgecheckt uit broncodebeheer.

  • NonGeneratedFiles : een lijst met alleen-lezenbestanden die niet zijn overschreven.

U definieert bijvoorbeeld een taak voor het uitchecken van GeneratedFiles.

OutputFilePath en OutputFileName

Deze eigenschappen worden alleen gebruikt door MSBuild. Ze hebben geen invloed op het genereren van code in Visual Studio. Ze leiden het gegenereerde uitvoerbestand om naar een andere map of een ander bestand. De doelmap moet al bestaan.

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

Een handige map om naar te omleiden is $(IntermediateOutputPath).

Als u een uitvoerbestandsbestand opgeeft, heeft deze voorrang op de extensie die is opgegeven in de uitvoerrichtlijn in de sjablonen.

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

Het opgeven van een OutputFileName of OutputFilePath wordt niet aanbevolen als u ook sjablonen in Visual Studio transformeert met behulp van Alles transformeren of de generator voor één bestand uitvoert. U krijgt verschillende bestandspaden, afhankelijk van de manier waarop u de transformatie hebt geactiveerd. Dit kan verwarrend zijn.

Verwijzing toevoegen en paden opnemen

De host heeft een standaardset paden waarin wordt gezocht naar assembly's waarnaar wordt verwezen in sjablonen. Ga als volgt te werk om deze set toe te voegen:

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

Geef een lijst gescheiden door puntkomma's op voor de mappen die worden doorzocht op insluitingsbestanden. Meestal voegt u deze toe aan de bestaande mappenlijst.

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

Contextgegevens van de build doorgeven aan de sjablonen

U kunt parameterwaarden instellen in het projectbestand. U kunt bijvoorbeeld buildeigenschappen en omgevingsvariabelen doorgeven:

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

In een tekstsjabloon, stel hostspecific in binnen de sjabloonrichtlijn. Gebruik de parameterrichtlijn om waarden op te halen:

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

In een instructieprocessor kunt u ITextTemplatingEngineHost.ResolveParameterValue aanroepen:

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

Opmerking

ResolveParameterValue haalt alleen gegevens op van T4ParameterValues wanneer u MSBuild gebruikt. Wanneer u de sjabloon transformeert met Visual Studio, hebben de parameters standaardwaarden.

Projecteigenschappen gebruiken in assembly en instructies opnemen

Visual Studio-macro's zoals $(SolutionDir) werken niet in MSBuild. U kunt in plaats daarvan projecteigenschappen gebruiken.

Bewerk uw .csproj - of VBPROJ-bestand om een projecteigenschap te definiëren. In dit voorbeeld wordt een eigenschap met de naam myLibFolder gedefinieerd:

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

U kunt nu uw projecteigenschap in de assembly gebruiken en richtlijnen opnemen.

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

Deze instructies krijgen waarden van T4parameterValues, zowel in MSBuild als in Visual Studio-hosts.

Vragen en antwoorden

Waarom zou ik sjablonen op de buildserver willen transformeren? Ik heb sjablonen al getransformeerd in Visual Studio voordat ik mijn code heb ingecheckt.

Als u een opgenomen bestand of een ander bestand bijwerkt dat door de sjabloon wordt gelezen, transformeert Visual Studio het bestand niet automatisch. Het transformeren van sjablonen als onderdeel van de build zorgt ervoor dat alles up-to-date is.

Welke andere opties zijn er voor het transformeren van tekstsjablonen?

Verwante inhoud

  • Er zijn goede richtlijnen in de T4 MSbuild-sjabloon te vinden op %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\MSBuild\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets
  • Last updated on