Getting Started: Client and Server Synchronization

Article
07/07/2014

Note

The following information is included as reference for existing applications that support offline scenarios only. For developing new applications, please see Architecture and Classes for Database Synchronization.

This topic describes a console application that downloads an initial dataset and then a set of incremental changes from a single table. The application is straightforward, but it will introduce you to code that is built on, in many ways, throughout the Sync Framework documentation. If you have read Architecture and Classes for Client and Server Synchronization, you should have an understanding of the main classes that are used in the application.

You can learn by just reading through the example code. However, it is more instructive to run the application and to see it in action. Before you run the code, make sure that you have the following installed:

Sync Framework

The application requires references to Microsoft.Synchronization.Data.dll, Microsoft.Synchronization.Data.Server.dll, and Microsoft.Synchronization.Data.SqlServerCe.dll.
SQL Server Compact Service Pack 1

The application requires a reference to System.Data.SqlServerCe.dll.
A version of SQL Server other than SQL Server Compact to act as the server database.

The example code uses localhost in connection strings. To use the instance of SQL Server Express that installs with Visual Studio, change localhost to .\sqlexpress. To use a remote server, change localhost to the appropriate server name.
The Sync Framework sample databases. Execute both scripts that are available in Setup Scripts for Database Provider How-to Topics. We recommend to that you review these scripts to see how change tracking is handled in the server database.

The application is composed of six classes:

SampleSyncAgent. This class is derived from SyncAgent and contains a SyncTable.
SampleServerSyncProvider. This class is derived from DbServerSyncProvider and contains the SyncAdapter.
SampleClientSyncProvider. This class is derived from SqlCeClientSyncProvider. In this example, this class contains only a connection string to the client database.
SampleStats. This class uses the statistics that are returned by the SyncAgent.
Program. This class sets up synchronization and calls methods from the Utility class.
Utility. This class handles all functionality that is not directly related to synchronization, such as holding connection string information and making changes to the server database. A complete Utility class is used in other topics. The complete class is available from Utility Class for Database Provider How-to Topics.

Key Parts of the API

Before you look at the complete code example, we recommend that you review the following examples that illustrate several key sections of the API that are used in this application.

Creating a SyncTable

The following code example creates a SyncTable object for the Customer table, specifies the synchronization direction, and specifies how the table should be created on the client. In this case, if the table already exists in the client database, the table will be dropped during the first synchronization.

Using the SqlSyncAdapterBuilder

Each of the code examples in this section creates a SyncAdapter for the Customer table. The synchronization adapter provides to the server synchronization provider the specific commands that are required to interact with the server database. In this application, the synchronization adapter is created by using the SqlSyncAdapterBuilder. The first example shows how to use the SqlSyncAdapterBuilder with a custom change tracking system. The second example shows how to use the SqlSyncAdapterBuilder with SQL Server change tracking (available in SQL Server 2008). For more information about change tracking, see Tracking Changes in the Server Database.

For information about how to create commands manually instead of using the builder, see How to: Download Incremental Data Changes to a Client.

Using a Custom Change Tracking System

To use a custom change tracking system, specify the following information for the SqlSyncAdapterBuilder and SyncAdapter:

The name of the table to synchronize and the tombstone table. A tombstone table is used to track delete operations in the server database. For more information, see Tracking Changes in the Server Database. If the tables are in a schema other than dbo, the schema must be specified.
The direction of synchronization. This controls which commands the SqlSyncAdapterBuilder creates. For more information about commands, see How to: Specify Snapshot, Download, Upload, and Bidirectional Synchronization.
The tracking columns in the server database. The columns are used to track when changes are made, so that only new changes are downloaded. You can include additional columns to track where changes are made. For more information, see How to: Use a Custom Change Tracking System.
The name of the SyncAdapter. This must match the name of the SyncTable. Therefore, it should not include the schema name.

Using SQL Server Change Tracking

To use SQL Server change tracking, specify the following information for the SqlSyncAdapterBuilder and SyncAdapter:

The name of the table to synchronize.
The direction of synchronization. This controls which commands the SqlSyncAdapterBuilder creates. For more information about commands, see How to: Specify Snapshot, Download, Upload, and Bidirectional Synchronization.
The type of change tracking to use. By default, Sync Services expects you to specify custom change tracking columns. In this code example, SQL Server change tracking is specified.
The name of the SyncAdapter. This must match the name of the SyncTable. Therefore, it should not include the schema name.

Specifying the New Anchor Command

The following code example specifies a command to retrieve a new anchor value from the server. The value is stored in the client database and is used by the commands that synchronize changes. During each synchronization, the new anchor value and the last anchor value from the previous synchronization are used: the set of changes between these upper and lower bounds is synchronized.

In this case, MIN_ACTIVE_ROWVERSION returns a timestamp value from a SQL Server database. (MIN_ACTIVE_ROWVERSION was introduced in SQL Server 2005 Service Pack 2.) A timestamp value is used because the tracking columns that are specified for the SqlSyncAdapterBuilder contain timestamp values. If the tracking columns contained date values, you could use a function such as GETUTCDATE() instead of MIN_ACTIVE_ROWVERSION. For more information about anchors, see Tracking Changes in the Server Database.

The SyncSession class contains several string constants that can be used in synchronization commands. SyncNewReceivedAnchor is one of these constants. You could also use the literal @sync\_new\_received\_anchor directly in your queries.

Calling the Synchronize Method

The following code example instantiates SampleSyncAgent and calls the Synchronize method. In the SampleSyncAgent class, the SampleClientSyncProvider is specified as the LocalProvider and the SampleServerSyncProvider is specified as the RemoteProvider, and also the synchronization table that has already been described.

In the SampleStats class, statistics that are returned by the SyncAgent are used to provide feedback to the user about the synchronization session. For more information, see How to: Work with Events and Program Business Logic.

Complete Code Examples

Now that you have seen the main sections of code that are involved in synchronization, these sections are combined in a complete application that is thoroughly commented. After you run this application, we recommend that you read the topics in the section Programming Common Client and Server Synchronization Tasks. You will see the same classes that are used in the code examples in this topic. However, they are applied across additional tables in more sophisticated ways.

Share via