Memanggil transformasi teks dalam proses build

Transformasi teks dapat dipanggil sebagai bagian dari proses build solusi Visual Studio. Ada tugas build yang dikhususkan untuk transformasi teks. Tugas build T4 menjalankan templat teks waktu desain, dan juga mengkompilasi templat teks run-time (praproscesed).

Ada beberapa perbedaan dalam apa yang dapat dilakukan tugas build, tergantung pada mesin build mana yang Anda gunakan. Saat Anda membangun solusi di Visual Studio, templat teks dapat mengakses atribut Visual Studio API (EnvDTE) jika atribut hostspecific="true" diatur. Tetapi itu tidak benar ketika Anda membangun solusi dari baris perintah atau saat Anda memulai build server melalui Visual Studio. Dalam kasus tersebut, build dilakukan oleh MSBuild dan host T4 yang berbeda digunakan. Ini berarti Anda tidak dapat mengakses hal-hal seperti nama file proyek dengan cara yang sama saat Anda membangun templat teks menggunakan MSBuild. Namun, Anda dapat meneruskan informasi lingkungan ke dalam templat teks dan prosesor direktif dengan menggunakan parameter build.

Mengonfigurasi komputer Anda

Untuk mengaktifkan tugas build di komputer pengembangan Anda, instal SDK Pemodelan untuk Visual Studio.

Catatan

Komponen Transformasi Template Teks secara otomatis diinstal sebagai bagian dari beban kerja pengembangan ekstensi Visual Studio. Anda juga dapat menginstalnya dari tab Komponen individual Alat Penginstal Visual Studio, di bawah kategori SDK, pustaka, dan kerangka kerja. Instal komponen SDK Pemodelan dari tab Komponen individual.

Jika server build Anda berjalan di komputer yang tidak menginstal Visual Studio, salin file berikut ke komputer build dari komputer pengembangan Anda:

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

Tip

Jika Anda mendapatkan MissingMethodException untuk metode Microsoft.CodeAnalysis saat menjalankan target build TextTemplating di server build, pastikan rakitan Roslyn berada di direktori bernama Roslyn yang berada di direktori yang sama dengan build yang dapat dieksekusi (misalnya, msbuild.exe).

Mengedit file proyek

Edit file proyek Anda untuk mengonfigurasi beberapa fitur di MSBuild, misalnya, mengimpor target transformasi teks.

Di Penjelajah Solusi, pilih Bongkar dari menu klik kanan proyek Anda. Itu memungkinkan Anda mengedit file .csproj atau .vbproj di editor XML. Setelah selesai mengedit, pilih Muat Ulang.

Mengimpor target transformasi teks

Dalam file .vbproj atau .csproj, temukan baris terakhir Import Project .

Setelah baris tersebut, jika ada, sisipkan impor Templat Teks:

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

Mengubah templat dalam build

Ada beberapa properti yang bisa Anda sisipkan ke dalam file proyek Anda untuk mengontrol tugas transformasi:

• Jalankan tugas Transformasi di awal setiap build:

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

• Timpa file yang bersifat baca-saja, misalnya, karena tidak dicek keluar:

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

• Ubah setiap templat setiap kali:

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

  Secara default, tugas T4 MSBuild meregenerasi file output jika lebih lama dari:

  • file templatnya
  • file apa pun yang disertakan
  • file apa pun yang sebelumnya telah dibaca oleh templat atau oleh prosesor direktif yang digunakannya

  Ini adalah pengujian dependensi yang lebih kuat daripada yang digunakan oleh perintah Transformasi Semua Templat di Visual Studio, yang hanya membandingkan tanggal templat dan file output.

Untuk melakukan hanya transformasi teks dalam proyek Anda, panggil tugas TransformAll:

msbuild myProject.csproj /t:TransformAll

Untuk mengubah templat teks tertentu:

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

Anda dapat menggunakan kartubebas di TransformFile:

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

Kontrol sumber

Tidak ada integrasi bawaan khusus dengan sistem kontrol sumber. Namun, Anda dapat menambahkan ekstensi Anda sendiri, misalnya, untuk memeriksa dan memeriksa file yang dihasilkan. Secara default, tugas transformasi teks menghindari penimpaan file yang ditandai sebagai baca-saja. Ketika file seperti itu ditemui, kesalahan dicatat di Daftar Kesalahan Visual Studio, dan tugas gagal.

Untuk menentukan bahwa file baca-saja harus ditimpa, sisipkan properti ini:

<OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>

Kecuali Anda menyesuaikan langkah pasca-pemrosesan, peringatan akan dicatat dalam Daftar Kesalahan saat file ditimpa.

Menyesuaikan proses build

Transformasi teks terjadi sebelum tugas lain dalam proses build. Anda dapat menentukan tugas yang dipanggil sebelum dan sesudah transformasi, dengan mengatur properti $(BeforeTransform) dan $(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>

Di AfterTransform, Anda dapat mereferensikan daftar file:

• GeneratedFiles - daftar file yang ditulis oleh proses. Untuk file yang menimpa file baca-saja yang ada, %(GeneratedFiles.ReadOnlyFileOverwritten) akan benar. File-file ini dapat dicek keluar dari kontrol sumber.

• NonGeneratedFiles - daftar file baca-saja yang tidak ditimpa.

Misalnya, Anda menentukan tugas untuk memeriksa GeneratedFiles.

OutputFilePath dan OutputFileName

Properti ini hanya digunakan oleh MSBuild. Mereka tidak memengaruhi pembuatan kode di Visual Studio. Mereka mengalihkan file output yang dihasilkan ke folder atau file yang berbeda. Folder target harus sudah ada.

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

Folder yang berguna untuk dialihkan adalah $(IntermediateOutputPath).

Jika Anda menentukan nama file output, itu lebih diutamakan daripada ekstensi yang ditentukan dalam arahan output dalam templat.

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

Menentukan OutputFileName atau OutputFilePath tidak disarankan jika Anda juga mengubah templat di dalam Visual Studio menggunakan Transformasi Semua atau menjalankan generator file tunggal. Anda akan berakhir dengan jalur file yang berbeda tergantung pada cara Anda memicu transformasi. Ini bisa membingungkan.

Menambahkan referensi dan menyertakan jalur

Host memiliki sekumpulan jalur default di mana ia mencari rakitan yang dirujuk dalam templat. Untuk menambahkan ke set ini:

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

Untuk mengatur folder yang akan dicari untuk menyertakan file, berikan daftar yang dipisahkan titik koma. Biasanya Anda menambahkan ke daftar folder yang ada.

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

Meneruskan data konteks build ke dalam templat

Anda dapat mengatur nilai parameter dalam file proyek. Misalnya, Anda dapat meneruskan properti build dan variabel lingkungan:

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

Dalam templat teks, atur hostspecific di direktif templat. Gunakan direktif parameter untuk mendapatkan nilai:

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

Dalam prosesor direktif, Anda dapat memanggil ITextTemplatingEngineHost.ResolveParameterValue:

C#

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

VB

Dim value = Host.ResolveParameterValue("-", "-", "parameterName")

Catatan

ResolveParameterValue mendapatkan data hanya dari T4ParameterValues saat Anda menggunakan MSBuild. Saat Anda mengubah templat menggunakan Visual Studio, parameter memiliki nilai default.

Gunakan properti proyek dalam rakitan dan sertakan arahan

Makro Visual Studio seperti $(SolutionDir) tidak berfungsi di MSBuild. Anda dapat menggunakan properti proyek sebagai gantinya.

Edit file .csproj atau .vbproj Anda untuk menentukan properti proyek. Contoh ini mendefinisikan properti bernama 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>

Sekarang Anda dapat menggunakan properti proyek Anda di assembly dan menyertakan direktif:

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

Direktif ini mendapatkan nilai dari T4parameterValues baik di MSBuild maupun di host Visual Studio.

T & J

Mengapa saya ingin mengubah templat di server build? Saya sudah mengubah templat di Visual Studio sebelum saya memeriksa kode saya.

Jika Anda memperbarui file yang disertakan atau file lain yang dibaca oleh templat, Visual Studio tidak mengubah file secara otomatis. Mengubah templat sebagai bagian dari build memastikan bahwa semuanya sudah diperbarui.

Opsi lain apa yang ada untuk mengubah templat teks?

• Utilitas TextTransform dapat digunakan dalam skrip perintah. Dalam kebanyakan kasus, lebih mudah untuk menggunakan MSBuild.

• Panggil Transformasi Teks di ekstensi Visual Studio.

• Templat teks waktu desain diubah oleh Visual Studio.

• Templat teks run-time diubah pada waktu proses di aplikasi Anda.

Konten terkait

• Ada panduan yang baik dalam templat T4 MSbuild di %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\MSBuild\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets

• Menulis templat teks T4