Warensoft Unity3D通信库使用向导4-SQL SERVER访问组件使用说明

huangfen2002

　　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命名空间中的类及其成员进行说明：

• 
  
  命名空间及类型说明
  

命名空间: 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(string key,T value)：关键字key等于值value，其中类型参数用于指明对应的字段的数据类型。
    
  • 
    
    NotEqualsTo(string key,T value) ：关键字key不等于值value，其中类型参数用于指明对应的字段的数据类型。
    
  • 
    
    GreaterThan(string key,T value) ：关键字key大于值value，其中类型参数用于指明对应的字段的数据类型。
    
  • 
    
    GreaterThanOrEqualsTo(string key,T value) ：关键字key大于等于值value，其中类型参数用于指明对应的字段的数据类型。
    
  • 
    
    SmallerThan(string key,T value) ：关键字key小于值value，其中类型参数用于指明对应的字段的数据类型。
    
  • 
    
    SmallerThanOrEqualsTo(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")
));