Warensoft Unity3D通信庫使用向導4-SQL SERVER訪問組件使用說明

Warensoft Unity3D通信庫使用向導4-SQL SERVER訪問組件使用說明

(作者:warensoft,有問題請聯系warensoft@163.com)

在前一節《warensoft unity3d通信庫使用向導3-建立WarensoftDataService》中已經說明如何配置Warensoft Data Service，從本節開始，將說明如果利用Warensoft Unity3D通信庫中的SQL SERVER組件和Warensoft Data Service交互以實現Unity3D 直接訪問SQL SERVER。我們首先對Warensoft.Communication.Client.DataClient命名空間中的類及其成員進行說明：

1. 命名空間及類型說明

命名空間: Warensoft.Unity.Communication.Client.DataClient
DataContext 類	該類通過Http協議對SqlServer連接進行管理.該類包含了所連接數據庫中的所有數據表的影射,另外還提供了對這些表數據的增、刪、改、查等功能。
DataEntity 類	數據實體類，代表一條數據記錄
DataEntitySet 類	數據實體集合類，代表一個數據表
DataProperty 類	數據屬性類，代表一個數據行中的數據列（字段）
DataPropertySet 類	數據屬性集合類，代表一個數據行中所有的數據列（字段）
DataQuery 類	該類為SQL SERVER數據查詢提供了許多構建方法，利用該類構建出來的查詢，會被傳送到Warensoft DataService服務器，并且被解析成數據庫可以識別的SQL語句

DataContext類

• 該類結構圖如下所示：

  

• 公開屬性說明：
  • SchemaLoaded：該屬性用于說明，當前連接所對應的數據庫中的表結構（Schema）是否已經加載完畢，如果已經加載完畢，可以利用DataContext實現對數據庫的增、刪、改、查。如果想實現表結構加載完畢的自動通知，請注冊SchemaLoadCompleted事件。
  • ServiceUrl：該屬性用于獲取對應的Warensoft Data Service的服務地址。
  • Tables：用于獲取該連接中所有表的集合，用戶可以通過表名（字符串）方式對數據表進行索引。
• 公開事件說明
  • Error：當數據連接或查詢出現錯誤時觸發
  • SchemaLoadCompleted：當數據連接中的數據表結構加載完畢時觸發。當該事件觸發時，DataContext只加載數據表結構，其中不包含數據。該事件是在某一次Update中觸發的，因此，對于Unity3D是線程安全的。
• 公開方法說明
  • DataContext(string url)：構造方法，其中參數用于指明Warensoft Data Service中的服務地址。注意：該類型的構造請不要直接在代碼中通過new方式構造，應當使用UnityCommunicationManager.CreateDataContext方法。
  • SaveChanges()：用于保存所有的增、刪、改操作，數據同步策略為"客戶端優先（后來者優先）"。如果希望指明數據同步策略，請使用其重載形式。
  • SaveChanges(RefreshMode mode)：用于保存所有的增、刪、改操作。其中的參數為RefreshMode枚舉類型，用于指明數據同步策略，其中包括兩種可選策略1.RefreshMode.ClientWins, 客戶端優先（后來者優先），2.RefreshMode.StoreWins，服務器優先（先來都優先）

DataEntity類

• 該類結構圖如下所示：

  

• 公開屬性說明
  • Properties：用于獲取該實體（數據行）中所有的字段（數據列）的集合。該集合類型可以通過["字段名"]形式進行索引并取出某一個字段對應的值。
  • State：用于獲取該實體（數據行）的修改狀態，該狀態通過一個EntityState枚舉類型來表示，該枚舉中包括Changed，Added，Deleted，Unchanged四個值。
  • TableName：用于獲取該實體現在表的表名。
  • this[string column]：索引器，用于通過指定字段名來直接取出該字段對應的值。
• 公開方法說明
  • DataEntity()：構造方法，該類的構造方法不可用，如果要創建一個新添加的數據實體，請使用DataEntitySet.NewEntity()方法
  • AcceptChanges()：用于確定對該實體的修改，該方法被調用后，該實體的State屬性會被重置為Unchanged，在相關聯的DataContext的SaveChanges方法被調用時，不會對該實體進行提交。
  • Delete()：將該實體的State置為Deleted，如果某一個實體的Delete()方法被調用后，該實體并不會立即被從內存中移除，但是不會出現在該實體所在數據表的可用行集合中，直到該實體所在的DataContext的SaveChanges方法被成功調用后，該實體才會從內存中移除。

  ?

DataEntitySet類

• 該類結構圖如下所示：

  

• 公開屬性說明
  • Count:獲取該實體集所代表的數據表中，所擁有的數據實體（數據行）的數量。
  • Entities：用于獲取該實體集（數據表）中所有的實體對象（數據行）。
  • TableName：用于獲取該實體集（數據表）所對應的數據表的表名。
• 公開方法說明
  • AcceptChanges()：將該實體集（數據表）中所有的實體（數據行）的State重置為Unchanged。
  • Add(DataEntity item)：將新建立的數據實體，添加到該實體集（數據表）中，其中參數item必須是由該實體集實例的NewEntity()方法所創建的，否則會拋出異常。新加入的實體的State會被標記為Added。此操作將只影響客戶端內存數據，當該實體集所在的DataContext的SaveChanges方法被調用后，數據才會被真正插入到數據庫中。
  • Clear()：清空該實體集中所有的數據。該操作只影響客戶端內存數據，當該實體集所在的DataContext的SaveChanges方法被調用后，數據庫不會產生任何影響。
  • Contains（DataEntity item）:判斷該實體集中是否已經包含指定項。
  • LoadAsync(Action fillAsyncCallback)：異步加載實體集中的數據實體（數據行）。其中參數fillAsyncCallback是異步加載完畢后的回調方法。請謹慎使用該方法，因為該方法會將對應服務器數據表中所有的數據都加載到客戶端中，建議使用其重載形式，并進行帶有條件的異步加載。
  • LoadAsync(Action fillAsyncCallback,DataQuery query)：異步加載實體集中的數據實體（數據行）。其中參數fillAsyncCallback是異步加載完畢后的回調方法，參數query為本次加載時的查詢條件。
  • NewEntity()：該方法用于創建一個新的DataEntity實例，該DataEntity實例，與該實體集具備相同數據表結構。

DataProperty類

• 該類結構圖如下所示：

  

• 公開屬性說明
  • ColumnName：用于獲取該字段名稱。
  • IsPrimaryKey：指示該字段是否為主鍵
  • Value：用于獲取該字段對應的值。
  • OriginalValue：用于獲取該字段修改之前的原始值，該字段在初始化時，Value與OriginalValue的值相同，如果該字段的值發生改變，則Value改變，OriginalValue值保持不變，直到DataContext的SaveChanges方法被成功調用后，OriginalValue的值才會與Value的值相同。

  ?

DataPropertySet類

• 該類結構圖如下所示：

  

• 公開屬性說明
  • Count：屬性集合（字段集合）中所擁有的屬性的數量。
  • this[int index]:索引，通過序號對指定屬性進行查找
  • this[string columnName]：索引，通過字段名對指定屬性進行查找
• 分開方法說明
  • 所有方法均為內部使用，不公開

  ?

DataQuery類

• 該類結構圖如下所示：

  

• 公開屬性說明
  • 所有屬性均為內部使用，不公開
• 公開方法說明
  • static And(DataQuery q1,DataQuery q2)：該靜態方法用于對兩個查詢進行And操作。
  • static Or(DataQuery q1,DataQuery q2)：該靜態方法用于對兩個查詢進行Or操作。
  • EqualsTo<T>(string key,T value)：關鍵字key等于值value，其中類型參數用于指明對應的字段的數據類型。
  • NotEqualsTo<T>(string key,T value) ：關鍵字key不等于值value，其中類型參數用于指明對應的字段的數據類型。
  • GreaterThan<T>(string key,T value) ：關鍵字key大于值value，其中類型參數用于指明對應的字段的數據類型。
  • GreaterThanOrEqualsTo<T>(string key,T value) ：關鍵字key大于等于值value，其中類型參數用于指明對應的字段的數據類型。
  • SmallerThan<T>(string key,T value) ：關鍵字key小于值value，其中類型參數用于指明對應的字段的數據類型。
  • SmallerThanOrEqualsTo<T>(string key,T value) ：關鍵字key小于等于值value，其中類型參數用于指明對應的字段的數據類型。
  • OrderBy(string key) ：按照指定關鍵字進行升序排序。
  • OrderByDescending(string key)：按照指定關鍵字進行降序排序。
  • Skip(int count)：在查詢時，按照count的值跨過指定行數。
  • Take(int count)：在查詢時，從查詢結果集中取count條記錄。相當于SQL SERVER中的TOP操作。
• 目前DataQuery中支持查詢的數據類型
  • Guid
  • byte
  • short
  • int
  • long
  • ushort
  • uint
  • ulong
  • double
  • float
  • decimal
  • bool
  • string

如何利用DataQuery構建復合查詢

DataQuery可以用于構建常見的SQL查詢，具備做法請參考下面代碼：

?

//查找Customers表中所有CustomerID為ALFKI的記錄this.context.Tables["Customers"].LoadAsync(() =>{//加載完畢

},(new DataQuery()).EqualsTo("CustomerID","ALFKI"));//查找Customers表中所有CustomerID不是ALFKI的記錄this.context.Tables["Customers"].LoadAsync(() =>{//加載完畢

}, (new DataQuery()).NotEqualsTo("Country", "US"));//查找Products表中所有UnitPrice大于10的記錄this.context.Tables["Products"].LoadAsync(() =>{//加載完畢

}, (new DataQuery()).GreaterThan("UnitPrice",10f));//查找Products表中所有UnitPrice小于等于10的記錄this.context.Tables["Products"].LoadAsync(() =>{//加載完畢

}, (new DataQuery()).SmallerThanOrEqualsTo("UnitPrice", 10f));//查找Products表中所有UnitPrice小于等于10的記錄//返回的結果集按ProductID進行升序排序this.context.Tables["Products"].LoadAsync(() =>{//加載完畢

}, (new DataQuery()).SmallerThanOrEqualsTo("UnitPrice", 10f).OrderBy("ProductID"));//查找Products表中所有UnitPrice小于等于10的記錄//返回的結果集按ProductID進行降序排序this.context.Tables["Products"].LoadAsync(() =>{//加載完畢

}, (new DataQuery()).SmallerThanOrEqualsTo("UnitPrice", 10f).OrderByDescending("ProductID"));//查找Products表中所有UnitPrice大于10的記錄//跨過前10條記錄再取前5條記錄//該查詢方法可以用于分頁操作this.context.Tables["Products"].LoadAsync(() =>{//加載完畢

}, (new DataQuery()).GreaterThan("UnitPrice", 10f).Skip(10).Take(5));//獲取Products表中所有Discontinued為true 并且UnitPrice大于20的記錄this.context.Tables["Products"].LoadAsync(() =>{//加載完畢

},(new DataQuery()).EqualsTo("Discontinued", true).GreaterThan("UnitPrice", 20f));//And操作示例//獲取Products表中所有Discontinued為true 并且UnitPrice大于20的記錄//該And操作與前一個示例的查詢過程等效this.context.Tables["Products"].LoadAsync(() =>{//加載完畢

},DataQuery.And((new DataQuery()).EqualsTo ("Discontinued",true),(new DataQuery()).GreaterThan("UnitPrice",20f)));//Or操作示例//獲取Customers表中，CustomerID為ALFKI或者Warensoft的所有記錄//該操作將返回兩條記錄this.context.Tables["Customers"].LoadAsync(() =>{//加載完畢

},DataQuery.Or((new DataQuery()).EqualsTo("CustomerID", "ALFKI"),(new DataQuery()).EqualsTo("CustomerID", "Warensoft")));

?

?

?