Pembuatan Kode Waktu Desain dengan menggunakan Templat Teks T4

Templat teks T4 waktu desain memungkinkan Anda menghasilkan kode program dan file lain dalam proyek Visual Studio Anda. Biasanya, Anda menulis templat sehingga bervariasi kode yang dihasilkannya sesuai dengan data dari model. Model adalah file atau database yang berisi informasi utama tentang persyaratan aplikasi Anda.

Misalnya, Anda dapat memiliki model yang menentukan alur kerja, baik sebagai tabel atau diagram. Dari model, Anda dapat menghasilkan perangkat lunak yang menjalankan alur kerja. Saat persyaratan pengguna Anda berubah, mudah untuk mendiskusikan alur kerja baru dengan pengguna. Meregenerasi kode dari alur kerja lebih dapat diandalkan daripada memperbarui kode secara manual.

Catatan

Model adalah sumber data yang menjelaskan aspek tertentu dari aplikasi. Ini bisa berupa bentuk apa pun, dalam segala jenis file atau database. Ini tidak harus dalam bentuk tertentu, seperti model UML atau model Bahasa Khusus Domain. Model umum dalam bentuk tabel atau file XML.

Anda mungkin sudah terbiasa dengan pembuatan kode. Saat Anda menentukan sumber daya dalam file .resx dalam solusi Visual Studio Anda, sekumpulan kelas dan metode dihasilkan secara otomatis. File sumber daya membuatnya jauh lebih mudah dan lebih dapat diandalkan untuk mengedit sumber daya daripada jika Anda harus mengedit kelas dan metode. Dengan templat teks, Anda dapat menghasilkan kode dengan cara yang sama dari sumber desain Anda sendiri.

Templat teks berisi campuran teks yang ingin Anda hasilkan, dan kode program yang menghasilkan bagian variabel teks. Kode program memungkinkan Anda mengulangi atau menghilangkan bagian teks yang dihasilkan secara kondisional. Teks yang dihasilkan sendiri dapat berupa kode program yang akan menjadi bagian dari aplikasi Anda.

Membuat Templat Teks Design-Time T4

Buat proyek Visual Studio baru, atau buka proyek yang sudah ada.
Tambahkan file templat teks ke proyek Anda dan beri nama dengan ekstensi .tt.

Untuk melakukannya, di Penjelajah Solusi, pada menu pintasan proyek Anda, pilih Tambahkan>Item Baru. Dalam kotak dialog Tambahkan Item Baru, pilih Templat Teks dari panel tengah.

Perhatikan bahwa properti Alat Kustom file adalah TextTemplatingFileGenerator.
Buka file . Ini sudah akan berisi arahan berikut:
```
<#@ template hostspecific="false" language="C#" #>
<#@ output extension=".txt" #>
```
Jika Anda menambahkan templat ke proyek Visual Basic, atribut bahasa akan menjadi "VB".
Tambahkan beberapa teks di akhir file. Contohnya:
```
Hello, world!
```
Simpan file.

Anda mungkin melihat kotak pesan Peringatan Keamanan yang meminta Anda untuk mengonfirmasi bahwa Anda ingin menjalankan templat. Klik OK.
Di Penjelajah Solusi, perluas simpul file templat dan Anda akan menemukan file yang memiliki ekstensi .txt. File berisi teks yang dihasilkan dari templat.

Catatan

Jika proyek Anda adalah proyek Visual Basic, Anda harus mengklik Tampilkan Semua File untuk melihat file output.

Meregenerasi kode

Templat akan dijalankan, menghasilkan file turunan, dalam salah satu kasus berikut:

Edit templat lalu ubah fokus ke jendela Visual Studio yang berbeda.
Simpan templat.
Klik Ubah Semua Templat di menu Build. Ini akan mengubah semua templat dalam solusi Visual Studio.
Di Penjelajah Solusi, pada menu pintasan file apa pun, pilih Jalankan Alat Kustom. Gunakan metode ini untuk mengubah subset templat yang dipilih.

Anda juga dapat menyiapkan proyek Visual Studio sehingga templat dijalankan saat file data yang dibaca telah berubah. Untuk informasi selengkapnya, lihat Meregenerasi kode secara otomatis.

Menghasilkan Teks Variabel

Templat teks memungkinkan Anda menggunakan kode program untuk memvariasikan konten file yang dihasilkan.

Mengubah konten file .tt:

<#@ template hostspecific="false" language="C#" #>
<#@ output extension=".txt" #>
<#int top = 10;

for (int i = 0; i<=top; i++)
{ #>
   The square of <#= i #> is <#= i*i #>
<# } #>

<#@ template hostspecific="false" language="VB" #>
<#@ output extension=".txt" #>
<#Dim top As Integer = 10

For i As Integer = 0 To top
#>
    The square of <#= i #> is <#= i*i #>
<#
Next
#>

.tt Simpan file, dan periksa file .txt yang dihasilkan lagi. Ini mencantumkan kuadrat angka dari 0 hingga 10.

Perhatikan bahwa pernyataan diapit dalam <#...#>, dan ekspresi tunggal dalam <#=...#>. Untuk informasi selengkapnya, lihat Menulis Template Teks T4.

Jika Anda menulis kode pembuatan dalam Visual Basic, arahan template harus berisi language="VB". "C#" adalah defaultnya.

Men-debug Templat Teks Design-Time T4

Untuk men-debug templat teks:

Masukkan debug="true" ke dalam direktif template. Contohnya:

<#@ template debug="true" hostspecific="false" language="C#" #>
Atur titik henti di templat, dengan cara yang sama seperti yang Anda lakukan untuk kode biasa.
Pilih Debug Templat T4 dari menu pintasan file templat teks di Penjelajah Solusi.

Templat berjalan dan berhenti di titik henti. Anda dapat memeriksa variabel dan menelusuri kode dengan cara biasa.

Tip

debug="true" membuat peta kode yang dihasilkan lebih akurat ke templat teks, dengan menyisipkan lebih banyak arahan penomoran baris ke dalam kode yang dihasilkan. Jika Anda membiarkannya keluar, titik henti mungkin menghentikan eksekusi dalam status yang salah.

Tetapi Anda dapat meninggalkan klausul dalam direktif templat bahkan saat Anda tidak menelusuri kesalahan. Ini hanya menyebabkan penurunan performa yang sangat kecil.

Membuat Kode atau Sumber Daya untuk Solusi Anda

Anda dapat membuat file program yang bervariasi, tergantung pada model. Model adalah input seperti database, file konfigurasi, model UML, model DSL, atau sumber lainnya. Anda biasanya menghasilkan beberapa file program dari model yang sama. Untuk mencapai hal ini, Anda membuat file templat untuk setiap file program yang dihasilkan, dan meminta semua templat membaca model yang sama.

Untuk menghasilkan kode program atau sumber daya

Ubah arahan output untuk menghasilkan file dengan jenis yang sesuai, seperti .cs, .vb, .resx, atau .xml.

Sisipkan kode yang akan menghasilkan kode solusi yang Anda butuhkan. Misalnya, jika Anda ingin menghasilkan tiga deklarasi bidang bilangan bulat dalam kelas:


<#@ template debug="false" hostspecific="false" language="C#" #>
<#@ output extension=".cs" #>
<# var properties = new string [] {"P1", "P2", "P3"}; #>
// This is generated code:
class MyGeneratedClass {
<# // This code runs in the text template:
  foreach (string propertyName in properties)  { #>
  // Generated code:
  private int <#= propertyName #> = 0;
<# } #>
}

<#@ template debug="false" hostspecific="false" language="VB" #>
<#@ output extension=".cs" #>
<# Dim properties = {"P1", "P2", "P3"} #>
class MyGeneratedClass {
<#
   For Each propertyName As String In properties
#>
  private int <#= propertyName #> = 0;
<#
   Next
#>
}

Simpan file dan periksa file yang dihasilkan, yang sekarang berisi kode berikut:

class MyGeneratedClass {
  private int P1 = 0;
  private int P2 = 0;
  private int P3 = 0;
}

Menghasilkan Kode dan Teks yang Dihasilkan

Saat Anda membuat kode program, yang paling penting untuk menghindari membingungkan kode pembuatan yang dijalankan di templat Anda, dan kode yang dihasilkan yang dihasilkan yang menjadi bagian dari solusi Anda. Dua bahasa tidak harus sama.

Contoh sebelumnya memiliki dua versi. Dalam satu versi, kode pembuatan ada di C#. Di versi lain, kode pembuatan Visual Basic. Tetapi teks yang dihasilkan oleh keduanya sama, dan ini adalah kelas C#.

Dengan cara yang sama, Anda dapat menggunakan templat Visual C# untuk menghasilkan kode dalam bahasa apa pun. Teks yang dihasilkan tidak harus dalam bahasa tertentu, dan tidak harus kode program.

Menyusun templat teks

Sebagai masalah praktik yang baik, kita cenderung memisahkan kode templat menjadi dua bagian:

Bagian konfigurasi atau pengumpulan data, yang menetapkan nilai dalam variabel, tetapi tidak berisi blok teks. Dalam contoh sebelumnya, bagian ini adalah inisialisasi properties.

Ini kadang-kadang disebut bagian "model", karena membangun model dalam penyimpanan, dan biasanya membaca file model.
Bagian pembuatan teks (foreach(...){...} dalam contoh), yang menggunakan nilai variabel.

Ini bukan pemisahan yang diperlukan, tetapi ini adalah gaya yang membuatnya lebih mudah untuk membaca templat dengan mengurangi kompleksitas bagian yang menyertakan teks.

Membaca file atau sumber lain

Untuk mengakses file model atau database, kode templat Anda bisa menggunakan assembly seperti System.XML. Untuk mendapatkan akses ke assembly ini, Anda harus menyisipkan arahan seperti ini:

<#@ assembly name="System.Xml.dll" #>
<#@ import namespace="System.Xml" #>
<#@ import namespace="System.IO" #>

Arahan assembly membuat assembly yang ditentukan tersedia untuk kode templat Anda, dengan cara yang sama seperti bagian Referensi dari proyek Visual Studio. Anda tidak perlu menyertakan referensi ke System.dll, yang dirujuk secara otomatis. Arahan import ini memungkinkan Anda menggunakan jenis tanpa menggunakan nama mereka yang sepenuhnya memenuhi syarat, dengan cara yang sama seperti arahan using dalam file program biasa.

Misalnya, setelah mengimpor System.IO, Anda dapat menulis:


<# var properties = File.ReadLines("C:\\propertyList.txt");#>
...
<# foreach (string propertyName in properties) { #>
...

<# For Each propertyName As String In
             File.ReadLines("C:\\propertyList.txt")
#>

Membuka file dengan nama jalur relatif

Untuk memuat file dari lokasi yang relatif terhadap templat teks, Anda dapat menggunakan this.Host.ResolvePath(). Untuk menggunakan this.Host, Anda harus mengatur hostspecific="true" dalam template:

<#@ template debug="false" hostspecific="true" language="C#" #>

Kemudian Anda dapat menulis, misalnya:

<# string filename = this.Host.ResolvePath("filename.txt");
  string [] properties = File.ReadLines(filename);
#>
...
<#  foreach (string propertyName in properties { #>
...

<# Dim filename = Me.Host.ResolvePath("propertyList.txt")
   Dim properties = File.ReadLines(filename)
#>
...
<#   For Each propertyName As String In properties
...
#>

Anda juga dapat menggunakan this.Host.TemplateFile, yang mengidentifikasi nama file templat saat ini.

Jenis this.Host (di VB, Me.Host) adalah Microsoft.VisualStudio.TextTemplating.ITextTemplatingEngineHost.

Mendapatkan data dari Visual Studio

Untuk menggunakan layanan yang disediakan dalam Visual Studio, atur atribut hostspecific dan muat assembly EnvDTE. Impor Microsoft.VisualStudio.TextTemplating, yang berisi metode ekstensi GetCOMService(). Anda kemudian dapat menggunakan IServiceProvider.GetCOMService() untuk mengakses DTE dan layanan lainnya. Contohnya:

<#@ template hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#@ import namespace="Microsoft.VisualStudio.TextTemplating" #>
<#
  IServiceProvider serviceProvider = (IServiceProvider)this.Host;
  EnvDTE.DTE dte = (EnvDTE.DTE) serviceProvider.GetCOMService(typeof(EnvDTE.DTE));
#>

Number of projects in this VS solution:  <#= dte.Solution.Projects.Count #>

Tip

Templat teks berjalan di domain aplikasinya sendiri, dan layanan diakses oleh marshaling. Dalam keadaan ini, GetCOMService() lebih dapat diandalkan daripada GetService().

Meregenerasi kode secara otomatis

Biasanya, beberapa file dalam solusi Visual Studio dihasilkan dengan satu model input. Setiap file dihasilkan dari templatnya sendiri, tetapi semua templat merujuk ke model yang sama.

Jika model sumber berubah, Anda harus menjalankan kembali semua templat dalam solusi. Untuk melakukan ini secara manual, pilih Ubah Semua Templat pada menu Build.

Jika Anda telah menginstal SDK pemodelan Visual Studio, Anda dapat mengubah semua templat secara otomatis setiap kali Anda melakukan build. Untuk melakukan ini, edit file proyek Anda (.csproj atau .vbproj) di editor teks dan tambahkan baris berikut di dekat akhir file, setelah pernyataan lainnya <import> . Dalam proyek bergaya SDK, ia dapat pergi ke mana saja dalam file proyek.

Catatan

SDK Transformasi Templat Teks dan SDK Pemodelan Visual Studio diinstal secara otomatis saat Anda menginstal fitur Visual Studio tertentu.

<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets" />
<PropertyGroup>
   <TransformOnBuild>true</TransformOnBuild>
   <!-- Other properties can be inserted here -->
</PropertyGroup>

Untuk informasi selengkapnya, lihat Pembuatan Kode dalam Proses Build.

Pelaporan kesalahan

Untuk menempatkan pesan kesalahan dan peringatan di jendela kesalahan Visual Studio, Anda dapat menggunakan metode ini:

Error("An error message");
Warning("A warning message");

Mengonversi file yang sudah ada menjadi templat

Fitur templat yang berguna adalah bahwa mereka terlihat sangat mirip dengan file yang mereka hasilkan, bersama dengan beberapa kode program yang disisipkan. Ini menyarankan metode yang berguna untuk membuat templat. Pertama-tama buat file biasa sebagai prototipe, seperti file Visual C#, lalu secara bertahap memperkenalkan kode pembuatan yang bervariasi pada file yang dihasilkan.

Untuk mengonversi file yang sudah ada menjadi templat waktu desain

Ke proyek Visual Studio Anda, tambahkan file jenis yang ingin Anda hasilkan, seperti file .cs, .vb, atau .resx.
Uji file baru untuk memastikan bahwa file tersebut berfungsi.
Di Penjelajah Solusi, ubah ekstensi nama file menjadi .tt.
Pastikan properti file .tt berikut:

Properti Pengaturan

Alat Kustom = TextTemplatingFileGenerator

Tindakan Build = Tidak
Sisipkan baris berikut ini di awal file:
```
<#@ template debug="false" hostspecific="false" language="C#" #>
<#@ output extension=".cs" #>
```
Jika Anda ingin menulis kode pembuatan templat Anda di Visual Basic, atur language atribut ke "VB" bukan "C#".

Atur extension atribut ke ekstensi nama file untuk jenis file yang ingin Anda hasilkan, misalnya .cs, .resx, atau .xml.
Simpan file.

File turunan dibuat, dengan ekstensi yang ditentukan. Propertinya benar untuk jenis file. Misalnya, properti Tindakan Build dari file .cs akan Dikompilasi.

Pastikan bahwa file yang dihasilkan berisi konten yang sama dengan file asli.
Identifikasi bagian file yang ingin Anda variasikan. Misalnya, bagian yang hanya muncul dalam kondisi tertentu, atau bagian yang diulang, atau tempat nilai tertentu bervariasi. Sisipkan kode pembuatan. Simpan file dan pastikan file turunan dihasilkan dengan benar. Ulangi langkah ini.

Properti	Pengaturan
Alat Kustom =	TextTemplatingFileGenerator
Tindakan Build =	Tidak

Panduan Pembuatan Kode

Lihat Panduan untuk Menulis Templat Teks T4.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-12-12