CodeSmith基础（四）

        本文是翻译的第四篇，内容为在CodeSmith中使用的语法和标签的参考。

CodeSmith模板语法参考
        本文的目的是在编写一个CodeSmith模板时遇到的各种类型的变量和对象提供参考。本文的目的不是要介绍CodeSmith，如果您想快速了解CodeSmith请查看我翻译的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）
例：

<%@ 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：被引入的命名空间的名字。记住同时必须要加载包含这个命名空间的相应组件，除非这个组件是被默认加载的。