IBatisNet1.5 — 對應檔–Parameter Maps and Inline Parameters

一、Parameter Maps        
        首先來看一下ParameterMap的定義：<parameterMap id="parameterMapIdentifier" 
  [class="fullyQualifiedClassName, assembly|typeAlias"]
  [extends="[sqlMapNamespace.]parameterMapId"]>
  <parameter 
    property ="propertyName" 
    [column="columnName"]
    [direction="Input|Output|InputOutput"]
    [dbType="databaseType"] 
    [type="propertyCLRType"]
    [nullValue="nullValueReplacement"] 
    [size="columnSize"] 
    [precision="columnPrecision"] 
    [scale="columnScale"]  
    [typeHandler="fullyQualifiedClassName, assembly|typeAlias"]  
  <parameter   />
  <parameter   /> 
</parameterMap>

其中只有id這個屬性是必須的，其它都為可選。下面我們來看一個parameterMap在SQLMAP中的具體應用：<parameterMap id="insert-employee-param" class="Employees">
  <parameter property="id" />
  <parameter property="empcode"/>
</parameterMap>

<statement id="insertEmployee" parameterMap="insert-employee-param">
  insert into Employees (Id, EmpCode) values (?,?);
</statement>

注意：我們通常在statement中使用的parameterMap都是在當前DataMap中定義的，其實我們可以引用應用程式裡其它的DataMap中的parameterMap，但是前面要加上DataMap的namespace作為首碼。如：<statement id="insertEmployee" parameterMap="otherDataMap.insert-employee-param">
  insert into Employees (Id, EmpCode) values (?,?);
</statement>

1、<parameterMap> attributes
      <parameterMap>包括三個屬性：id(必須)，class(可選)，extends(可選)
      1.1、id
               是該parameterMap在當前DataMap中的唯一標識。
      1.2、class
               可以是property object或是IDictionary的執行個體，雖然class不是必須Attribute，但是我們最好去設定它的值，這樣可以協助我們驗證傳入參數的有效性並且能夠最佳化效能。
      1.3、extends
               這個在statement中已經說過了，大概的意思都是一樣的，這裡不再多說，parameterMap可以繼承其它DataMap中的parameterMap，繼承的時候要加上DataMap的namespace。
2、<parameter> Elements
      <parameterMap>有一個或多個<parameter>的子項目，用於匹配SQL Statement中的預留位置。
      2.1、property
               可以指定參數類中的一個屬性，也可以是IDictionary instance中的一項的名稱。它可以在SQL Statement中使用多次。
      2.2、column
               column通常用於定義預存程序中的參數名稱。
      2.3、direction
               用於指定參數的類型：輸出(Output)、輸入(Input)、雙向(InputOutput)。
      2.4、dbType
               指定參數對應於資料庫的列的類型。通常情況下僅當列為nullable時需要指定dbType。另外，對於一些特殊的資料類型如DateTime，在.net中只有System.DateTime一種時間的資料類型，而資料庫（MSSQL）中有DateTime,Date等，為了區分參數的類型，此時我們也需要指定dbType。
      2.5、type
               參數property在CLR中的類型。通常用於預存程序中的InputOutput和Output參數。
      2.6、nullValue
               當property的值為nullValue中設定的值的時候，就會將property的值替換為null。這個通常用於那些在程式中無法直接賦null值的資料類型，比如：int,double,float等類型。
      2.7、size
               一般用於設定property值的最大值。
      2.8、precision
               設定property值的精度。(?)
      2.9、scale
               設定property值的範圍。(?)
      2.10、typeHandler
               typeHandler允許使用者使用自訂的typeHandler,我們可以通過建立自訂的typeHandler來從資料庫中儲存或擷取Boolean、Guid類型的資料。關於自訂typeHandler，將在後面的文章中專門介紹。

二、Inline Parameter Maps
        如果使用Inline Parameter(內建參數)來代替parameterMap，我們需要為它添加額外的類別資訊。InlineParameter的文法允許你在有參數的sql statement中嵌入參數的property name,property type,column type和null value replacement。下面我們來一一樣本：
1、A <statement> using inline parameters
      

<statement id="insertEmployee" parameterClass="Employees">
  insert into Employees(Id,EmpCode)
  values (#id#, #empcode#)
</statement>

2、A <statement> using an inline parameter map with a type<statement id="insertEmployee" parameterClass="Employees">
  insert into Employees(Id,EmpCode)
  values (#id:int#, #empcode:varchar#)
</statement>

3、A <statement> using an inline parameter map with a null value replacement

<statement id="insertEmployee" parameterClass="Employees">
  insert into Employees(Id,EmpCode)
  values (#id:int:-99999#, #empcode:varchar#)
</statement>

4、A <statement> using alternate inline syntax with property, type, dbType, and null value replacement

<update id="UpdateEmployee" parameterClass="Employees">
      update Employees set
      empcode=#EmpCode#,
      empname=#EmpName#,
      email = #Email,type=string,dbType=Varchar,nullValue=no_email@provided.com#
      where id = #Id#
</update>

使用InlineParameter需注意幾點：
      不能單獨設定null value replacement，必須和dbType同時使用。
      對於既是參數又在resultMap中的null value,必須在resultMap中指定資料庫列的null value replacement.
      對於有大量類型描述元或null value replacement的複雜查詢，建議採用parameterMap.

三、Standard Type Parameters
      在實際的應用中，存在很多隻帶一個Int或是String型的參數的statement，這時候我們可以直接用standard library object(int ,string,etc)來作為Statement的參數，而不需要另外指定其它的object。如下：
A <statement> using standard type parameters

<update id="DeleteEmployee" parameterClass="int">
      Update Employees Set
        isdelete = 'y'
      Where id=#value#
</update>

四、Map or IDictionary Type Parameters
      我們還可以使用System.Collection.IDictionary的執行個體來作為Statement的參數類，最常用的也就是Hashtable了，如下：<update id="ChangePassword" parameterClass="Hashtable">
      Update Employees
      Set password=#Password#
      Where id=#Id#
</update>

注意：在我們傳入的hashtable中必須包括名為Password和Id的兩個鍵，其值的類型必須匹配它們對應的資料庫列的類型，否則將會出錯。

關於parameterMap就說到這裡。