Megosztás a következőn keresztül:

Szövegátalakítás meghívása a buildelési folyamat során

A szövegátalakítás a Visual Studio-megoldások buildelési folyamatának részeként hívható meg. Vannak olyan összeállítási feladatok, amelyek szövegátalakításra specializálódnak. A T4 építési feladatok tervezési időben szöveges sablonokat futtatnak, és lefordítják a futásidejű (előre feldolgozott) szövegsablonokat is.

A buildelési feladatok végrehajtásában van néhány különbség attól függően, hogy melyik buildmotort használja. A megoldás Visual Studióban történő létrehozásakor egy szöveges sablon hozzáférhet a Visual Studio API-hoz (EnvDTE), ha a hostspecific="true" attribútum be van állítva. Ez azonban nem igaz, ha a megoldást a parancssorból hozza létre, vagy amikor a Visual Studióval kezdeményez egy kiszolgálói buildet. Ezekben az esetekben a buildelést az MSBuild végzi, és egy másik T4-gazdagépet használ. Ez azt jelenti, hogy az MSBuild használata esetén nem férhet hozzá például a projektfájlok nevéhez ugyanúgy, amikor szövegsablont épít. A környezeti adatokat azonban a buildparaméterek használatával szöveges sablonokba és irányelvfeldolgozókba is átadhatja.

Gépek konfigurálása

Ha engedélyezni szeretné a buildelési feladatokat a fejlesztői számítógépen, telepítse a Visual Studióhoz készült Modeling SDK-t.

Megjegyzés:

A Text Template Transformation összetevő automatikusan telepítve van a Visual Studio bővítményfejlesztési számítási feladatainak részeként. A Visual Studio Installer Egyes összetevők lapján, az SDK-k, kódtárak és keretrendszerek kategóriában is telepítheti. Telepítse a Modellezés SDK-összetevőt az Egyes összetevők lapon.

Ha a buildkiszolgáló olyan számítógépen fut, amelyen nincs telepítve a Visual Studio, másolja a következő fájlokat a buildelési számítógépre a fejlesztőgépről:

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

Jótanács

Ha a Microsoft.CodeAnalysis metódushoz kapcsolódó MissingMethodException hibát kap, miközben a TextTemplating buildcélokat futtatja egy buildkiszolgálón, győződjön meg arról, hogy a Roslyn assembly-k egy Roslyn nevű könyvtárban vannak, amely ugyanabban a könyvtárban található, mint a build futtatható fájl (például msbuild.exe).

A projektfájl szerkesztése

Szerkessze a projektfájlt az MSBuild egyes funkcióinak konfigurálásához, például a szövegátalakító célok importálásához.

A Megoldáskezelőben válassza a Projekt jobb gombbal kattintva elérhető menüjében a Eltávolítás lehetőséget. Ez lehetővé teszi a .csproj vagy a .vbproj fájl szerkesztését az XML-szerkesztőben. Ha végzett a szerkesztéssel, válassza az Újratöltés lehetőséget.

A szövegátalakítási célok importálása

A .vbproj vagy a .csproj fájlban keresse meg az utolsó Import Project sort.

A sor után, ha létezik, szúrja be a Szöveg-sablonozás importálását:

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

Sablonok átalakítása buildben

Az átalakítási feladat vezérléséhez beszúrhat néhány tulajdonságot a projektfájlba:

  • Futtassa az Átalakítás feladatot minden build elején:

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

  • Csak olvasható fájlok felülírása, például amikor nincsenek ellenőrzésre kivéve:

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

  • Minden sablon átalakítása minden alkalommal:

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

    Alapértelmezés szerint a T4 MSBuild feladat újragenerál egy kimeneti fájlt, ha régebbi, mint:

    • sablon fájlja
    • minden olyan fájl, amely bele van foglalva
    • a sablon vagy az általa használt irányelvfeldolgozó által korábban beolvasott fájlok

    Ez egy hatékonyabb függőségi teszt, mint amelyet a Visual Studio Összes sablon átalakítása parancsa használ, amely csak a sablon és a kimeneti fájl dátumait hasonlítja össze.

Ha csak a szövegátalakításokat szeretné végrehajtani a projektben, hívja meg a TransformAll feladatot:

msbuild myProject.csproj /t:TransformAll

Adott szövegsablon átalakítása:

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

Helyettesítő karaktereket használhat a TransformFile-ban:

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

Forrásvezérlő

Nincs konkrét beépített integráció egy forrásvezérlő rendszerrel. Hozzáadhat azonban saját bővítményeket, például egy létrehozott fájl kivételéhez és beadásához. Alapértelmezés szerint a szövegátalakítási feladat nem írja felül az írásvédettként megjelölt fájlokat. Ha ilyen fájlba ütközik, a rendszer hibát naplóz a Visual Studio hibalistájában, és a feladat meghiúsul.

Az írásvédett fájlok felülírásának megadásához szúrja be a következő tulajdonságot:

<OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>

Ha nem szabja testre az utófeldolgozási lépést, a rendszer figyelmeztetést naplóz a hibalistában egy fájl felülírásakor.

A buildelési folyamat testreszabása

A szövegátalakítás a buildelési folyamat egyéb tevékenységei előtt történik. Az átalakítás előtt és után meghívott feladatokat a tulajdonságok $(BeforeTransform) és $(AfterTransform)a következők beállításával határozhatja meg:

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

A AfterTransform alkalmazásban hivatkozhat fájllistákra.

  • GeneratedFiles – a folyamat által írt fájlok listája. Azoknál a fájloknál, amelyek felülírják a meglévő írásvédett fájlokat, %(GeneratedFiles.ReadOnlyFileOverwritten) igaz lesz. Ezek a fájlok kivehetők a forrásvezérlőből.

  • NonGeneratedFiles – a felül nem írt írásvédett fájlok listája.

Definiálhat például egy feladatot a GeneratedFiles ellenőrzésére vagy letöltésére.

KimenetiFájlÚtvonal és KimenetiFájlNév

Ezeket a tulajdonságokat csak az MSBuild használja. Ezek nem befolyásolják a Visual Studio kódgenerálását. Átirányítják a létrehozott kimeneti fájlt egy másik mappába vagy fájlba. A célmappának már léteznie kell.

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

Az $(IntermediateOutputPath) egy hasznos mappa, ahová átirányíthat.

Ha kimeneti fájlnevet ad meg, az elsőbbséget élvez a sablonok kimeneti irányelvében megadott kiterjesztéssel szemben.

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

A(z) OutputFileName vagy OutputFilePath megadása nem ajánlott, ha a Visual Studio-ban sablonok átalakítására kerül sor az Összes átalakítása funkcióval vagy egy fájlgenerátor futtatása során. Az átalakítás aktiválásának módjától függően különböző fájlelérési utakat fog eredményezni. Ez zavaró lehet.

Hivatkozás hozzáadása és elérési utak belefoglalása

A hoszt alapértelmezett útvonalkészlettel rendelkezik, ahol a sablonokban hivatkozott assembly-ket keres. Ha hozzá szeretne adni ehhez a csoporthoz:

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

Az include fájlok kereséséhez állítsa be a mappákat egy pontosvesszővel elválasztott lista megadásával. Általában hozzáadja a meglévő mappalistához.

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

A buildkörnyezet adatainak átadása a sablonokba

A projektfájlban paraméterértékeket állíthat be. Átadhatja például a buildtulajdonságokat és a környezeti változókat:

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

Szövegsablonban állítsa be a hostspecific-t a sablon irányelvben. Értékek lekéréséhez használja a paraméter irányelvet:

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

Egy irányelv-feldolgozóban meghívhatja az ITextTemplatingEngineHost.ResolveParameterValue parancsot:

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

Megjegyzés:

ResolveParameterValue csak akkor kap adatokat a T4ParameterValues-től, ha az MSBuild-et használja. Ha a sablont a Visual Studióval alakítja át, a paraméterek alapértelmezett értékekkel rendelkeznek.

Projekt tulajdonságainak használata az assembly-ben és include-direktívák alkalmazása

Az olyan Visual Studio-makrók, mint a $(SolutionDir) nem működnek az MSBuildben. Ehelyett a projekttulajdonságokat használhatja.

Szerkessze a .csproj vagy a .vbproj fájlt egy projekttulajdonság definiálásához. Ez a példa egy myLibFolder nevű tulajdonságot definiál:

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

Most már használhatja a projekttulajdonságot az összeállításban, és tartalmazhatja a direktívákat is.

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

Ezek az utasítások a T4parameterValues értékeit mind az MSBuild, mind a Visual Studio környezetében beszerzik.

Kérdések és válaszok

Miért szeretném átalakítani a sablonokat a buildkiszolgálón? A Visual Studióban már átalakítottam a sablonokat, mielőtt beadtam a kódot.

Ha frissít egy belefoglalt fájlt vagy egy sablon által olvasott fájlt, a Visual Studio nem alakítja át automatikusan a fájlt. A sablonok build részeként történő átalakítása biztosítja, hogy minden naprakész legyen.

Milyen egyéb lehetőségek állnak rendelkezésre a szövegsablonok átalakításához?

Kapcsolódó tartalom

  • A T4 MSbuild sablonban a következő helyen talál útmutatást: %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\MSBuild\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets
  • Last updated on