Introduction to EntitySpaces

        EntitySpaces persistence layer and business object architecture for Microsoft .NET

EntitySpaces is an object-relational mapping tool, the architecture of EntitySpaces can be used when writing an ASP.NET, .NET Framework or .NET Compact Framework application. The architecture is provider/database independent, allowing developers to run the same binary code against any of the supported databases. EntitySpacesworks with both C# and VB.NET and uses no reflection and no XML files. EntitySpaces has a capability of Language Integrated Query (LINQ) support. EntitySpaces is 100% free, can be downloaded from here

I have been working with EntitySpaces 2009 and 2012 versions and found that EntitySpaces has a vast feature set and provider independence that make it dependable, reliable, robust, scalable, and manageable architecture.


EntitySpaces Features:

• Serialization
• Simple, yet powerful, dynamic queries
• Data manipulation via dynamic SQL or stored procedure
• Hierarchical Data Models (Uses foreign keys in database to build hierarchical object model)
• Nullable Types
• Design time data binding support for grids, detail forms and other controls in ASP.NET
• Abstract and Concrete Classes
• Data structure centric / Generated from database schema.
• Compact Framework Support 
• .NET Frameworks 2.0, 3.5, 4.0 support
• WCF Support in 2012 release.
• Script Services support to cater the Ajax calls (uses jSon as data format) in 2012 release.

EntitySpaces Providers List:

• Microsoft SQL Server
• Microsoft Access
• Oracle
• MySQL (Runs Under Mono)
• Sybase SQL Anywhere
• Postgre SQL
• SQLite
• VistaDB (Runs Under Mono)

In this post I will show you how the EntitySpaces 2012 reduces the development effort and makes the life easy for developers. I will highlight the key points and settings of EntitySpace 2012 and some code snippets with C# to begin with it.

Please see the getting started document of EntitySpaces 2012 for installation guidance.

After Successful Installation of EntitySpaces 2012 first you need to configure it with some basic settings that are listed below.

1 - Get Connected With Your Database :
1.1 -  Launch your Visual Studio (2005/2008/2010) you will find a the EntitySpaces 2012 Add-In under the Tools menu as shown below. 

EntitySapces Add-In For Visual Studio

You may launch the EntitySpaces directly from your programs list in Start menu.

 1.2 - Go to the Settings tab to configure your database connection.

• You will find the Connection tab under Settings tab
• Choose your desired driver from the Drivers dropdown list.

           
2 - Change The Default File Locations :

      2.1 - Go to the File Locations tab under the Settings tab to set the default file locations:
               In this tab you can set the deafult output files path, EntitySpaces code generation templates   
               I recommend to use it with deafult file locations settings.
               

EntitySpaces File Locations

               

3 - Change the Naming Conventions As Desired :

      3.1 - Go to the Naming Conventions tab under the Settings tab to set the default Naming 
               Conventions.  

• In this tab you can set the default Naming Conventions that best describe your project/development environment and/or standards.
• These settings allow you to change the naming convetions of your abstract, collection, contcrete, query, meta and proxy stub classes that will be generated by EntitySpace 2012
•  I recomment to use it as default.

EntitySpaces Naming Conventions

      
4 - MetaData Settings And Aliases:
     4.1 - Go to the MetaData tab under the EntitySpaces 2012 to view and change the meta data
              settings and aliases as desired.

• In this tab you can see the detailed hierarchichal database structure and can change the attributes names, indexes etc....             

EntitySpaces Meta Data Settings

      
5 - Mappings of Data Types:
     5.1 - Go to the Mappings tab under the EntitySpaces 2012 to view and change the mapping of
              data types between the Database Structure and .NET Framework. 

EntitySpaces Data Types Mapping

After all the configurations and settings mentioned above now you are ready to generate the  EntitySpaces 2012 code/classes.

6 - Temeplate Generation:
     6.1 - Go to the Template tab under the EntitySpaces 2012 to generate the template classes.
You can generate the MetadataMap for C#, Client Side Proxy/Stub, Rich Internet Application classes, WCF Service classes with complete operational and data contracts, WCF Service with jSon format support, web admin suite, Custom, and Generated Classes.

EntitySpaces Template Generation

In this post I will use only Custom and Generated Classes to begin with EntitySpaces 2012.

   

6.1 - Generated Classes:
The generated classes is the persistence layer of EntitySpaces 2012, that provides the data acquisition, manipulation, and retreival mechanism with the capability to handling the multiple connections and data providers. Generated classes contains the core mechanism of data structure defined in database, for each database table it will generate a file that contains 3 classes with complete list of attributes of a particular database table with a capability to implement the Nullable data storage mechanism/functionality.


6.2 - Custom Classes:
The custom classes are the business objects for EntitySpaces 2012. These will allow to accomodate the change in Database structure without change a single line of code. EntitySpaces allow us to write the custom/business logic in this layer with keeping the Generated Classes as they generated / without change.

7 - Begin With EntitySpaces Applicaion:
After generation of both Generated and Custom classes your solution will look like as a below picture.

Solution Explorer

7.1 - Configuration File Settings:
 It includes the connection string and other EntitySpaces dependecies. 

7.2 - Add EntitySpaces DLL References to your Solution:
 All the releated dll files could be found in  the below mentioned file path.
"C:\Program Files\EntitySpaces 2012\Runtimes\.NET x.x"  

EntitySpaces Dependencies

7.3 - Initialize The Loader on Application_Start Event in Global.asax:

7.4 - Data Manipulation With EntitySpaces 2012:

 Data maipulation is very simple with EntitySpaces 2012 due to it's strong feature set and vast  functionality for DML. What we need to do for data maipulation is just to paas the Entity object and call save method of this entity. The below mentjiod code snippet will illustrate further.

In above mentioned code snippet I have a esDataRowState to decide whether to create a new object for this particular entity or just update the existing one. For bulk insertion you may use the Collection
object and call the save method for that particular collection class in a same way. In below mentioned code snippet I will show you how to perform the delete operation with a collection of entity object.

In the above mentioned example I am using a Collection with a Query object to load the objects in my collection to delete. I am passing the Query object to Collection.Load method to load all the objects for deletion, now I am simply calling the Collection.MarkAllAs Deleted method to mark the objects as deleted and then calling the Save method to finally perform the delete operation.

7.5 - Implementation Of Transacion Control Mechanism In EntitySpaces 2012:

By using the EntitySpaces.Interfaces.esTransactionScope object we can implement the trasaction control mechnism in our DML to avoid the inconsistency that could be caused by network connection failure and/or any other interruption in network connection. Below metioned code snippet will illustrate the transaction control mechanism implementation.

 In above mentioned code I am performing my DML operations under the 
using(EntitySpaces.Interfaces.esTransactionScope) and using esTransactionScope.Complete method that will invoke the Commit command of Database, in case of any exception arise under the esTransactionScope theEntitySpaces 2012 will automatically invoke the RoleBack command of Database.

7.6 - Data Acquisition With DB Level Paging Implementation In EntitySpaces 2012:
          7.6.1 - Key Points to get the desired data set from database:
                  1 - Set the Collection.Query.es.CountAll to true.
                  2 - Set the Collection.Query.es.PageNumber to you desired page number.
                  3 - Set the Collection.Query.es.PageSize to your desired page size.
                  4 - Invoke the Collection.Query.OrderBy method


The below mentioned code snippet will illustrate the  data acquisition with DB level paging implementation inEntitySpaces 2012.

Post by Kashif Akhtar