Menulis Templat Teks T4
Templat teks berisi teks yang akan dihasilkan darinya. Misalnya, templat yang membuat halaman web akan berisi "<html>..." dan semua bagian standar lainnya dari halaman HTML. Dimasukkan ke dalam templat adalah blok kontrol, yang merupakan fragmen kode program. Blok kontrol menyediakan nilai yang bervariasi dan memungkinkan bagian teks menjadi kondisional dan diulang.
Struktur ini membuat templat mudah dikembangkan, karena Anda dapat memulai dengan prototipe file yang dihasilkan, dan secara bertahap menyisipkan blok kontrol yang memvariasikan hasilnya.
Template terdiri dari bagian-bagian berikut:
Arahan - elemen yang mengontrol cara templat diproses.
Blok teks - konten yang disalin langsung ke output.
Blok kontrol - kode program yang menyisipkan nilai variabel ke dalam teks, dan mengontrol bagian teks kondisional atau berulang.
Untuk mencoba contoh dalam topik ini, salin ke dalam file templat seperti yang dijelaskan dalam Pembuatan Kode Waktu Desain dengan menggunakan Templat Teks T4. Setelah mengedit file templat, simpan, lalu periksa output .txt file.
Arahan
Arahan templat teks memberikan instruksi umum kepada mesin templat teks tentang cara menghasilkan kode transformasi dan file output.
Misalnya, direktif berikut menentukan bahwa file output harus memiliki ekstensi .txt:
<#@ output extension=".txt" #>
Untuk informasi selengkapnya tentang arahan, lihat Arahan Templat Teks T4.
Blok teks
Blok teks menyisipkan teks langsung ke dalam file output. Tidak ada pemformatan khusus untuk blok teks. Misalnya, templat teks berikut akan menghasilkan file teks yang berisi kata "Halo":
<#@ output extension=".txt" #>
Hello
Blok kontrol
Blok kontrol adalah bagian dari kode program yang digunakan untuk mengubah templat. Bahasa defaultnya adalah C#, tetapi untuk menggunakan Visual Basic, Anda dapat menulis direktif ini di awal file:
<#@ template language="VB" #>
Bahasa tempat Anda menulis kode di blok kontrol tidak terkait dengan bahasa teks yang dihasilkan.
Blok kontrol standar
Blok kontrol standar adalah bagian dari kode program yang menghasilkan bagian dari file output.
Anda dapat mencampur sejumlah blok teks dan blok kontrol standar dalam file templat. Namun, Anda tidak dapat menempatkan satu blok kontrol di dalam blok lain. Setiap blok kontrol standar dibatasi oleh simbol <# ... #>.
Misalnya, blok kontrol dan blok teks berikut menyebabkan file output berisi baris "0, 1, 2, 3, 4 Halo!":
<#
for(int i = 0; i < 4; i++)
{
Write(i + ", ");
}
Write("4");
#> Hello!
Alih-alih menggunakan pernyataan eksplisit Write(), Anda dapat mengintervensi teks dan kode. Contoh berikut mencetak "Halo!" empat kali:
<#
for(int i = 0; i < 4; i++)
{
#>
Hello!
<#
}
#>
Anda dapat menyisipkan blok teks di mana pun Write(); pernyataan akan diizinkan dalam kode.
Catatan
Saat Anda menyematkan blok teks dalam pernyataan majemuk seperti perulangan atau kondisional, selalu gunakan kurung kurawal {...} untuk memuat blok teks.
Blok kontrol ekspresi
Blok kontrol ekspresi mengevaluasi ekspresi dan mengonversinya menjadi string. Ini dimasukkan ke dalam file output.
Blok kontrol ekspresi dibatasi oleh simbol <#= ... #>
Misalnya, blok kontrol berikut menyebabkan file output berisi "5":
<#= 2 + 3 #>
Perhatikan bahwa simbol pembukaan memiliki tiga karakter "<#=".
Ekspresi dapat menyertakan variabel apa pun yang berada dalam cakupan. Misalnya, blok ini mencetak baris dengan angka:
<#@ output extension=".txt" #>
<#
for(int i = 0; i < 4; i++)
{
#>
This is hello number <#= i+1 #>: Hello!
<#
}
#>
Blok kontrol fitur kelas
Blok kontrol fitur kelas mendefinisikan properti, metode, atau kode lain yang tidak boleh disertakan dalam transformasi utama. Blok fitur kelas sering digunakan untuk fungsi pembantu. Biasanya, blok fitur kelas ditempatkan dalam file terpisah sehingga dapat disertakan oleh lebih dari satu templat teks.
Blok kontrol ekspresi dibatasi oleh simbol <#+ ... #>
Misalnya, file templat berikut mendeklarasikan dan menggunakan metode:
<#@ output extension=".txt" #>
Squares:
<#
for(int i = 0; i < 4; i++)
{
#>
The square of <#= i #> is <#= Square(i+1) #>.
<#
}
#>
That is the end of the list.
<#+ // Start of class feature block
private int Square(int i)
{
return i*i;
}
#>
Fitur kelas harus ditempatkan di akhir file tempat mereka ditulis. Namun, Anda dapat <#@include#> file yang berisi fitur kelas, bahkan jika direktif include diikuti oleh blok dan teks standar.
Untuk informasi selengkapnya tentang blok kontrol, lihat Blok Kontrol Templat Teks.
Blok fitur kelas dapat berisi blok teks
Anda dapat menulis metode yang menghasilkan teks. Misalnya:
List of Squares:
<#
for(int i = 0; i < 4; i++)
{ WriteSquareLine(i); }
#>
End of list.
<#+ // Class feature block
private void WriteSquareLine(int i)
{
#>
The square of <#= i #> is <#= i*i #>.
<#+
}
#>
Sangat berguna untuk menempatkan metode yang menghasilkan teks dalam file terpisah yang dapat disertakan oleh lebih dari satu templat.
Menggunakan definisi eksternal
Rakitan
Blok kode templat Anda dapat menggunakan jenis yang ditentukan sebagai rakitan.NET yang paling sering digunakan seperti System.dll. Selain itu, Anda dapat mereferensikan rakitan.NET lainnya atau rakitan Anda sendiri. Anda dapat memberikan nama jalur, atau nama yang kuat dari rakitan:
<#@ assembly name="System.Xml" #>
Anda harus menggunakan nama jalur absolut, atau menggunakan nama makro standar dalam nama jalur. Misalnya:
<#@ assembly name="$(SolutionDir)library\MyAssembly.dll" #>
Direktif perakitan tidak berpengaruh dalam templat teks yang telah diolah sebelumnya.
Untuk informasi selengkapnya, lihat Arahan rakitan T4.
Namespace
Direktif impor sama using dengan klausul dalam C# atau imports klausa dalam Visual Basic. Ini memungkinkan Anda untuk merujuk ke jenis dalam kode Anda tanpa menggunakan nama yang sepenuhnya memenuhi syarat:
<#@ import namespace="System.Xml" #>
Anda dapat menggunakan sebanyak assembly mungkin dan import direktif yang Anda inginkan. Anda harus menempatkannya sebelum teks dan blok kontrol.
Untuk informasi selengkapnya, lihat Direktif Impor T4.
Menyertakan kode dan teks
Direktif include menyisipkan teks dari file templat lain. Misalnya, arahan ini menyisipkan konten test.txt.
<#@ include file="c:\test.txt" #>
Konten yang disertakan diproses hampir seolah-olah itu adalah bagian dari templat teks termasuk. Namun, Anda dapat menyertakan file yang berisi blok <#+...#> fitur kelas meskipun direktif diikuti oleh teks biasa dan blok kontrol standar.
Untuk informasi selengkapnya, lihat Arahan Menyertakan T4.
Metode utilitas
Ada beberapa metode seperti Write() yang selalu tersedia untuk Anda di blok kontrol. Mereka menyertakan metode untuk membantu Anda mengindentasi output, dan untuk melaporkan kesalahan.
Anda juga dapat menulis serangkaian metode utilitas Anda sendiri.
Untuk informasi selengkapnya, lihat Metode Utilitas Templat Teks.
Mengubah Data dan Model
Aplikasi yang paling berguna untuk templat teks adalah menghasilkan materi berdasarkan konten sumber seperti model, database, atau file data. Templat Anda mengekstrak dan memformat ulang data. Kumpulan templat dapat mengubah sumber tersebut menjadi beberapa file.
Ada beberapa pendekatan untuk membaca file sumber.
Baca file di templat teks. Ini adalah cara paling sederhana untuk memasukkan data ke dalam templat:
<#@ import namespace="System.IO" #>
<# string fileContent = File.ReadAllText(@"C:\myData.txt"); ...
Muat file sebagai model yang dapat dinavigasi. Metode yang lebih kuat adalah membaca data sebagai model, yang dapat dinavigasi oleh kode templat teks Anda. Misalnya, Anda dapat memuat file XML dan menavigasinya dengan ekspresi JalurX. Anda juga dapat menggunakan xsd.exe untuk membuat sekumpulan kelas tempat Anda dapat membaca data XML.
Edit file model dalam diagram atau formulir. Domain-Specific Language Tools menyediakan alat yang memungkinkan Anda mengedit model sebagai diagram atau formulir Windows. Ini memudahkan untuk mendiskusikan model dengan pengguna aplikasi yang dihasilkan. Domain-Specific Language Tools juga membuat sekumpulan kelas dengan jenis kuat yang mencerminkan struktur model. Untuk informasi selengkapnya, lihat Membuat Kode dari Bahasa Khusus Domain.
Jalur file relatif dalam templat waktu desain
Dalam templat teks waktu desain, jika Anda ingin mereferensikan file di lokasi yang relatif terhadap templat teks, gunakan this.Host.ResolvePath(). Anda juga harus mengatur hostspecific="true" dalam direktif template:
<#@ template hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ import namespace="System.IO" #>
<#
// Find a path within the same project as the text template:
string myFile = File.ReadAllText(this.Host.ResolvePath("MyFile.txt"));
#>
Content of MyFile.txt is:
<#= myFile #>
Anda juga dapat memperoleh layanan lain yang disediakan oleh host. Untuk informasi selengkapnya, lihat Akses Visual Studio dari Templat Teks.
Templat Teks waktu desain berjalan di AppDomain terpisah
Anda harus menyadari bahwa templat teks waktu desain berjalan di AppDomain yang terpisah dari aplikasi utama. Dalam kebanyakan kasus, ini tidak penting, tetapi Anda mungkin menemukan pembatasan dalam kasus kompleks tertentu. Misalnya, jika Anda ingin meneruskan data masuk atau keluar dari templat dari layanan terpisah, maka layanan harus menyediakan API yang dapat diserialisasikan.
(Ini tidak benar dari templat teks run-time, yang menyediakan kode yang dikompilasi bersama dengan kode Anda lainnya.)
Mengedit Templat
Editor templat teks khusus dapat diunduh dari Galeri Online Extension Manager. Pada menu Alat, klik Pengelola Ekstensi. Klik Galeri Online, lalu gunakan alat pencarian.