Skip to end of metadata
Go to start of metadata

Creating entity model and services that support your enterprise mobile application should be simple and manageable. Microsoft .NET already provides the technology to create the entity model and services using ASP.NET Entity Framework and ASP.NET Web API. To learn more about these technologies, refer to the following links.

The entity model and services generated with these tools are only capable to handle basic CRUD operation as you can learn from Accessing Web API Controller. To support more advanced scenarios typically required in enterprise apps, you will have to write additional code which is tedious and less efficient as you deal with large entity sets.

On this page:

Crosslight ships with a built-in entity data services for both client and server platforms which enable you to rapidly implement advanced data management such as data tracking, data validation, data synchronization, and batch save changes. To help you easily create entity models that comply to Crosslight's entity services, Crosslight provides Entity Designer Extensions which is integrated directly to Visual Studio's entity model designer. The extension automatically generates entity models that support data tracking, data synchronization, multiple time zone support and many more. Furthermore, the extension can also automatically generate Web API Controller that will serve as your enterprise data service.

Crosslight Entity Designer Extensions is extensions module for Visual Studio's Entity Designer. The following are the list of supported Visual Studio version.

  • Visual Studio 2012
  • Visual Studio 2013
  • Visual Studio 2015
For an overview of Crosslight Entity Services, see Enterprise Data Access.

Creating Entity Model And Services

Before creating an entity model, you need to ensure that the Intersoft WebApi EDM Extensions for NET 4.5 extension is installed as shown in the following figure. By default, the extension is automatically installed during installation.

In case you cannot find the extension in the list, you can install it manually by locating the Crosslight installation folder at C:\Program Files\Intersoft Solutions\[Crosslight Folder]\bin for x86 environment or C:\Program Files (x86)\Intersoft Solutions\[Crosslight Folder]\bin for x64 environment. In this folder, run Intersoft.VisualStudio.OM.Designer.11.0.vsix for Visual Studio 2012 or Intersoft.VisualStudio.OM.Designer.12.0.vsix for Visual Studio 2013 or Intersoft.VisualStudio.OM.Designer.14.0.vsix for Visual Studio 2015.

Next, you can start creating your entity model by adding a new item to your project in Visual Studio such as shown in the following figure.

You can select either  ADO.NET Entity Data Model or Intersoft Entity Data Model. Both actually do the same thing, if you're using ADO.NET Entity Data Model, you need to turn on the Intersoft WebAPI code generation manually, while the Intersoft Entity Data Model already have the settings turn on by default.

After you created a new entity model using Crosslight entity designer, you will get something similar to the following figure.

In the property window, you can see that there are several configuration under Intersoft WebAPI EDM Extension group

  • IntersoftWebApi Enabled
  • Code Generation Version
  • Generate Entity Context
  • Generate Entity Models
  • Generate Entity Controller
  • Generate Entity Repository
  • Allow Multipart Media
  • Optimistic Concurrency Strategy

This configuration will determine whether the Entity Designer Extensions is enabled, which code that will be automatically generated and using which code generator.

The Crosslight Entity Designer extends the Visual Studio designer by adding new properties under the Intersoft WebAPI EDM Extension category. You can find different kind of Crosslight extended properties based on the selection in the designer. There are three kind of selection which are: domain context, entity, and property.

Generating Entity Context

Entity context is a class that manages the entity objects at runtime which includes retrieving data from database and persisting data to database. Entity context is a concept of ASP.NET Entity Framework which comes with .NET Framework 4.5 by default. Crosslight entity services supports both Entity Framework version 5 and 6.

Generating an entity context is simple. You only need to set the Generate Entity Context property at the domain context level to true as follows.

This setting will generate a file called [EntityModel] and it will generate the entity context as follows.

Generating Entity Model

Crosslight provides built-in entity services for advanced data management at the client side. To use the entity services, the entity model must derive from EntityBase class and all the properties must have EntityProperty definition for each column it represents.

Similar to entity context, you can easily generate the entity model by simply setting the Generate Entity Model property at the domain context level to true as follows.

This setting will generate a file called [EntityModel].tt and it will generate the entity model as follows.

If you have Views or Stored Procedures, it will also create the models that support the view query and stored procedure query.

After the model is generated, the files will be linked to the existing Portable Class Library (PCL) project under Domain Models folder. If you have multiple portable projects, you will be prompted to select which project you want the model to be linked. The target project should be your Crosslight Core project that holds the shared application and user interaction logic.

Unlike entity context, there are several configurations that you can set when generating entity model. These configurations allow you to add additional metadata that will help you when dealing with the following scenarios:

  • Incremental Refresh (also known as Pull To Refresh)
  • Data Synchronization
  • Multiple Time Zone Support

Incremental Refresh Metadata

Incremental refresh is a scenario where you retrieve data based on last retrieved date. This scenario is commonly seen in application that uses pull to refresh to retrieve new data.

Incremental refresh metadata allows Intersoft Application Framework to automatically perform pull to refresh scenario on specific view. To learn more about how to enable pull to refresh using Intersoft Application Framework, see Enabling Pull to Refresh.

To specify incremental refresh metadata, set the Increment Date Property value at the entity model level such as follow.

This setting will add the following metadata in your generated entity model.

Data Synchronization Metadata

Data synchronization is a scenario where you retrieve data from online repository that have not been synchronized to local data repository and vice versa. To perform data synchronization you data need to have the following metadata embed in your table.

  • Synchronization Date Property
    Used to identify which data that haven't been synced.
  • Logical Delete Property
    Used to identify which records already been deleted.
  • Synchronization State Property
    Used to store additional synchronization state. For example, key-mapping for temporary id and actual id when processing new records. 

Crosslight Enterprise App Framework already provides built-in mechanism to handle data synchronization that leverages these data synchronization metadata. To learn more how to enable data synchronization, see Enabling Data Synchronization.

To specify the data synchronization metadata, set the Synchronized Date, Logical Delete and Synchronization State property at the entity model level as follow.

This setting will add the following metadata in your generated entity model.

Multiple Time Zone Metadata

One of the key challenges in building successful data-driven mobile apps is the consideration of multiple users who access and make changes to the data in different time zone. Consider a user posted a comment on 8:00 AM GMT+7, the app should smartly display the comment as 11:00 AM on other user's devices located in GMT+10 timezone.

The best practice to address this challenge is to convert the date/time value to UTC+0 time when sending the data to the data service. Upon retrieval, the UTC+0 value will be converted back to the local time zone respective to the setting in each device.

Crosslight provides a way to automatically convert date/time values to UTC+0 by applying DateTimeSerialization attribute on your entity model property. To learn more about multiple time zone concept, see Multiple Time Zone Support.

Instead of manually applying the attribute, you can easily set the DateTime Serialization Mode property using the designer extensions. Simply set the property value to Utc to apply the automatic date time conversion such as follows.

This setting will add the following metadata in your generated entity model.

Generating Entity Controller

The server-side counter part of Crosslight entity services is built around the ASP.NET Web API technology in conjunction with ASP.NET MVC. Unlike the entity controller generated by Web API, the entity controller generated by Entity Designer Extensions will include all entities defined in your entity model which greatly reduce code redundancy and increase development efficiency. Furthermore, the generated entity controllers are automatically configured to support OData query and returns optimized result for enterprise data operation.

Crosslight v4 introduce a new ApiController<TEntityContext> class that provides better extensibility for your application. Originally Crosslight Entity Designer will generate a entity controller that extends from ApiController class. You can opted to use the new ApiController<TEntityContext> class by changing the Code Generation Version to V4.

The default value for Code Generation Version is still set to V3 for compatibility purposes.

Similar to entity context, generating entity models requires just a simple property set, that is by setting the Generate Entity Controller property at domain context level to true such as follows.

This setting will generate a file called [EntityModel] and it will generate the API Controller as follows.

If you set the Code Generation Version to V4, you will get the following code.

As seen in the code above, the V4 generated code gives you more flexibility to override certain processes through the new ApiController<TEntity> base class. One of the most common scenarios is to intercept the save or synchronize process for better error handling, or perhaps you would like to perform some performance and error logging. In this case, you can simply override the SaveChangesCore method in a new partial class. This allows the generated code to remain unchanged, while giving you flexibility to implement new behaviors through methods override in a partial class.

If you enable Data Synchronization Metadata in any of the entity, the entity controller will generate a new method called SynchronizeChanges.

This method will be used to perform save pending changes and querying new data based on last synchronized date.

If you create the EDMX in a .NET Class Library project, the generated Entity Controller will be excluded in build action, and there will be a linked file to existing Web API project.

If you do not have existing Web API project, you will need to manually add the link into your Web API project.

By default it will generate data access for all entities defined in EDMX. You can remove the unwanted entities from Entity Controller by setting the Generate Controller property to False at Entity Model level as follows.

Allow Multipart Media

If your apps require file upload functionality which should be sent along with data in one single request, you can set the Allow Multi Part Media property at the domain context level to true.

This setting will change the generated entity controller as follows.

Optimistic Concurrency Strategy

Another thing that you can control from entity controller is how it handles concurrency issue when merging conflict arise.

You can change the optimistic concurrency handling by setting the Optimistic Concurrency Strategy property at domain context level as follows.

This setting will change the generated entity controller as follows.

Generating Entity Repository

If you are using Intersoft Application Framework, you are required to create the entity repository to perform data access to an entity. This is a mandatory process to comply with the repository design pattern implemented in Intersoft Application Framework. To learn more about repository pattern, see Repository Pattern.

To automatically generate the entity repository for your entities, you need to set the Generate Entity Repository property at domain context level to true such as follows.

In addition, you can also customize the type of repository to be used in all generated entities by setting the Entity Repository Type property.

By default, entity repository will be generated for all entities defined in EDMX. To remove the repository generation for a specific entity, simply set the Generate Repository property of the entity to false.