Dela via

Anropa texttransformering i byggprocessen

Texttransformering kan anropas som en del av byggprocessen för en Visual Studio-lösning. Det finns bygguppgifter som är specialiserade för texttransformering. T4-bygguppgifter kör textmallar vid designtid och kompilerar även textmallar vid körning (förbearbetade).

Det finns vissa skillnader i vad bygguppgifterna kan göra, beroende på vilken byggmotor du använder. När du skapar lösningen i Visual Studio kan en textmall komma åt Visual Studio API (EnvDTE) om attributet hostspecific="true" har angetts . Men det stämmer inte när du skapar lösningen från kommandoraden eller när du initierar en serverversion via Visual Studio. I dessa fall utförs bygget av MSBuild och en annan T4-värd används. Det innebär att du inte kan komma åt saker som projektfilnamn på samma sätt när du skapar en textmall med HJÄLP av MSBuild. Du kan dock skicka miljöinformation till textmallar och direktivprocessorer med hjälp av byggparametrar.

Konfigurera dina datorer

Om du vill aktivera bygguppgifter på utvecklingsdatorn installerar du Modeling SDK för Visual Studio.

Anmärkning

Komponenten Transformering av textmall installeras automatiskt som en del av arbetsbelastningen för utveckling av Visual Studio-tillägget. Du kan också installera den från fliken Enskilda komponenter i Visual Studio Installer under kategorin SDK:er, bibliotek och ramverk . Installera SDK-komponenten modellering från fliken Enskilda komponenter .

Om byggservern körs på en dator som inte har Visual Studio installerat kopierar du följande filer till byggdatorn från utvecklingsdatorn:

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

Tips/Råd

Om du får en MissingMethodException för en Microsoft.CodeAnalysis-metod när du kör TextTemplating-byggmål på en byggserver kontrollerar du att Roslyn-sammansättningarna finns i en katalog med namnet Roslyn som finns i samma katalog som den körbara versionen (till exempel msbuild.exe).

Redigera projektfilen

Redigera projektfilen för att konfigurera några av funktionerna i MSBuild, till exempel importera texttransformeringsmålen.

I Solution Explorer väljer du Ta bort från högerklicksmenyn i projektet. Det gör att du kan redigera .csproj- eller .vbproj-filen i XML-redigeraren. När du är klar med redigeringen väljer du Ladda om.

Importera texttransformeringens mål

Leta reda på den sista Import Project raden i filen .vbproj eller .csproj.

Efter den raden, om den finns, ska du infoga importen av texttemplating:

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

Transformera mallar i ett bygge

Det finns några egenskaper som du kan infoga i projektfilen för att styra omvandlingsaktiviteten:

  • Kör transformeringsaktiviteten i början av varje bygge:

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

  • Skriv över filer som är skrivskyddade, till exempel eftersom de inte är utcheckade:

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

  • Transformera varje mall varje gång:

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

    Som standard återskapar T4 MSBuild-aktiviteten en utdatafil om den är äldre än:

    • dess mallfil
    • filer som ingår
    • de filer som tidigare har lästs av mallen eller av den direktivprocessor som den använder

    Det här är ett kraftfullare beroendetest än vad som används av kommandot Transformera alla mallar i Visual Studio, som endast jämför datumen för mallen och utdatafilen.

Om du bara vill utföra texttransformeringar i projektet anropar du TransformAll-uppgiften:

msbuild myProject.csproj /t:TransformAll

Så här transformerar du en specifik textmall:

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

Du kan använda jokertecken i TransformFile:

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

Källkontroll

Det finns ingen specifik inbyggd integrering med ett källkontrollsystem. Du kan dock lägga till egna tillägg för att till exempel checka ut och checka in en genererad fil. Som standard undviker texttransformeringsaktiviteten att skriva över en fil som är markerad som skrivskyddad. När en sådan fil påträffas loggas ett fel i Visual Studio-fellistan och uppgiften misslyckas.

Om du vill ange att skrivskyddade filer ska skrivas över infogar du den här egenskapen:

<OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>

Om du inte anpassar efterbearbetningssteget loggas en varning i fellistan när en fil skrivs över.

Anpassa byggprocessen

Texttransformeringen sker före andra uppgifter i byggprocessen. Du kan definiera uppgifter som anropas före och efter omvandlingen genom att ange egenskaperna $(BeforeTransform) och $(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>

I AfterTransformkan du referera till listor med filer:

  • GeneratedFiles – en lista över filer som skrivits av processen. För de filer som skriver över befintliga skrivskyddade filer %(GeneratedFiles.ReadOnlyFileOverwritten) är det sant. Dessa filer kan checkas ut från källkontrollen.

  • NonGeneratedFiles – en lista över skrivskyddade filer som inte skrevs över.

Du kan till exempel definiera en uppgift för att checka ut GeneratedFiles.

"OutputFilePath" och "OutputFileName"

Dessa egenskaper används endast av MSBuild. De påverkar inte kodgenereringen i Visual Studio. De omdirigerar den genererade utdatafilen till en annan mapp eller fil. Målmappen måste redan finnas.

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

En användbar mapp att omdirigera till är $(IntermediateOutputPath).

Om du anger ett utdatafilnamn har det företräde framför tillägget som anges i utdatadirektivet i mallarna.

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

Att ange en OutputFileName eller OutputFilePath rekommenderas inte om du även transformerar mallar i Visual Studio med Transformera alla eller kör en enda filgenerator. Du får olika filsökvägar beroende på hur du utlöste omvandlingen. Det här kan vara förvirrande.

Lägga till referens- och inkluderingssökvägar

Värden har en standarduppsättning med sökvägar där den söker efter sammansättningar som refereras i mallar. Så här lägger du till i den här uppsättningen:

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

Ange en semikolonavgränsad lista om du vill ange de mappar som ska sökas efter inkluderingsfiler. Vanligtvis lägger du till i den befintliga mapplistan.

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

Skicka kompileringskontextdata till mallarna

Du kan ange parametervärden i projektfilen. Du kan till exempel skicka byggegenskaper och miljövariabler:

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

I en textmall ställer du in hostspecific i malldirektivet. Använd parameterdirektivet för att hämta värden:

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

I en direktivprocessor kan du anropa ITextTemplatingEngineHost.ResolveParameterValue:

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

Anmärkning

ResolveParameterValue hämtar endast data från T4ParameterValues när du använder MSBuild. När du transformerar mallen med Visual Studio har parametrarna standardvärden.

Använda projektegenskaper i sammansättning och inkludera direktiv

Visual Studio-makron som $(SolutionDir) fungerar inte i MSBuild. Du kan använda projektegenskaper i stället.

Redigera filen .csproj eller .vbproj för att definiera en projektegenskap. I det här exemplet definieras en egenskap med namnet 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>

Nu kan du använda projektegenskapen i sammansättning och inkludera direktiv:

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

Dessa direktiv hämtar värden från T4parameterValues både i MSBuild och Visual Studio.

Frågor och svar

Varför skulle jag vilja transformera mallar på byggservern? Jag har redan transformerat mallar i Visual Studio innan jag checkade in min kod.

Om du uppdaterar en inkluderad fil eller en annan fil som lästs av mallen omvandlar Visual Studio inte filen automatiskt. Om du omvandlar mallar som en del av bygget ser du till att allt är uppdaterat.

Vilka andra alternativ finns det för att transformera textmallar?

Relaterat innehåll

  • Det finns bra vägledning i T4 MSbuild-mallen på %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\MSBuild\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets
  • Skriva en T4-textmall
  • Last updated on