CodeSmith的模版中的文法

本篇將介紹CodeSmith的模版中的文法。
標籤
        標籤一般出現在模板的頭部，被用做設定許多不同的屬性。
代碼模板的聲明（CodeTemplate Directive）
        這個是模板中唯一必須的聲明，包含一些模板特殊的屬性，包含模板使用的語言、產生的語言和一些對於模板的描述。
        例：<%@ CodeTemplate Language="C#" TargetLanguage="C#" Description="Generates a class." %>

參數的介紹：
    Language：在開發編寫模板時使用的語言，例如C#，VB.NET，Jscript等。
    TargetLanguage：只是對模板代碼的一個分類，不會影響產生的程式碼語言。是模板的一個屬性，說明模板要基於那種語言產生相應的代碼。例如你可以用CodeSmith從任何一種語言產生C#代碼。
    Description：對於模板的一些說明資訊，在CodeSmith Explorer中選中該模板時會顯示這裡的資訊。
    Inherits：所有CodeSmith模板預設繼承自CodeSmith.Engine.CodeTemplate，這個類提供模板使用的一些準系統，像ASP.NET頁面的Page類，這些被繼承的類的屬性可以被修改，但是這些新的類也必須繼承CodeSmith.Engine.CodeTemplate。CodeSmith也同樣可以找到這個類，當然你要引入一個組件包含這個類。
    Src：在某些方面Src和繼承Inherits比較相似，它們都允許你從其他的類包含一些功能進模板。這兩個屬性的區別是，Src可以讓類與你的模板被動態編譯，而Inherits僅允許你提供一個已經編譯好的類或組件。
    Debug：可以確定是否在模板中可以包含偵錯符號。如果將這個屬性設定為True，則可以使用System.Diagnostics.Debugger.Break()方法來設定斷點。
    LinePragmas：設定為True，模板的錯誤將被指向到模板的原始碼。設定為False，模板的錯誤將被指向到編譯的原始碼。

屬性的聲明（Property Directive）
        屬性被用做在模板運行時聲明一個使用的參數，例：<%@ Property Name="ClassName" Type="String" Default="Class1" Category="Context" Description="The name of the class to generate" Optional="true" %>

屬性參數的介紹：

    Name：模版使用的參數的名稱。
    Type：參數類型可以是任何.NET有效資料類型，例如簡單的String類型或者是CodeSmith的SchemaExplorer.DatabaseSchema類型。注意，類型必須是基底類別庫的類型，例如用String或者Int32代替string和int。
    Default ：設定預設值。
    Category ：用來說明這個屬性在CodeSmith Explorer的屬性面板中顯示成什麼類型，例如下拉選擇、直接輸入等。
    Description ：在屬性面板中對於這個屬性的描述。
    Optional ：設定這個屬性是否是必須的，設定為True表明這個參數值可有可無，設定為False則這個參數必須有值。
    Editor ：表明在屬性面板中輸入這個屬性的值時使用何種GUI（圖形介面編輯器）編輯器。
    EditorBase ：編輯器使用的基本類型，如果沒有被說明，UITypeEditor為預設編輯器。
    Serializer ：這塊我的水平不太會犯疑：）The serializer parameter specifies the IPropertySerializer type to use when serializing the properties values.  This is equivalent to using a [PropertySerializerAttribute].

XML屬性聲明（XmlProperty Directive）
例：
代碼標籤
       <% %>標籤
       可以放置任意數量的代碼在其中，但並不能直接輸出到模版中。

<% foreach (ColumnSchema column in SourceTable.Columns) { %>
<%= column.Name %>
<% } %>

<%= %>標籤

在模版中輸出一個字串。上例中的<%=column.Name%>

指令碼標籤

在這個標籤中可以包含一段代碼，但是他不直接影響輸出的模版。可以放置一些比較有協助的方法在其中，然後在模版的各個地方可以調用它。在指令碼標籤中必須包含這個參數runat=”template”，否則他會被處理成普通文本。

例：

 1 <script runat="template">
  2 private string GetColumnName(ColumnSchema cs)
  3 {
  4       return cs.Name;
  5 }
  6  </script>
  7 
  8  <% foreach (ColumnSchema cs in SourceTable.Columns) { %>
  9  <%= GetColumnName(cs) %>
10 <% } %>

 

使用標籤可以大量減少代碼，並使模版更加的易讀和一管理。

 

Include標籤

和ASP.NET一樣，可以在模版中包含一些文字檔，但同ASP.NET一樣它也不是總能達到你的目標。

例：

<!-- #include file="myfile.inc" -->

 

有時在多個模版中引用一個組件中的功能，調用其中的方法，這時我們引用組件。但有些情況下，適用Include標籤可以得到更好的效果。

Comment標籤

注釋標籤，在前邊已經做過介紹。

例：

<%-- This is a comment --%><%@ XmlProperty Name="EntityMap" Schema="EntityMap.xsd" Optional="False" Category="Context" Description="EntityMap XML file to base the output on." %>

XML屬性的參數：
    Name：名稱。
    Schema ：這個參數用來指定一個XSD檔案，建立一個強型別物件模型。如果這個計劃被指定，編譯器會嘗試分析這個XSD檔案並為這個計劃產生一個強型別物件模型，這樣可以在模版中使用強型別和智能與XML協同工作。如果這個計劃沒有被設定，這個參數將為XmlDocument類型並且將使用XML DOM去導航到一個XML內容並產生代碼。
    Category ：在CodeSmith屬性面板中的類別。
    Description ：描述。
    Optional ：這個參數是否是必須的，如果設定為True，則參數不是必須的，反之False則為必須的。在設定為False時，如果使用者沒有提供參數則CodeSmith不能繼續運行。

註冊的聲明（Register Directive）
    這個屬性通常被用作引入另一個模版檔案並與當前的模版檔案同時被編譯。這是一種使用子模版的互動方法。
    例：

<%@ Register Name="MySubTemplate" Template="MySubTemplate.cst" MergeProperties="True" ExcludeProperties="SomeExcludedPropertyName,SomeProperties*" %>

    模版一旦被註冊，就可以建立一個模版的執行個體，然後象這樣設定它的屬性：

 1 <script runat="template">
  2 public void OutputSubTemplate()
  3 {
  4    MySubTemplate mySubTemplate = new MySubTemplate();
  5 
  6    // set an individual properties value.
  7    mySubTemplate.SomeExcludedPropertyName =  "SomeValue";
  8    
  9    // copy all properties with matching name and type to the sub template instance.
10    this.CopyPropertiesTo(mySubTemplate);
11 
12    // render the template to the current templates Response object.
13    mySubTemplate.Render(this.Response);
14 
15    // render the template to a file.
16    mySubTemplate.RenderToFile("C:/SomeFile.txt");
17 }
18 </script>

註冊的參數：
    Name：代表被引入的模版的名稱。它可以被用作建立一個模版的執行個體。
    Template：被引入模版檔案的相對路徑，它可以與當前的模版一起被動態編譯。
    MergeProperties：設定成True時，所有被引用的面板的屬性將被動態添加到當前模版中。
    ExcludePorperties：當使用MergeProperties時，你可能不需要某些屬性被添加到當前模版中。將不需要的屬性以逗號分隔放在這裡，*號可以被用作萬用字元使用。

組件的聲明（Assembly Directive）
    用作在模版中引用一個外部部組件，或者包含一個編譯好的源檔案。
例：

<%@ Assembly Name="SchemaExplorer" %>

或

<%@ Assembly Src="MySourceFile.cs" %>

    CodeSmith自動載入一些不同的組件：System, System.Diagnostics, System.ComponentModel, Microsoft.VisualBasic, CodeSmith.Engine

組件的參數：
    Name：需要引用組件的名稱，組建必須存在於Global Assembly Cache，與CodeSmith在同一路徑下或與模版檔案在同一路徑下。
    Src：要包含檔案的相對路徑。

引入的聲明（Import Directive）
    在模版中引入一個命名空間，這個與VB.NET中的Imports和C#中的using相同。
    例：

<%@ Import Namespace="SchemaExplorer" %>

引入的參數：
    NameSpace：被引入的命名空間的名字。記住同時必須要載入包含這個命名空間的相應組件，除非這個組件是被預設載入的。