Incorporating Data Synchronization into Applications by Using Visual Studio
To incorporate data synchronization into your application, Visual Studio provides a Local Database Cache template. Local Database Cache is available as a new project item template. (On the Project menu, click Add New Item.) For more information, see How to: Configure Data Synchronization in an Application.
.gif) Note: |
|---|
The
Local Database Cache template cannot be directly added to a smart device project. Instead, you must add the Local Database Cache to the middle-tier WCF or Web service project and then split the generated synchronization components into the smart device project. For more information, see Occasionally Connected Applications (Devices).
|
Starting in Visual Studio 2008 SP1, in addition to the Configure Data Synchronization dialog box, you can also use the Data Source Configuration Wizard to configure synchronization. During configuration of a typed dataset, select the option to Enable local database caching on the Choose Your Database Objects page of the wizard. For more information, see Walkthrough: Creating an Occasionally Connected Application by Using the Data Source Configuration Wizard.
Adding a Local Database Cache opens the Configure Data Synchronization dialog box. You use this dialog box to provide specific information about the client and server in order to set up the required synchronization components. The local database cache uses a SQL Server Compact 3.5 database on the client to store data locally. You can use an existing SQL Server Compact 3.5 database as the local database cache. If you do not yet have a local database, you can use the Configure Data Synchronization dialog box to create a new local database. To create a new local SQL Server Compact 3.5 database, you can set the Client connection (in the Configure Data Synchronization dialog box) to create a new SQL Server Compact 3.5 database based on the tables selected from the Server connection.
| Note: |
|---|
The
Configure Data Synchronization dialog box enables you to configure Microsoft Synchronization Services for ADO.NET for download scenarios only. This means that after you configure data synchronization by using this dialog box, calling Microsoft.Synchronization.Data.SyncAgent.Synchronize will only update the local database with changes found on the remote database. Changes made to the data on the local database will not be uploaded to the remote database. After you configure data synchronization by using the Configure Data Synchronization dialog box, you can programmatically enable uploads (bidirectional synchronization) during synchronization. For more information, see How to: Configure a Local and Remote Database for Bidirectional Synchronization.
|
Configuring the Remote Database for Synchronization
For data synchronization to work successfully, there are some additions that are required to each table on the remote database with which you want to synchronize. The Configure Data Synchronization dialog box creates SQL scripts to run against the remote database to create the necessary objects (the objects listed in the table below). All SQL scripts that are created by the synchronization designer are saved to a SQLScripts folder in your project.
| Note: |
|---|
The SQL scripts generated by the
Configure Data Synchronization dialog box are run by default. You can choose whether the scripts are generated and executed by setting the Script Generation options in the Configure Tables for Offline Use dialog box.
The default behavior of the
Configure Data Synchronization
dialog box is to automatically run the scripts and update the remote database when the dialog box is closed. Clear the
Execute scripts when this dialog is closed
check box if you do not want to automatically run the scripts. Additionally, if the remote database already has the required tracking columns, triggers, and deleted-items table, no scripts will be generated. In other words, if no changes are required to the remote database, no scripts are created.
|
The following table lists the items required on the remote database and provides an explanation for each:
Additions to each synchronized table on the remote database
|
Explanation
|
|---|
LastEditDate column
|
This column should be a DateTime or TimeStamp on each table being synchronized. It is compared to the LastEditDate column on the client to identify records that have been modified on the server since the last synchronization call.
|
CreationDate column
|
This column should be a DateTime or TimeStamp on each table being synchronized. It is compared to the CreationDate column on the client to identify records that have been added to the server since the last synchronization call.
|
deleted items table (TableName_Deleted)
|
Items are moved to this table when they are deleted from the table on the database server. This is done to identify records deleted from the server since the last synchronization call. Each table being synchronized requires a deleted items table to track records deleted from the remote table.
|
DeletionTrigger (TableName_DeletionTrigger)
|
This trigger runs every time that a record is deleted from the server database table. Deleted records are moved to the deleted items table. They are moved to the deleted items table because records in the client database that are not in the server database might be treated as new records and added back to the server. Synchronization Services checks the deleted items table to determine that it should delete a deleted record from the client database instead of adding it back to the server database.
|
InsertTrigger (TableName_InsertTrigger)
|
This trigger populates the CreationDate column with the current date and time when new records are added.
|
UpdateTrigger (TableName_UpdateTrigger)
|
This trigger populates the LastEditDate column with the current date and time when existing records are modified.
|
Starting the Synchronization Process from an Application
After providing the required information in the Configure Data Synchronization dialog box, add code to your application to initiate synchronization. It is important to understand that synchronizing data updates the local database, not the table in the dataset or any other object in your application. Remember to reload your application data source with the updated data from the local database. For example, call the TableAdapter.Fill method to load your dataset's data table with the updated data from the local database.
Add the following code to your application where you want to initiate the synchronization process:
' Call SyncAgent.Synchronize() to initiate the synchronization process.
' Synchronization only updates the local database, not your project's data source.
Dim syncAgent As LocalDataCache1SyncAgent = New LocalDataCache1SyncAgent()
Dim syncStats As Microsoft.Synchronization.Data.SyncStatistics = syncAgent.Synchronize()
' Add code here to refill your application's data source
' with the updated data from the local database.
// Call SyncAgent.Synchronize() to initiate the synchronization process.
// Synchronization only updates the local database, not your project's data source.
LocalDataCache1SyncAgent syncAgent = new LocalDataCache1SyncAgent();
Microsoft.Synchronization.Data.SyncStatistics syncStats =
syncAgent.Synchronize();
// Add code to refill your application's data source
// with the updated data from the local database.