CodeSmith使用基礎教程 (4) — 控制檯與屬性編輯器

七、CodeSmith控制檯指南。

很多人僅僅知道CodeSmith像一個圖形應用程序，或者可能是一個Visual Studio的附件，但是通過CodeSmith的控制檯應用程序還有好多其他的使用方法。控制檯應用程序是很有價值的，因爲可以通過它去生成腳本，或者其他一些自動工具。這篇文檔的目的就是要告訴你怎樣使用它的控制檯應用程序並且如何去定義變量和參數。

Basic Usage

大多數情況下是用控制檯應用程序來創建一個模板，一個屬性文件，然後保存輸出的文件。這有一個很好的例子介紹將合併模版的處理過程放到一個過程中，就像使用NAnt工具。

首先我們要確定完成一個什麼樣的模版，爲這個模板創建一個什麼樣的XML屬性文件。XML屬性文件提供在執行模版是需要的各個屬性。生成一個屬性文件最簡單的方法是在CodeSmith Explorer中打開一個模版，填寫屬性，點擊生成按鈕generate，然後再點擊Save Property Set XML按鈕。這個按鈕會在點擊完生成按鈕後找到，在Save Output和Copy Output按鈕旁邊。然後系統提示輸入保存XML屬性文件的文件名，下面看一個ArrayList.cst模版創建的XML屬性文件。

 1<?xml version="1.0" encoding="us-ascii"?>
 2<codeSmith>
 3            <propertySet>
 4                        <property name="Accessibility">Public</property>
 5                        <property name="ClassName">PersonArray</property>
 6                        <property name="ItemType">Person</property>
 7                        <property name="ItemValueType">False</property>
 8                        <property name="ItemCustomSearch">False</property>
 9                        <property name="KeyName">PersonID</property>
10                        <property name="KeyType">int</property>
11                        <property name="IncludeInterfaces">True</property>
12                        <property name="IncludeNamespaces">False</property>
13            </propertySet>
14</codeSmith>

就像看到的一樣，也可以手動創建這個文件，但是使用CodeSmith Explorer會更簡便。

現在我們有了這個XML文件，我們繼續看一下如何去執行這個模版並是用控制檯工具保存結果。首先我們需要是用/template參數去聲明我們要是用的模版，像這樣：

C:/Program Files/CodeSmith/v3.0>cs /template:Samples/Collections/ArrayList.cst

在這個例子中我們使用了ArrayList.cst模版，它存儲在本地的Samples/Collections文件夾下。下一步我們要去聲明我們在最後一步需要創建的XML文件，我們是用/propertyset參數去實現。

C:/Program Files/CodeSmith/v3.0>cs /template:Samples/Collections/ArrayList.cst  /propertyset:PersonArray.xml

這個/property參數用來指定我們的XML屬性文件。最後一個我們需要用的參數是/output參數，用來指定輸出怎樣被保存。

C:/Program Files/CodeSmith/v3.0>cs /template:Samples/Collections/ArrayList.cst /propertyset:PersonArray.xml /out:test.cs

使用/out參數指定將結果輸出到一個叫test.cs文件中保存。執行這個命令後，模板將開始運行，使用屬性文件將結果輸出到test.cs文件保存。

這是大多數情況下有效使用控制檯。

 

Merging Output

在各種代碼生成中最大的挑戰就是將生成的代碼和開發人員編寫或修改的代碼區分開。控制檯對這個問題提供了一個有效的獨特的解決方案，使用一個指定的參數在當前已存在的代碼文件中需要將模板生成的代碼添加的地方指定一塊區域。

下面是一個簡單的代碼文件，包含了我們要添加生成代碼的區域。

1using System;
2
3namespace Entities
4{
5      GeneratedOrderEntity#region GeneratedOrderEntity
6 
7
8      #endregion  
9}

我們的目標是將DatabaseSchema/BusinessObject.cst模版生成的代碼添加到類文件的GeneratedOrderEntity區域中。和上一個例子一樣，使用CodeSmith console控制檯應用程序執行這個模版，但是這次要使用另一個參數merge。

C:/Program Files/CodeSmith/v3.0>cs /template:Samples/DatabaseSchema/BusinessObject.cst /propertyset:OrderEntity.xml /out:OrderEntity.cs /merge:InsertRegion= "RegionName=Sample Generated Region;Language=C#;"

使用merge參數我們可以指定區域的名稱，在這個例子中是GeneratedOrderEntity，然後控制檯應用程序將執行模版，並將結果添加到這個區域中。我們來看一下執行完這個指令後生成的代碼。

 1using System;
 2
 3namespace Infozerk.AuthServices.UnitTestSuite
 4{
 5      GeneratedOrderEntity#region GeneratedOrderEntity
 6      
 7
 8      Order#region Order
 9      /**//// <summary>
10      /// http://www.livebaby.cn.
11      /// </summary>
12      public class Order
13      {
14            protected int _id;
15            protected string _customerID = String.Empty;
16            protected int _employeeID;
17            protected DateTime _orderDate;
18            protected DateTime _requiredDate;
19            protected DateTime _shippedDate;
20            protected int _shipVia;
21
22--爲了簡短省略了類的其他部分就像看到的一樣，Order類被添加到了我們指定的區域中。在代碼文件中使用merge參數生成的內容在其他部分被修改或手寫後很容易重新再次生成而不會產生影響。

 

 

參數介紹Parameter Reference

 

Specifying Output

/out:<file>

指定從模版創建的輸出文件的名稱。

/out:default

指定這個文件被默認保存成模版是用的名稱。

/merge:<mergetype>=<init>

指定模版輸出的區域。可以簡寫爲/m

 

Specifying Input

/template:<file>

選擇要執行的模版，簡寫爲/t

/propertyset:<file>

生成代碼時需要使用的XML屬性文件。簡寫爲/p

 

Compiler Options

/debug[+|-]

指定模版需要包含的調試信息。（允許在運行模版時進行調試）

/tempfiles[+|-]

指定保留臨時文件。（如果在臨時文件上調試也可以）

 

Miscellaneous

/help

顯示幫助信息。

/nologo

禁止生成器版權信息。

八、編寫CodeSmith自定義屬性的編輯器（Writing Custom Property Editors）

        當你開始編寫自定義的CodeSmith模板時，很可能對於使用它的strings或integers屬性很滿意，但有時你會發現需要創建一個不同類型的屬性，可能是一個自定義的類型或者是.NET framework中但是在屬性面板中沒有提供的類型。在模板中去作這些很簡單，但是怎樣指定一個類型在運行模板時顯示在屬性面板中呢？例如創建了一個Person類並且具有很多不同的屬性，但是卻沒有辦法讓用戶去組裝這個類……除非創建一個自定義屬性編輯器。

        屬性面板提供了方法去編寫自定義的屬性編輯器，當用戶在面板上選擇一個屬性時可以激發相應的方法，同時也可以通過編寫代碼實現提示用戶輸入一個必要的值。下面我們舉個例子，創建一個接受組建的屬性並且是用影射循環貫串所有的類，是所有的類都可以使用它和它的方法，去創建一個NUnit測試基礎。（這句翻譯的不好，原文：As an example we are going to build a template which accepts an assembly as a property and then using reflection loops through all of the classes, and the methods of those classes, to build NUnit test stubs.）

        首先，我們來關注一下模板的組件屬性，暫且不看自定義編寫的代碼。模板的第一部分是一些聲明定義和屬性。將屬性放在腳本標籤中代替使用屬性聲明，在下一部分將看到這樣做的必要。

 1<%@ CodeTemplate Language="C#" TargetLanguage="C#" Description="Builds a class for each class in the assembly, and a test stub for every method." %>
 2
 3<%@ Import NameSpace="System.Reflection" %>
 4
 5<script runat="template">
 6
 7private Assembly assembly;
 8
 9public Assembly AssemblyToLoad
10{
11      get{return assembly;}
12      set{assembly = value;}
13}
14
15</script>

 

 

        然後我們爲組建assembly中的每一個類創建一個類，爲每一個類創建他的方法。然後直接將模板的輸出內容放入Visual Studio.NET，然後在編寫組件的單元測試時使用嚮導。

 1using System;
 2using NUnit.Framework;
 3
 4<%
 5      foreach(Type T in AssemblyToLoad.GetTypes())
 6      {
 7            if(T.IsClass)
 8            {
 9                  %>
10
11                  [TestFixture]
12                  public class <%=T.Name%>Tests
13                  {
14                  <%
15                              MethodInfo[] methods = T.GetMethods ( BindingFlags.Public | BindingFlags.Instance | BindingFlags.Static  );
16                              foreach(MethodInfo M in methods)
17                              {
18                                    %>
19
20                                    [Test]
21                                    public void <%=M.Name%>Test
22                                    {
23                                          //TODO Write this test
24                                    }                 
25                                    <%
26                              }
27
28                  %>}<%
29            }
30      }
31%>

 

 /Files/Bear-Study-Hard/AssemblyHelper.zip

        首先我們需要創建一個繼承UITypeEditor的類。

1public class AssemblyFilePicker : UITypeEditor
2{
3      public AssemblyFilePicker(): base()
4      {
5      }
6}

 

        關於UITypeEditor的說明請大家參看MSDN或Visual Studio.NET自帶幫助中的說明，其中有詳細的例子。

        然後我們需要重載UITypeEditor類的兩個不同的方法。第一個需要重載點的方法是GetEditStyle，這個方法是告訴屬性面板對於當前類型是用什麼類型的編輯器，在這個例子中我們設置編輯類型爲Modal。這樣大家可以在該屬性格子的右邊看到一個小按鈕，它將引發一個對話框等模式的對話（trigger a modal dialog）。這是我們的GetEditStyle方法：

1public override UITypeEditorEditStyle GetEditStyle(ITypeDescriptorContext context) 
2{
3      return UITypeEditorEditStyle.Modal;
4}

 

        其中的Modal爲顯示一個省略號按鈕。

 

        首先我們要從當前的服務和控件中得到一個參考，有了控件的參考我們可以通過它轉到ShowDialog方法。（原文：First we need to get a reference to the current service and control, we need the reference to the control so we can pass it to the ShowDialog method.）         然後我們創建一個openFileDialog類並填入適合的屬性。        然後我們通過控件的參考（reference）將對話框顯示給用戶。        下一步我們檢查用戶是否點擊了OK按鈕，如果點擊了，通過文件選擇對話框選擇文件後使用LoadForm方法加載這個組件，最後返回這個值。        這個值將被放在屬性面板中並可以被模板讀取，但是需要注意，在我們作這個之前要將組件import引入到模板中，並在模板中用一對屬性聲明。

 

1IWindowsFormsEditorService editorService = (IWindowsFormsEditorService)provider.GetService(typeof(IWindowsFormsEditorService));
2Control editorControl = editorService as Control;
3
4if (editorControl != null) 
5{

 

1OpenFileDialog openFileDialog = new OpenFileDialog();                         
2
3openFileDialog.CheckFileExists = true;
4openFileDialog.DefaultExt = ".dll";
5openFileDialog.Multiselect = false;
6openFileDialog.Title = "Select an Assembly:";
7openFileDialog.Filter = "Assembly Files | *.dll";

 

1DialogResult result = openFileDialog.ShowDialog(editorControl);

 

 1if (result == DialogResult.OK)
 2            {
 3Assembly assembly = Assembly.LoadFrom( openFileDialog.FileName ) ;
 4                  value = assembly; 
 5            }
 6            else
 7            {
 8                  value = null;
 9            }
10      }
11}
12
13return value;
14}

 

        加載這個模板我們僅需將這個組件assembly與模板放在同一目錄下，然後再模板中加入下面兩行代碼。

1<%@ Assembly Name="AssemblyHelper" %>
2<%@ Import NameSpace="AssemblyHelper" %>

 

 

        需要重載的另一個方法是EditValue方法，當用戶電擊屬性時會調用這個方法。按照我們需要加載的組件類型需要創建一個打開文件對話框（open file dialog）然後捕獲這個對話框，在屬性格子中返回對話框的結果。

1public override object EditValue(ITypeDescriptorContext context, IServiceProvider provider, object value)
2{
3
4if (provider != null) 
5{

 

        這個模板僅僅可以編譯通過，但是由於我們編寫顯示了一個類型屬性面板並不知道如何去操作它，所以我們沒有辦法自定義指定組件在加載時想要加載的組件。

        我們需要創建一個UITypeEditor，這是一個建立屬性面板是用的特殊屬性的類。UITypeEditor需要創建在一個和模板分離的組件中，我們是用Visual Studio創建這個類。