Skip to end of metadata
Go to start of metadata

Working with data in client side can be tedious if you are using a simple POCO object, particularly when your apps need to support data editing and changes tracking. In such case, you will need to manually store the entity information such as the entity state, original values, current values and editing values.

Without entity information, advanced data operations such as sand-box editing operation cannot be easily achieved, let alone tracking changes or cancelation that might occur during user interaction.

Crosslight provides a comprehensive component called EntityContainer to support many of the advanced features required in business apps.

On this page:

Tracking Changes with Entity Container

EntityContainer allows you to track changes to the entity stored in the container. The entity stored in the container must inherit from EntityBase and have complete EntityProperty definition such as follows.

The EntityProperty definitions allow the entity container to do the following operations:

  • Create and finalize temporary auto increment id for auto increment id column.
  • Create and maintain navigation property's reference to related entity.
  • Define the value type and default value for each property.

Tracking Updated Entities

To enabled tracking in an entity, the entity must be stored in EntityContainer. You can add your entity to EntityContainer using EntityContainer.AttachEntity() methods

When an entity is stored in EntityContainer, any changes to the property of the entity will change the EntityAspect.EntityState to Modified. When the property is changed, the OriginalValues of the entity is not changed, instead it will store the new value in CurrentValues property. This allows you to revert back your entity value to original state by calling EntityAspect.RejectChanges().

Tracking Inserted Entities

To insert an item, you can call the EntityContainer.AddEntity() method which will set the EntityAspect.EntityState to Added

Note that the entity must have its primary key before inserted to the EntityContainer, unless it is an auto increment key.

If the entity has auto increment key, the EntityContainer will add a temporary id, until it retrieves the actual key when persisted to database.

Tracking Deleted Entities

To delete an item, you can simply call the EntityAspect.Delete() method which will set the EntityAspect.EntityState to Deleted. Note that this method does not remove the entity from the EntityContainer nor from your Items collection that bound to your view.

If you removed an entity from the entity container, the entity will be no longer tracked and its EntityState will be set to Detached.

Using IEditableObject for Sandbox Editing

By default, the EntityBase class implements IEditableObject interface which provides you with three methods that you can use for sandbox editing.

  • BeginEdit()
    The BeginEdit method will mark your entity as in editing state, which will store any property value changes to EditingValues property instead of CurrentValues property.  
  • CancelEdit()
    The CancelEdit method will reset the editing state back to normal and clear all values in EditingValues property. 
  • EndEdit()
    The EndEdit method will revert the editing state back to normal and copy all values in EditingValues property to CurrentValues property and mark the EntityAspect.EntityState to Modified or Added depending on the scenario.

Alternatively, you can also use EntityAspect.RejectChanges method to reject all changes made to the container. Unlike CancelEdit method, the RejectChanges method will finalize the entity state immediately.

To learn how sandbox editing is implemented, take a look at the DataEditorViewModelBase.cs provided in the App Framework.

Preparing Save Request for Changed Data

When you are ready to send the pending changes you can use EntityContainer.PreparedSaveEntities() method. This will create a collection of entities that are modified, deleted or inserted. You can then use these entities to create the RestRequest that will call the enterprise data service to perform the save changes operation.

The following code shows you how to create and execute the RestRequest that contains pending changes from EntityContainer.

Finalize Save Changes

As seen in the above sample code, the SaveResult object has KeyMappings property when the request is completed. This property holds temporary key mapping to its actual key for newly added entity.

By calling the FinalizeSaveChanges method, it will set the entity that still use temporary key with the actual key returned from database. This process is important to perform subsequent editing process.

Return Saved Entities

Furthermore, FinalizeSaveChanges is also used to merge the returned saved entities values. You can choose to return the saved entities if your data service performs additional logic that might insert or modify values. This will be useful if you have business logic that you want to store at service level, making the client lighter.