CodeSmith 使用教程(16) 使用XMLProperty

在前面CodeSmith 使用教程(6): 基本语法-声明和使用属性 介绍了CodeSmith中使用属性的基本方法，模板中的属性是通过Property指令来定义。

CodeSmith 也支持使用XML文档来定义属性，可以把一些配置属性定义到XML文件中，定义XML的属性是使用XmlProperty来定义：

<%@ XmlProperty Name="PurchaseOrder" 
   Schema="PO.xsd" 
   Optional="False" 
   Category="Data" 
   Description="Purchase Order to generate packing list for." %> 

XmlProperty 指令可以有多个参数，除Name为必须的外，其它的参考都是可选的。

属性参数的介绍：

• Name：模版使用的参数的名称，必须为有效的模板语言名称，比如使用C#，Name必须为有效的C#变量名。但提供XML 的Schema文件时，这个变量的类型为一个XmlDocument实例。
• Schema：XML属性对应的Schema文件名，可以用来校验存放XML属性的XML文件是否有效，如果提供了Schema 文件，CodeSmith在代码模板中支持IntelliSense。
• Default：设置默认值。
• Category：用来说明这个属性在CodeSmith Explorer的属性面板中显示成什么类型，例如下拉选择、直接输入等。
• Description：在属性面板中对于这个属性的描述。
• Optional：设置这个属性是否是必须的，设置为True表明这个参数值可有可无，设置为False则这个参数必须有值。
• OnChanged 为属性发生变化时定义事件处理代码。
• RootElement： 指定XML根元素的相对路径。

本例使用CodeSmith自带的一个例子，使用PurchaseOrder.xsd ，XML 的定义如下：

<?xml version="1.0" encoding="utf-8"?> 
<xs:schema targetNamespace="http://www.codesmithtools.com/purchaseorder" 
elementFormDefault="qualified" 
xmlns="http://www.codesmithtools.com/purchaseorder" 
xmlns:xs="http://www.w3.org/2001/XMLSchema"> 
  <xs:element name="PurchaseOrder"> 
    <xs:complexType> 
      <xs:sequence> 
        <xs:element name="OrderDate" type="xs:string" minOccurs="1" maxOccurs="1" /> 
        <xs:element name="SubTotal" type="xs:string" minOccurs="1" maxOccurs="1" /> 
        <xs:element name="ShipCost" type="xs:string" minOccurs="0" maxOccurs="1" /> 
        <xs:element name="TotalCost" type="xs:string" minOccurs="1" maxOccurs="1" /> 
        <xs:element name="ShipTo" minOccurs="0" maxOccurs="1"> 
          <xs:complexType> 
            <xs:sequence> 
              <xs:element name="Line1" type="xs:string" minOccurs="0" maxOccurs="1" /> 
              <xs:element name="City" type="xs:string" minOccurs="0" maxOccurs="1" /> 
              <xs:element name="State" type="xs:string" minOccurs="0" maxOccurs="1" /> 
              <xs:element name="Zip" type="xs:string" minOccurs="0" maxOccurs="1" /> 
            </xs:sequence> 
            <xs:attribute name="Name" type="xs:string" /> 
          </xs:complexType> 
        </xs:element> 
        <xs:element name="Items" minOccurs="0" maxOccurs="1"> 
          <xs:complexType> 
            <xs:sequence> 
              <xs:element name="OrderedItem" minOccurs="0" maxOccurs="unbounded"> 
                <xs:complexType> 
                  <xs:sequence> 
                    <xs:element name="ItemName" type="xs:string" minOccurs="1" maxOccurs="1" /> 
                    <xs:element name="Description" type="xs:string" minOccurs="0" maxOccurs="1" /> 
                    <xs:element name="UnitPrice" type="xs:string" minOccurs="1" maxOccurs="1" /> 
                    <xs:element name="Quantity" type="xs:string" minOccurs="1" maxOccurs="1" /> 
                    <xs:element name="LineTotal" type="xs:string" minOccurs="1" maxOccurs="1" /> 
                  </xs:sequence> 
                </xs:complexType> 
              </xs:element> 
            </xs:sequence> 
          </xs:complexType> 
        </xs:element> 
      </xs:sequence> 
    </xs:complexType> 
  </xs:element> 
</xs:schema> 

与这个XML Schema配合使用的用来存放XML属性的XML文件为SamplePurchaseOrder.xml ，其定义如下：

<?xml version="1.0"?> 
<PurchaseOrder xmlns="http://www.codesmithtools.com/purchaseorder"> 
  <ShipTo Name="Eric J. Smith"> 
    <Line1>123 Test Dr.</Line1> 
    <City>Dallas</City> 
    <State>TX</State> 
    <Zip>75075</Zip> 
  </ShipTo> 
  <OrderDate>05-01-2003</OrderDate> 
  <Items> 
    <OrderedItem> 
      <ItemName>Item #1</ItemName> 
      <Description>Item #1 Description</Description> 
      <UnitPrice>5.45</UnitPrice> 
      <Quantity>3</Quantity> 
      <LineTotal>16.35</LineTotal> 
    </OrderedItem> 
    <OrderedItem> 
      <ItemName>Item #2</ItemName> 
      <Description>Item #2 Description</Description> 
      <UnitPrice>12.75</UnitPrice> 
      <Quantity>8</Quantity> 
      <LineTotal>102.00</LineTotal> 
    </OrderedItem> 
  </Items> 
  <SubTotal>45.23</SubTotal> 
  <ShipCost>5.23</ShipCost> 
  <TotalCost>50.46</TotalCost> 
</PurchaseOrder> 

定义一个简单的模板，把SamplePurchaseOrder.xml 中的内容重新输出，可以在代码模板中定义一个XMLProperty ，其Schema 指定为PurchaseOrder.xsd

<%-- 
This template demonstates using the XmlProperty directive 
--%> 
<%@ CodeTemplate Language="C#" TargetLanguage="Text" 
  Description="Demonstrates using the Xml serializer." %> 
<%@ XmlProperty 
   Name="MyPurchaseOrder" 
   Schema="PurchaseOrder.xsd" 
   Default="SamplePurchaseOrder.xml" %> 
This file generated by CodeSmith on <%= DateTime.Now.ToLongDateString() %> 
 
PurchaseOrder: 
	Address: 
		Name: <%= MyPurchaseOrder.ShipTo.Name %> 
		Line1: <%= MyPurchaseOrder.ShipTo.Line1 %> 
		City: <%= MyPurchaseOrder.ShipTo.City %> 
		State: <%= MyPurchaseOrder.ShipTo.State %> 
		Zip: <%= MyPurchaseOrder.ShipTo.Zip %> 
	OrderDate: <%= MyPurchaseOrder.OrderDate %> 
	Items: 
		<% for (int i = 0; i < MyPurchaseOrder.Items.Count; i++) { %> 
		<%= i %>: 
			ItemName: <%= MyPurchaseOrder.Items[i].ItemName %> 
			Description: <%= MyPurchaseOrder.Items[i].Description %> 
			UnitPrice: <%= MyPurchaseOrder.Items[i].UnitPrice %> 
			Quantity: <%= MyPurchaseOrder.Items[i].Quantity %> 
			LineTotal: <%= MyPurchaseOrder.Items[i].LineTotal %> 
		<% } %> 
	SubTotal: <%= MyPurchaseOrder.SubTotal %> 
	ShipCost: <%= MyPurchaseOrder.ShipCost %> 
	TotalCost: <%= MyPurchaseOrder.TotalCost %> 

模板中定义的XML属性名为MyPurchaseOrder 对应的Schema为PurchaseOrder.xsd ，因此在代码模板可以通过MyPurchaseOrder.ShipTo.Name 的格式来直接引用XML Schema中定义的元素，CoddSmith也支持IntelliSense。
运行该模板，首先需要为MyPurchaseOrder选择合适的XML文件：
如果选择的文件不符合指定的XML Schema，CodeSmith不允许选择该文件，本例使用预先定义的SamplePurchaseOrder.xml ，生成的文件如下：