Skip to end of metadata
Go to start of metadata

Most applications typically require access to a remote data source, either on their own application data service or public data services. The access to these data services is highly dependent on data connectivity. When the data connectivity is not stable or hard to come by, the application will be not functional.

To overcome this issue, most applications now support an offline data storage that keep all or portion of data in the device's storage. When the remote server is unreachable due to connection issues, users can still work with the application by reading the local data. This scenario introduces the needs of two-way data synchronization to sync the modified local data to the server and vice versa.

Enterprise App Framework leverages the existing Crosslight data services such as SQLite and EntityContainer to provide comprehensive functionality allowing you to enable data synchronization feature easily.

It is recommended that you are already familiar with data services available in Enterprise App Framework prior to implementing data synchronization. Please refer to the following topics to learn more about Crosslight data services.

On this page:

Enabling Data Synchronization

To enable data synchronization using Enterprise App Framework, you need to perform the following tasks.

  • Add Intersoft.Crosslight.Data, Intersoft.Crosslight.Data.ComponentModel and Intersoft.Crosslight.Data.SQLite in your project references.
  • Create the entity services, entity repositories and entity models that has data synchronization metadata. (Data Synchronization Metadata)
  • Configure the data access target url. (Configure DataAccess TargetUrl)
  • Register the entity repositories. (Register The Entity Repository)
  • Set the EnableDataSynchronization property in AppSettings to True and configure the related data synchronization configurations (AppSettings.LocalDatabaseName, AppSettings.LocalDatabaseLocation, AppSettings.DataSynchronizationMode)
  • Register the SynchronizationService and specify the entity types that will take part in the synchronization process.

The following code shows how to configure the AppSettings and SynchronizationService along with other supporting configuration in AppService.cs.

Enabling Multiple Synchronization Channel

When you build an enterprise application with several modules, synchronizing data for all modules in a bulk might hinder your application performance significantly. When facing this requirement, it is best to separate the data synchronization into several synchronization channels. The synchronization channel can then focus on specific entities only, for example you might want to gather all the master data in one synchronization channel, and transactional data per module in other synchronization channel. To learn more about multiple synchronization channel concept, Synchronizing Data.

To enable multiple synchronization channel, you need to define the synchronization channel and register it to SynchronizationService as follows.

Configuring Synchronization Channel

Synchronization channel represents a set of synchronization rules. You can configure these synchronization rules directly from SynchronizationChannel properties. The following are some of rules that you can set.

  • Types
    Defines the entity types that will be synchronized by the synchronization channel.
  • SychronizationMode
    Defines the synchronization behavior:
    • TwoWay, means that it will attempt to perform synchronization both ways.
    • FromServer, means that it will only attempt to perform synchronization from server to client. Pending changes in client will not be sent.
    • FromClient, means that it will only attempt to perform synchronization from client to server. New data from server will not be fetched.
  • Priority
    Determines the queue priority when the channel is queued in synchronization queue.
  • PageSize
    Determines whether the synchronization channel should apply paging mechanism when retrieving data from server side. The PageSize also determines the number of record it should retrieve per request. 
  • UserSpecific
    Determines whether the synchronized data is user specific. If set to true, it will create synchronization info for the current user.
  • AutoRetry
    Determines whether the synchronization channel should automatically retry the sync process when the previous sync failed.
  • MaximumRetry
    Determines number of maximum retry when the auto retry feature is enabled.
  • QueryDefinition
    Determines the LocalTypeQueryDefinition that will be used when performing load local data.

Synchronization Service

SynchronizationService is a built-in service in Enterprise App Framework responsible for data synchronization process such as:

  • Retrieving data from server side and synchronized it to local storage.
  • Sending pending changes from local storage and synchronized it to server side.
  • Synchronization Channel queue management for multiple synchronization channel scenario.
  • Resolve stall mechanism when there are problems with connectivity during previous synchronization process.
  • Loading data from local storage.

Synchronizing Data in Single Channel Scenario

In most cases, your apps should perform two-way synchronization to ensure both local and remote data are updated with latest version. In essence, two-way synchronization defines the process of gathering all pending changes from local storage and submit them to server, then push the new and updated data back to the client. This type of synchronization process is fully supported in the Crosslight App Framework through SynchronizationService class which works in conjunction with SynchronizationRestRepository class.

To perform two-way data synchronization, you can use SynchronizeDataAsync method with SynchronizeAction.SyncData or SynchronizeAction.SyncDataUserInitiated arguments such as shown in the code example below.

Synchronizing Data in Multiple Channels Scenario

Alternatively, if you have multiple synchronization channels, you can opt to use either SynchronizationService.Start method or SynchronizationService.StartImmediately method. The Start method will add your channel to synchronization queue, and will be handled when your queue is up. The StartImmediately method on the other hand, bypass the synchronization queue and process the synchronization channel directly.

Crosslight provides built-in queue management for multiple channels to avoid double processing, particularly when there are multiple synchronization channel entries. To learn more about the queue management implemented in SynchronizationService, see Synchronizing Data.

The following code shows you how to use SynchronizationService.Start and SynchronizationService.StartImmediately methods.

Loading Data From Local Storage

Depending on your application's requirements, you might want to load all the data from local data storage at start up. The data will be stored in EntityContainer and subsequent data retrieval will be taken from EntityContainer rather than re-opening connection to SQLite and re-instantiating the data model. This approach is only applicable if your application has moderate amount of data. In case you need to handle a large amount of data, you should use the EntityRepository capability to load data partially from the local data storage.

To load data from local storage, you can use SynchronizeDataAsync method with SynchronizeAction.LoadLocalData arguments.

This will load all the data from all table in local storage. Alternatively, you can use LocalTypeQueryDefinition to specify which entity to be loaded. You can also add additional query in the form of QueryDescriptor if needed.

The best time to load the data from local storage is during application's start up. The following code shows you how to load master data from local data storage in OnStart method of AppService.cs.

In most cases, some data that are related to user must be loaded after login process. This means that you will need to load the user-specific data later.

The following code shows you how to load user-specific data from the local storage for single synchronization channel scenario.

For multiple synchronization channel you can specify the local type query definition directly to the channel as follows.

Storing Pending Changes

Enterprise App Framework provides built-in functions to automatically save pending changes to local storage when the remote server is unreachable. Since all the complexity and details have been handled, all you need to do is simply inheriting your entity repository from EditableLocalEntityRepository. Furthermore, you can also have your repositories automatically generated using Entity Designer Extensions. To learn more how to generate entity repository, see Generating Entity Repository.

You can then consume the entity repository in your view model that derive from the base classes available in Enterprise App Framework. To learn more about the view models available in the App Framework, see Data View Models Pattern.

Synchronization Triggers

Built with solid architecture, Crosslight App Framework is thoughtfully engineered with comprehensive data services that you can easily consume and extend. In addition to many pre-built synchronization features, the App Framework also implements smart synchronization triggers.

Without requiring additional code, the sync process will be automatically triggered in the following events:

  • Application Start
  • Application Resume
  • Background Interval

In addition, you can also trigger the sync process manually such as in pull-to-sync scenario. Feel free to add more sync triggers by simply calling the SynchronizeDataAsync method with SynchronizeAction.SyncData argument.


To learn how data synchronization works and see it in action, please check out the Synchronization Sample which demonstrates a fully-functional simple task app with two-way sync support.