How to: Specify Snapshot, Download, Upload, and Bidirectional Synchronization
Sync Framework supports snapshot, download, upload, and bidirectional synchronization. Because of the flexibility that Sync Framework provides you can specify different types of synchronization for different tables. For more information, see Architecture and Classes for Client and Server Synchronization.
This topic provides an overview of the properties that are required for each type of synchronization. The topics in this section describe how to configure the types of synchronization and provide code examples.
The type of synchronization that is used for a table depends on the synchronization commands that you set on the SyncAdapter and the SyncDirection property on the SyncTable. The synchronization commands determine what data can be synchronized, and the SyncDirection property determines which data is actually synchronized for a particular session. Frequently, these are the same: For example, you specify bidirectional synchronization and the commands to support it. However, in some cases, you might want to synchronize in only one direction. For example, a salesperson might require download-only access to product data, whereas a manager might also require the ability to update this data remotely. The SyncAdapter commands can be specified for bidirectional synchronization. However, the SyncDirection property is set to download-only for the salesperson.
Then for each table, manually specify a set of commands for the SyncAdapter, or use the SqlSyncAdapterBuilder to generate those commands. For download-only and bidirectional synchronization, the server must also be configured to track incremental data changes. For more information, see Tracking Changes in the Server Database.
If you manually create commands, you will set some or all the following properties on the SyncAdapter:
SelectIncrementalInsertsCommand. This property is used in all kinds of synchronization. The property specifies the command that retrieves from the server database: the initial inserts for snapshot, download-only, and bidirectional synchronization; and the incremental inserts for download-only and bidirectional synchronization. By default, the command also retrieves the table schema from the server database for all kinds of synchronization. Schema creation and inserts are applied to the client by the SqlCeClientSyncProvider.
SelectIncrementalUpdatesCommand and SelectIncrementalDeletesCommand. These properties are used in download-only and bidirectional synchronization. The properties specify the commands that retrieve updates and deletes at the server so that the updates and deletes can be applied to the client by the SqlCeClientSyncProvider.
InsertCommand, UpdateCommand, and DeleteCommand. These properties are used in upload-only and bidirectional synchronization. The properties specify the commands that apply inserts, updates, and deletes made at the client to the server.
SelectConflictUpdatedRowsCommand and SelectConflictDeletedRowsCommand. These properties are typically used in bidirectional synchronization. The properties specify the commands that retrieve update and delete conflicts at the server. For more information, see How to: Handle Data Conflicts and Errors.
One of the advantages of specifying the synchronization commands manually is that you have more control over the commands and which types of changes are uploaded from the client. For example, if you want to perform bidirectional synchronization, but you do not want to upload deletes from the client, do not specify a command for the DeleteCommand property. For an example of manual commands that are more complex than those generated by the SqlSyncAdapterBuilder, see How to: Handle Data Conflicts and Errors.
If you have the SqlSyncAdapterBuilder generate the commands, set the SyncDirection property. This property determines which of the SyncAdapter commands to generate for a table. For snapshot or upload-only synchronization, this is all you have to set. For download-only and bidirectional synchronization, you must also set properties that identify which columns on the server are used to track changes, and whether the data should be filtered. Those properties are as follows:
Based on the columns and filter values that are specified for these properties, the SqlSyncAdapterBuilder generates the appropriate commands.
After a table has been synchronized, you can specify a different synchronization direction. However, snapshot synchronization does not enable change-tracking in the client database. If you anticipate that an application will require change-tracking of data at some point, we recommend that you do not configure snapshot synchronization. If you configure snapshot synchronization and then change to another type of synchronization, you must be aware of the following issues that are related to change-tracking:
If you have snapshot synchronization configured and then change to download-only or bidirectional synchronization:
Rows from the server side might be selected and downloaded again. This can cause conflicts during the download phase.
If you have snapshot synchronization configured, make changes in the client database, and then change to upload-only or bidirectional synchronization:
Any changes that are made in the client database are not uploaded. If you require the changes to be uploaded, you must perform a dummy update of each changed row.
If you have snapshot synchronization configured, change to upload-only or bidirectional synchronization and then make changes in the client database:
Conflicts can occur during the upload phase.