T4 Text Template ile dinamik olarak nasıl dosya oluşturabileceğimizi göreceğiz. Aslında EntityFramework’den aşina olduğumuz ama dosyalarına çoğu zaman müdahale etmediğimiz *.tt uzantılı dosyalar birer T4 metin şablonudur.
T4 Text Template
T4 Text Template Nasıl Oluşturulurdan önce çok basit şekilde .tt uzantılı dosya içerisindeki yazılan kodlar nasıl sonuca ulaşıyor 3 aşamada görelim bir şema üzerinde.
Yeni T4 Text Template Oluşturma
Hemen T4 anlatımına T4 Text Template nasıl oluşturabiliriz ile başlayalım projeye Projenize Solution Explorer penceresinden sağ tuş yapıp Add menüsü altındaki Add New Item‘a tıklayın çıkan şablon listesinden Text Template‘i seçin ve projenize ekleyin. Projenize ekledikten sonra .tt uzantılı bir dosyanın oluştuğunuz göreceksiniz. Eğer herhangi bir isim değişikliği yapmadıysanız TextTemplate1.tt adlı bir dosya oluşacaktır.
Dosya oluştuktan sonra alttakine benzer bir kod ile karşılaşacaksınız ve <#@ …. #> bu şekildeki tanımlamaların her bir satırına direktif diyoruz. Direktifleri ayrıntılı olarak farklı bir makalede ele alacağız.
Kod(TextTemplate1.tt)
1 2 3 4 5 6 | <#@ template debug="false" hostspecific="false" language="C#" #> <#@ assembly name="System.Core" #> <#@ import namespace="System.Linq" #> <#@ import namespace="System.Text" #> <#@ import namespace="System.Collections.Generic" #> <#@ output extension=".txt" #> |
Text Template dosyası oluşturduğunuzda dosya seçili iken property penceresinde Custom Tool özelliğinin TextTemplatingFileGenerator olmasına dikkat ediniz. Bu değer sayesinde Text Template File Generator derleme işlemini yapacak ve çıktı olarak output direktifindeki extension uzantısı ile kaydedilecek. Yani TextTemplate1.txt uzantılı dosya içine Generator sonucunda oluşan çıktı yazılacak. Bu dosya çıktısında boş bir .txt uzantılı dosya oluşturulacaktır çünkü içeriğe henüz hiçbirşey girmedik.
Metin blokları – Text blocks
Anlaşılması en basit kontrol bloğudur .tt uzantılı dosya içerisine yazılan tüm metinler çıktı dosyasına olduğu gibi yazılacaktır. Çok basit bir örnek ile görelim.
Kod(TextTemplate2.tt)
1 2 3 4 | <#@ template debug="false" hostspecific="false" language="C#" #> <#@ assembly name="System.Core" #> <#@ output extension=".txt" #> Merhaba |
Çıktı olarak tek satırlık basit bir .txt uzantılı dosya oluşturulacak.
Standart kontrol blokları – Standard control blocks
Şimdi for döngüsü ile 10 defa döngü değeri olan i değişkeninin her dönüşte karesini alacak metni Generator ile .txt uzantılı dosyaya yazılacak. Kodlarımızı <# … #> Standart Kontrol Blokları arasında kodlarımızı yazacağız farklı birkaç blok tanımları daha var sırasıyla bunlarıda göreceğiz. Şimdi standrt kontrol blokları arasında yazdığımız örneği inceleyelim.
Kod(TextTemplate3.tt)
1 2 3 4 5 6 7 8 9 10 11 12 13 | <#@ template debug="false" hostspecific="false" language="C#" #> <#@ assembly name="System.Core" #> <#@ output extension=".txt" #> <#int top = 10; for (int i = 0; i<=top; i++) { #> <#= i #>'in karesi <#= i*i #>. <# } #> |
Sonuç
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | 0'in karesi 0. 1'in karesi 1. 2'in karesi 4. 3'in karesi 9. 4'in karesi 16. 5'in karesi 25. 6'in karesi 36. 7'in karesi 49. 8'in karesi 64. 9'in karesi 81. 10'in karesi 100. |
İfade kontrol blokları – Expression control blocks
<#= … #> ifade kontrol blokları yazılan kodları derler ve string olarak alınan değer çıktı dosyasına(TextTemplate1.txt) yazılır. Örnek olarak <#= 2 + 3 #> şeklinde bir tanımlama yapılırsa ifade kontrol bloğu derlenip çıktı dosyasına 5 yazılacaktır. Bu ifade kontrol bloklarını zaten bir önceki örnekdede kullandık kontrol edebilirsiniz. Şimdi ifade kontrol bloğunu bir örnek üzerinde görelim ve çıktısını kontrol edelim.
Kod(TextTemplate4.tt)
1 2 3 4 5 6 7 8 9 10 11 12 | <#@ template debug="false" hostspecific="false" language="C#" #> <#@ assembly name="System.Core" #> <#@ output extension=".txt" #> <# for (int i = 0; i < 4; i++) { #> <#= i+1 #> kere merhaba. <# } #> |
Sonuç
1 2 3 4 | 1 kere merhaba. 2 kere merhaba. 3 kere merhaba. 4 kere merhaba. |
Sınıf özelliği kontrol blokları – Class feature control blocks
Sınıf özelliği kontrol blokları tanımlaması <#+ … #> şeklinde yapılmaktadır ve bu bloklar içerisine özellik(property) ve metod tanımlamaları yapılır tt uzantılı dosya içerisinde kullanılabilir kısacası çıktı oluşturmak için yardımcı metodlar ve özellikler(properties) oluşturabiliriz ve bunları kullanabiliriz hemen bu kontrol bloğu ile ilgili bir örnek yapıp çıktıyı kontrol edelim ve bilgimizi pekiştirelim.
Kod(TextTemplate5.tt)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | <#@ template debug="false" hostspecific="false" language="C#" #> <#@ assembly name="System.Core" #> <#@ output extension=".txt" #> Kareler: <# for (int i = 0; i < 4; i++) { #> <#= i + 1 #> sayısının karesi <#= Square(i+1) #> <# } #> Liste bitişi. <#+ // Sınıf özelliği bloğu int Square(int i) { return i*i; } #> |
Üstteki kodda görüldüğü gibi geri dönüş tipi int olan Square adında class feature control bloğu arasında bir metod tanımladık ve bu metodu ifade kontrol bloğu arasında kullandık.
Sonuç(TextTemplate1.txt)
1 2 3 4 5 6 | Kareler: 1 sayısının karesi 1 2 sayısının karesi 4 3 sayısının karesi 9 4 sayısının karesi 16 Liste bitişi. |
Sınıf özelliği blokları içerisinde metin blokları kullanabiliyoruz. Örnek üzerinden nasıl kullandığımızı görelim.
Kod(TextTemplate6.tt)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | <#@ template debug="false" hostspecific="false" language="C#" #> <#@ assembly name="System.Core" #> <#@ output extension=".txt" #> Karelerin Listesi: <# for (int i = 0; i < 4; i++) { Square(i); } #> Liste bitişi. <#+ // Sınıf özelliği bloğu void Square(int i) { #> <#= i #> sayısının karesi <#= i * i #> <#+ } #> |
Sonuç(TextTemplate1.txt)
1 2 3 4 5 6 | Karelerin Listesi: 0 sayısının karesi 0 1 sayısının karesi 1 2 sayısının karesi 4 3 sayısının karesi 9 Liste bitişi. |
Harici tanımlamarı kullanma
Assemblies – Kütüphaneler
Bu blok ile sıklıkla kullandığımız .NET kütüphaneleri(System.Xml, System.Core v.b.)’ni Text Teplate yapımıza dahil edip kütüphane özelliklerini kullanabiliyor olacağız. Ayrıca kendi .NET kütüphanelerinizide projenize dahil edebilirsiniz. Assembly tanımını visual studio’ya projemize referans eklemeyi olayına benzetebiliriz bu durumda kütüphane içerisinde namespaceleri kullanabiliyor olacağız. Hem sistem kütüphaneleri hemde kendi kütüphanelerinizi nasıl dahil edeceğiniz ile ilgili örnek altta verilmiştir.
Sistem kütüphaneleri için assembly tanım kullanımı.
1 | <#@ assembly name="System.Xml" #> |
Not: Varsayılan olarak System kütüphanesi metin şablonu içerisine dahil edilmektedir o yüzden System.IO, System.Text v.b. System altındaki isim alanlarını kullanabilmektesiniz.
Kendi kütüphaneleriniz için assembly tanım kullanımı
1 | <#@ assembly name="$(SolutionDir)kutuphane\Benim.dll" #> |
Üstteki örneğimizde $(SolutionDir) tanımı dikkatinizi çekmiş olabilir bu tanım makro diye adlandırılmaktadır aslında işlev olarak yer tutucudan bir farkı yoktur çok ayrıntılı değinmeyeceğiz makalenin devamında makrolar üzerinde durulacaktır. Şimdilik bu ve bunun gibi yer alan onlarca makronun sağladığı şey tanımladığınız makronun derleme esnasında makroya uygun yol, dosya adı, Proje Adı v.b. değerler ile değiştirilmesidir. $(SolutionDir) ile projenize ait solution dosyasının dizini dönmektedir.
Namespaces – İsim Alanları
Assemly ile Text Template içerisine eklediğimiz kütüphaneler içerisindeki isim alanlarını kullanmak için namespace tanımını kullanacağız bu tanım C# ile sınıf içerisinde yaptığımız kodlamada using kullanımı ile aynı işi yapmaktadır.
Assembly tanımı kısmında System.Xml adlı kütüphaneyi projemize dahil ettik böylece System.Xml adlı kütüphane içerisindeki System.Xml, System.Xml.Schema, System.Xml.Xsl v.b. isim alanlarını kullabiliyor olacağız metin şablonumuz içerisinde. Hemen bir örnek yapalım assembly ve namespace tanımı ile alakalı.
TextTemplate7.tt
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | <#@ template debug="false" hostspecific="false" language="C#" #> <#@ assembly name="System.Xml" #> <#@ import namespace="System.Xml" #> <#@ output extension=".xml" #> <# var xml = new XmlDocument(); var person = xml.CreateElement("Person"); person.AppendChild(CreateChildWithText(xml, "Murat")); xml.AppendChild(person); Write(xml.InnerXml); #> <#+ public XmlNode CreateChildWithText(XmlDocument doc, string text) { var node = doc.CreateElement("Name"); var xmlAttr = doc.CreateAttribute("Job"); xmlAttr.InnerText = "Software Developer"; node.Attributes.Append(xmlAttr); node.InnerText = text; return node; } #> |
Üstte standart kontrol bloğu ve sınıf özellikli blok içerisinde XmlDocument nesnesi ve alt nesnelerini kullandığımızı görüyorsunuz bu nesneleri kullanabiliyor olmam metin şablonuna assembly tanımı ile System.Xml kütüphanesini eklemiş olmamla ve namespace tanımı ilede System.Xml adlı isim alanını kullanıyor olmamla mümkün oldu. Ayrıca output direktifinde çıktı dosya uzantısının .xml olarak belirtilmiş olduğunu görüyorsunuz böylelikle bize üretilecek çıktı .xml uzantılı olacak. Şimdi üstteki kodun sonucunu görelim.
Bir diğer önemli noktada şudur ifade kontrol blokları kullanmadan çıktı dosyasına yazdırma işlemini Console Application‘da sıkça kullandığımız Write, WriteLine metodlarını kullanarak yazdırma işlemini gerçekleştirebilirsiniz.
Sonuç(TextTemplate1.xml)
1 2 3 | <Person> <Name Job="Software Developer">Murat</Name> </Person> |
Kod ve metin dahil etme
include direktifini kullanarak Text Template’imize kodlarımızı ve içeriklerimizi kolayca dahil edebiliriz böylelikle birçok kodumuzu birçok farklı yerde kullanma imkanımız olabilir ve kod okunurluğu noktasında iyileştirme sağlamış olabiliriz yada birçok yerde kullandığımız tekrar eden metin bloklarını yine bu yöntemle dahil edebiliriz hemen bir örnek ile durumu daha iyi anlamaya çalışalım.
Yapacağımız bu örnekte her bir javascript dosyası için bir metin şablonu oluşturduğumuzu varsayalım ve oluşturulacak her javascript dosyaları başında altta Header.txt içeriğindeki gibi bir içerik olduğunu varsayalım. Bunları sürekli sürekli metin şablonlarına yazmak yerine Header.txt adında bir dosya içerisinden include direktifi ile çekeceğiz.
Header.txt
1 2 3 4 5 | /** * Bu Header.txt dosyayı deneme amaçlı oluşturulmuştur. * Oluşturan: <#= Environment.UserName #> * Oluşturma Tarihi: <#= DateTime.Now.ToString("dd-MM-yyyy hh:mm:ss") #> */ |
Fark ettiyseniz üstteki kodumuzda <#= .. #> ifade blokları yer almaktadır include direktifi aldığı içeriği derlediği için .txt uzantılı dosya içerisindende bu blokları kolaylıkla kullanabilmekteyiz.
TextTemplate8.tt
1 2 3 4 5 | <#@ template debug="false" hostspecific="false" language="C#" #> <#@ assembly name="System.Xml" #> <#@ import namespace="System.Xml" #> <#@ output extension=".js" #> <#@ include file="Header.txt" #> |
Sonuç(TextTemplate1.js)
1 2 3 4 5 | /** * Bu Header.txt dosyayı deneme amaçlı oluşturulmuştur. * Oluşturan: Murat * Oluşturma Tarihi: 06-11-2016 03:40:42 */ |
Dosya yollarına ulaşma
Normalde bir dosyaya ulaşmak için direkt olarak bir yol girdiğinizde erişebileceksiniz dosyaya örnek bir dosya içerisindeki tüm metinleri okumak istediğinizde File.ReadAllText(“C:\Test.txt”) şeklinde bir kullanım ile dosya içeriğini okuyabilirsiniz. Fakat eğer dosya C dizini altında değilde çalışmış olduğumuz dizin altında ise o zaman burada yardımımıza 2-3 farklı yöntem yetişiyor bunlardan ilki daha önce makale içerisinde bahsettiğimiz ama detayına inmediğimiz makrolar, bir diğer ise direkt yol belirtebilirsiniz örnek: C:\ProjeKlasörüm\Test.txt şeklinde olabilir bir diğer yöntemde Host.ResolvePath(“Test.txt”) yöntemidir fakat bu yöntemi kullanabilmeniz için template direktifi kısmındaki hostspecific özelliğinde varsayılan olarak yer alan false değerini true yapmalısınız bu durumda bu özelliği kullanabilirsiniz.
TextTemplate9.tt
1 2 3 4 5 6 7 8 | <#@ template debug="false" hostspecific="true" language="C#" #> <#@ assembly name="System.Xml" #> <#@ import namespace="System.IO" #> <#@ output extension=".txt" #> <# var file = File.ReadAllText(Host.ResolvePath("Test.txt")); Write(file); #> |
Not: Host.ResolvePath(yol) metoduna girmiş olduğunuz yol yada dosya adına önek olarak .tt uzantılı dosyanız nerede ise o yol verilmektedir. Ayrıca hostspecific özelliğini true yapınca Host özelliği altında kullanabileceğimiz birçok metod ve özellik yer almaktadır bu özellikleri ve metodları ayrı bir makalede ele alacağız.
Sonuç
1 | Bu dosya içeriği Test.txt dosyasından geldi. |
Hata Raporlama
Visual Studio’da uygulama geliştirirken compile time‘da hata olunca hatalar Error List penceresinde gözükür ve proje compile edilmez. Ayrı durumu metin şablonu dosyamızdada geçerli Dosyayı kaydetmeye çalıştığımızda compile etmeye başlar eğer hata varsa hatayı Error List penceresine yazdırır. Kendi hatalarımızı bir Exception fırlatarak oluşturabileceğimiz gibi metin şablonuna özgü Error ve Warning metodlarını kullanarak Hata veya Uyarı bastırabiliriz ikisinin etkisi farklı compile time‘da Eğer Error kullandıysak metin şablonu compile edilmeyecek fakat Warning kullandıysak bir uyarı olarak Error List penceresine bastırılacak ve compile time‘a etkisi olmayacak.
Makrolar
| Makro | Açıklama |
|---|---|
| $(RemoteMachine) | Set to the value of the Remote Machine property on the Debug property page. See Changing Project Settings for a C/C++ Debug Configuration for more information. |
| $(Configuration) | Geçerli projenizin yapılandırma adını verir, örnek, “Debug”. |
| $(Platform) | Geçerli projenizin platformunu verir, örnek, “Win32”. |
| $(ParentName) | (Deprecated.) Name of the item containing this project item. This will be the parent folder name, or project name. |
| $(RootNameSpace) | Projenin ana isim alanını verir. |
| $(IntDir) | Path to the directory specified for intermediate files. If this is a relative path, intermediate files go to this path appended to the project directory. This path should have a trailing slash. This resolves to the value for the Intermediate Directory property. Do not use $(OutDir) to define this property. |
| $(OutDir) | Path to the output file directory. If this is a relative path, output files go to this path appended to the project directory. This path should have a trailing slash. This resolves to the value for the Output Directory property. Do not use $(IntDir) to define this property. |
| $(DevEnvDir) | Visual Studio uygulamasının yüklendiği dizini verir. (sürücü + yol) |
| $(InputDir) | (Deprecated; migrated.) The directory of the input file (defined as drive + path); includes the trailing backslash ‘\’. If the project is the input, then this macro is equivalent to $(ProjectDir). |
| $(InputPath) | (Deprecated; migrated.) The absolute path name of the input file (defined as drive + path + base name + file extension). If the project is the input, then this macro is equivalent to $(ProjectPath). |
| $(InputName) | (Deprecated; migrated.) The base name of the input file. If the project is the input, then this macro is equivalent to $(ProjectName). |
| $(InputFileName) | (Deprecated; migrated.) The file name of the input file (defined as base name + file extension). If the project is the input, then this macro is equivalent to $(ProjectFileName). |
| $(InputExt) | (Deprecated; migrated.) The file extension of the input file. It includes the ‘.’ before the file extension. If the project is the input, then this macro is equivalent to $(ProjectExt). |
| $(ProjectDir) | Projenin dizini (sürücü + yol). |
| $(ProjectPath) | Projenin net adresini verir (sürücü + yol + proje adı + dosya uzantısı). |
| $(ProjectName) | Projenizin temel adı. |
| $(ProjectFileName) | Projenizin dosya adı (temel adı + dosya uzantısı). |
| $(ProjectExt) | Projenizin uzantısını verir. |
| $(SolutionDir) | Solution dosyanızın yer aldığı dizini verir (sürücü + yol) |
| $(SolutionPath) | Solution dosya adı ve uzantısı ile beraber net yolu verir. (sürücü + yol + solution adı + dosya uzantısı). |
| $(SolutionName) | Solution dosyanızın uzantısız adını verir. |
| $(SolutionFileName) | Solution dosya adı uzantısı ile birlikte. (temel adı + dosya uzantısı). |
| $(SolutionExt) | Solution dosyanızın uzantısını verir. |
| $(TargetDir) | Geçerli olan yapılandırmaya ait derleme dizinini verir. |
| $(TargetPath) | Dosya adı ve uzantısı ile birlikte net yolu verir. (sürücü + yol + temel ad + dosya uzantısı). |
| $(TargetName) | The base name of the primary output file for the build. |
| $(TargetFileName) | Derleme sonucu oluşan dosya adı ve uzantısı ile birlikte. (temel ad+ dosya uzantısı). |
| $(TargetExt) | Derleme sonucu oluşan dosyanın uzantısını verir. |
| $(VSInstallDir) | The directory into which you installed Visual Studio. This property contains the version of the targeted Visual Studio, which might be different that the host Visual Studio. For example, when building with |
| $(VCInstallDir) | The directory into which you installed Visual C++. This property contains the version of the targeted Visual C++, which might be different that the host Visual Studio. For example, when building with |
| $(FrameworkDir) | .NET Framework dizinini verir. |
| $(FrameworkVersion) | The version of the .NET Framework used by Visual Studio. Combined with $(FrameworkDir), the full path to the version of the .NET Framework use by Visual Studio. |
| $(FrameworkSDKDir) | The directory into which you installed the .NET Framework. The .NET Framework could have been installed as part of Visual Studio or separately. |
| $(WebDeployPath) | The relative path from the web deployment root to where the project outputs belong. Returns the same value as RelativePath. |
| $(WebDeployRoot) | The absolute path to the location of <localhost>. For example, c:\inetpub\wwwroot. |
| $(SafeParentName) | (Deprecated.) The name of the immediate parent in valid name format. For example, a form is the parent of a .resx file. |
| $(SafeInputName) | (Deprecated.) The name of the file as a valid class name, minus file extension. |
| $(SafeRootNamespace) | (Deprecated.) The namespace name in which the project wizards will add code. This namespace name will only contain characters that would be permitted in a valid C++ identifier. |
| $(FxCopDir) | The path to the fxcop.cmd file. The fxcop.cmd file is not installed with all Visual C++ editions. |
Not: Eğer Visual Studio‘nuzda T4 Text Template için herhangi bir Syntax Çözümü yok ise o zaman ReSharper‘i ForTea adlı plugin ile kullanabilirsiniz yada eğer ücretsiz bir yöntem arıyorsanız tangible T4 Editor‘ü önerebilirim.
