Telerik UI for Windows Phone by Progress
Contents

The SynchronizationContext class is the central place where the synchronization routines are performed for a given object type. It exposes API for creating or deleting items, and also for viewing items currently available after the last synchronization. The SynchronizationContext class also allows for specifying filters based on which items are synchronized.

Using the SynchronizationContext class

A SynchronizationContext for a given Cloud object type is retrieved via the SynchronizationContextPool class. The SynchronizationContextPool class is the central repository for SynchronizationContext instances for unique Cloud object types. Let's assume we want to retrieve the SynchronizationContext for the Task type discussed in the Getting Started section:

CopyC#
SynchronizationContext<Task> tasksContext = SynchronizationContextPool.GetContextForType<Task>();

This call will return us the single SynchronizationContext instance for the Person type. The following code snippet demonstrates how the SynchronizationContext can be used for creating or deleting objects and synchronizing the state with the Cloud:

CopyC#
SynchronizationContext<Task> tasksContext = SynchronizationContextPool.GetContextForType<Task>();
Task task = new Task();
task.Name = "Meeting with John";
task.Description = "Meet with John to discuss the sales statistics from the last month.";
task.DueDate = new DateTime(26, 12, 2013);

// Registers adds the item to the context. This stores is locally and schedules the item for server creation during the next synchronization routine
await tasksContext.AddAsync(task);

// Starts a new synchronization routine which makes sure local and Cloud items of the corresponding type are synchronized
await tasksContext.SynchronizeAsync();

// Marks the given object as deleted. It will be permanently deleted during the next synchronization routine.
await tasksContext.DeleteAsync(task);

Executing separate synchronization stages independently

A SynchronizeAsync call executes several synchronization stages one after another. In a nutshell, what these stages do is:

  • load the local database in memory and generate the so-called SynchronizationContextView
  • synchronize deleted items both on the server and locally
  • upload the local updates and download the server updates
  • create the local new items on the server and store the new server items locally

In specific cases you may want to execute a single synchronization operation like downloading new items or uploading local changes. For that purpose, there is an overload of the SynchronizeAsync method that accepts a value from the SynchronizationOperationFlags enum. A combination of values may also be provided. The enum enlists the following possibilities:

  • Download - new and updated items are downloaded from the server
  • Delete - items are deleted locally and on the server
  • Upload - items created locally or marked as dirty are uploaded to the server
  • LoadLocalDatabase - items stored in the local database are loaded into memory and made available through the SynchronizationContextView

Providing a single or a combination of these values will instruct the corresponding SynchronizationContext to only perform the specified operation(s).

Defining a Filter for the SynchronizationContext

If you want to make sure that only objects that meet given requirements are part of the synchronization procedure, you can define a filter to the SynchronizationContext as follows:

CopyC#
SynchronizationContext<Task> tasksContext = SynchronizationContextPool.GetContextForType<Task>();
tasksContext.SynchronizationFilter = task => task.CreatedBy == CloudProvider.Current.CurrentUser.Id;

This code snippet demonstrates how defining a filter for objects created by the currently logged Telerik Cloud user is done.

Accessing the Objects in the SynchronizationContext

The SynchronizationContext class exposes the View property which is of type SynchronizationContextView. This property gives you access to all items that are available after the last synchronization procedure. You can use this property as a point of access to the Cloud objects being synchronized and use it to visualize them in different controls like ListBoxes or JumpLists. The SynchronizationContextView class implements the IEnumerable interface.

Using the ResolutionMode property

During a synchronization procedure collisions may occur. Collisions are situations in which both the local object and its server representation have been changed. In that case you can define which object is considered during synchronization by setting the ResolutionMode property. It accepts the following values:

  • PreferServer - takes the server version of the object when synchronizing
  • PreferLocal - takes the local version of the object when synchronizing

Tracking Synchronization Progress and handling Exceptions

The SynchronizeAsync method returns an instance of the SynchronizationProgress class. This class contains information about the syncrhonization procedure like:

  • The items that have been affected by the synchronization procedure along with information about the exact synchronization action that has been performed on them
  • A collection of all successfully performed synchronization stages.

The SynchronizeAsync method may thrown a SynchronizationException during synchronization. The SynchronizationException class exposes a property that returns an instance of the SynchronizationProgress class that contains information about the already performed synchronization stages at the point of the exception.

Using the SynchronizationProgress to identify errors

The SynchronizationProgress class exposes the PerformedStages property which returns an array of values defined by the SynchronizationStage enum. It contains all successfully performed stages. The order of synchronization stages of a successfull synchronization procedure is as follows:

  1. Synchronization - marks the start of the synchronization procedure
  2. LoadingLocalDataBase - marks the stage at which locally stored items are loaded into the memory
  3. DeletingItemsRemovedOnServer - marks the stage at which items that are missing on the server are also deleted locally
  4. DeletingLocalItemsOnServer - marks the stage at which items marked as deleted locally are deleted on the server as well
  5. DeletingLocalItems - marks the stage at which items marked as deleted locally and do not exist on the server are purged
  6. GettingNewAndUpdatedItemsFromServer - marks the stage at which new and updated items are downloaded from the server and stored locally
  7. UpdatingLocalItemsOnServer - marks the stage at which locally stored items that are marked as dirty are uploaded on the server
  8. CreatingLocalItemsOnServer - marks the stage at which new local items are created on the server
So if an exception is thrown during synchronization, the last stage that completed successfully at the point of the exception will be last in the exposed array.

Get Information about the Items that have been affected by the Synchronization Procedure

The SynchronizationProgress class exposes the AffectedItems property which returns an array of ItemSynchronizationInfo objects. An ItemSynchronizationInfo encapsulates a single data item and the synchronization action that has been performed on it. The possible synchronization actions are as follows:

  • DeletedLocally - the item has been deleted from the local storage
  • DeletedOnServer - the item has been deleted on the server
  • CreatedLocally - the item has been created in the local storage
  • CreatedOnServer - the item has been created on the server
  • UpdatedLocally - the item has been updated in the local storage
  • UpdatedOnServer - the item has been updated on the server