Blok Kontrol Templat Teks

Blok kontrol memungkinkan Anda menulis kode di templat teks untuk memvariasikan output. Ada tiga jenis blok kontrol, yang dibedakan oleh tanda kurung bukanya:

• <# Standard control blocks #> dapat berisi pernyataan.

• <#= Expression control blocks #> dapat berisi ekspresi.

• <#+ Class feature control blocks #> dapat berisi metode, bidang, dan properti.

Blok kontrol standar

Blok kontrol standar berisi pernyataan. Misalnya, blok standar berikut mendapatkan nama semua atribut dalam dokumen XML:

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

<#
    List<string> allAttributes = new List<string>();
    XmlDocument xDoc = new XmlDocument();
    xDoc.Load(@"E:\CSharp\Overview.xml");
    XmlAttributeCollection attributes = xDoc.Attributes;
    if (attributes.Count > 0)
    {
       foreach (XmlAttribute attr in attributes)
       {
           allAtributes.Add(attr.Name);
       }
     }
#>

Anda dapat menyematkan teks biasa di dalam pernyataan majemuk seperti if atau for. Misalnya, fragmen ini menghasilkan baris output di setiap iterasi perulangan:

<#
       foreach (XmlAttribute attr in attributes)
       {
#>
Found another one!
<#
           allAtributes.Add(attr.Name);
       }
#>

Peringatan

Selalu gunakan {...} untuk memisahkan pernyataan berlapis yang berisi teks biasa yang disematkan. Contoh berikut mungkin tidak berfungsi dengan baik:

<# if (ShouldPrint) #> Some text. -- WRONG

Sebagai gantinya, Anda harus menyertakan {braces}, sebagai berikut:

<#
 if (ShouldPrint)
 {   //  "{" REQUIRED
#>
Some text.
<#
 }
#>

Blok kontrol ekspresi

Blok kontrol ekspresi digunakan untuk kode yang menyediakan string yang akan ditulis ke file output. Misalnya, dengan contoh di atas, Anda dapat mencetak nama atribut ke file output dengan memodifikasi blok kode sebagai berikut:

<#
    XmlDocument xDoc = new XmlDocument();
    xDoc.Load(@"E:\CSharp\Overview.xml");
    XmlAttributeCollection attributes = xDoc.Attributes;
    if (attributes != null)
    {
       foreach (XmlAttribute attr in attributes)
       {
#><#= attr.Name #><#
       }
    }
#>

Blok kontrol fitur kelas

Anda dapat menggunakan blok kontrol fitur kelas untuk menambahkan metode, properti, bidang, atau bahkan kelas berlapis ke templat teks Anda. Penggunaan blok fitur kelas yang paling umum adalah menyediakan fungsi pembantu untuk kode di bagian lain dari templat teks. Misalnya, blok fitur kelas berikut mengkapitalisasi huruf pertama dari nama atribut (atau, jika nama berisi spasi kosong, itu memanfaatkan huruf pertama dari setiap kata):

<#@ import namespace="System.Globalization" #>

<#+
    private string FixAttributeName(string name)
    {
        return CultureInfo.CurrentCulture.TextInfo.ToTitleCase(name);
    }
#>

Catatan

Blok kontrol fitur kelas tidak boleh diikuti oleh blok kontrol standar dalam file templat yang sama. Namun, pembatasan ini tidak berlaku untuk hasil penggunaan arahan <#@include#>. Setiap file yang disertakan dapat memiliki blok standar diikuti oleh blok fitur kelas.

Anda dapat membuat fungsi yang menghasilkan output dengan menyematkan blok teks dan ekspresi di dalam blok kontrol fitur kelas. Misalnya:

<#+
    private void OutputFixedAttributeName(string name)
    {
#>
 Attribute:  <#= CultureInfo.CurrentCulture.TextInfo.ToTitleCase(name) #>
<#+  // <<< Notice that this is also a class feature block.
    }
#>

Anda dapat memanggil fungsi ini dari blok standar atau dari blok fitur kelas lain:

<# foreach (Attribute attribute in item.Attributes)
{
  OutputFixedAttributeName(attribute.Name);
}
#>

Cara menggunakan blok kontrol

Semua kode di semua blok kontrol standar dan ekspresi dalam satu templat (termasuk semua kode dalam templat yang disertakan) digabungkan untuk membentuk metode TransformText() kode yang dihasilkan. (Untuk informasi selengkapnya tentang menyertakan templat teks lain dengan petunjuk include, lihat Petunjuk Templat Teks T4.)

Anda harus mengingat pertimbangan berikut saat menggunakan blok kontrol:

• Bahasa. Anda dapat menggunakan kode C# atau Visual Basic dalam templat teks. Bahasa defaultnya adalah C#, tetapi Anda dapat menentukan Visual Basic dengan parameter language petunjuk template. (Untuk informasi selengkapnya tentang petunjuk template, lihat Petunjuk Templat Teks T4.)

  Bahasa yang Anda gunakan dalam blok kontrol tidak ada hubungannya dengan bahasa atau format teks yang Anda hasilkan dalam templat teks. Anda dapat membuat C# dengan menggunakan kode Visual Basic atau sebaliknya.

  Anda hanya dapat menggunakan satu bahasa dalam templat teks tertentu, termasuk semua templat teks yang Anda sertakan dengan petunjuk include.

• Variabel lokal. Karena semua kode dalam blok kontrol standar dan ekspresi dalam templat teks dihasilkan sebagai metode tunggal, Anda harus memastikan bahwa tidak ada konflik dengan nama variabel lokal. Jika Anda menyertakan templat teks lainnya, Anda harus memastikan bahwa nama variabel unik di semua templat yang disertakan. Salah satu cara untuk memastikan hal ini adalah dengan menambahkan string ke setiap nama variabel lokal yang mengidentifikasi templat teks tempat string dideklarasikan.

  Ada baiknya juga menginisialisasi variabel lokal Anda ke nilai yang masuk akal ketika Anda mendeklarasikannya, terutama ketika Anda menyertakan beberapa templat teks.

• Bersarangnya blok kontrol. Blok kontrol mungkin tidak bersarang di dalam satu sama lain. Anda harus selalu menghentikan blok kontrol yang diberikan sebelum membuka blok kontrol lain. Misalnya, berikut ini memperlihatkan cara mencetak beberapa teks dalam blok ekspresi sebagai bagian dari blok kontrol standar.

  <#
  int x = 10;
  while (x-- > 0)
  {
  #>
  <#= x #>
  <# } #>
  

• Pemfaktoran ulang. Untuk menjaga templat teks Anda tetap pendek dan mudah dipahami, sangat disarankan agar Anda menghindari kode berulang baik dengan memperhitungkan kode yang dapat digunakan kembali ke dalam fungsi pembantu di blok fitur kelas atau dengan membuat kelas templat teks Anda sendiri yang mewarisi dari kelas Microsoft.VisualStudio.TextTemplating.TextTransformation.