Walkthrough: Creating an Occasionally Connected Smart Device Application

Article
09/03/2015

This walkthrough provides step-by-step directions for configuring data synchronization in an occasionally connected smart device application. The sample application adds a customer to the local database cache and synchronizes the changes with a remote database. It also displays customer data on a Windows Form: this enables you to verify that synchronization is successful.

During this walkthrough, you will follow these steps:

Create a new Smart Device application.
Add a new Window Communication Foundation (WCF) Service Library which serves as a middle tier between the local database cache and the remote database.

Note

The middle tier service library is required because Synchronization Services for ADO.NET (Devices) does not support direct 2-tier synchronization.
Add a new Local Database Cache to the project.
Configure synchronization settings.
Configure and start the WCF service.
Add synchronization functionality to your device application.
Test the application.

Prerequisites

To complete this walkthrough you must:

Install the Northwind sample database on a Microsoft SQL Server or Microsoft SQL Server Express Edition database. The local database cache on the device emulator will synchronize with this database. For more information, see How to: Install Sample Databases.
Install Windows Mobile Device Center (Windows Vista) or ActiveSync.
Install Visual Studio 2008 Service Pack 1.
Install Microsoft Synchronization Services for ADO.NET.
Install Microsoft SQL Server Compact 3.5 Service Pack 1 for Windows Mobile.

Creating the Smart Device Application

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Visual Studio Settings.

To create a new project on the desktop computer

From the File menu, create a new project that uses either Visual Basic or Visual C#.

Note

The Configure Data Synchronization dialog box is supported in Visual Basic and C# projects. Therefore, make sure to select one of these languages.
Name the solution Walkthrough and the project OCSDeviceApp.
Under Project types, click Smart Device, and then Smart Device Project template.
Click OK.

The Add New Smart Device Project dialog box will appear. By default, the Windows Mobile 5.0 Pocket PC SDK target operating system, .NET Compact Framework version 3.5, and Device Application template are selected.
Click OK.

The OCSDeviceApp project is created and added to Solution Explorer.

Creating a WCF Service

Unlike desktop applications, the local SQL Server Compact database cache cannot synchronize directly with the remote SQL Server database for smart device projects. You must create a WCF service library that acts as a middle tier between the two databases. The device application uses services exposed by the WCF service for synchronization.

To add a WCF Service Library to the Solution

From the File menu, point to Add, and then click New Project.
Name the project MiddleTierServiceLibrary.
Click WCF under Project types, followed by the WCF Service Library template.
Click OK.

The MiddleTierServiceLibrary project is created and added to Solution Explorer.

Adding a Local Database Cache

Unlike desktop applications, the Local Database Cache template is not available from the Add New Item dialog box of a smart device project. Instead, you must add a local database cache to the middle tier WCF or Web Service project.

To add a local database cache to a project

Right-click the MiddleTierServiceLibrary project, point to Add, and then click New Item.
Click the Local Database Cache template and type NorthwindCache.sync in the Name box.
Click Add.

A NorthwindCache.sync file is added to Solution Explorer and the Configure Data Synchronization dialog box appears. NorthwindCache.sync stores synchronization configuration information.

Configuring Synchronization Settings

To create data connections to the server and client databases

Use the Configure Data Synchronization dialog box to create a connection to the Northwind database that you installed as a prerequisite to this walkthrough. This is the remote database external to your smart device application. You may either select an existing Server connection to the SQL Server Northwind database, or, if a connection does not exist, click New to create a new connection to the SQL Server Northwind database.

Note

You may enable SQL Server change tracking, but only after the connection to the remote database server is configured to connect to a SQL Server 2008 database. For more information, see How to: Configure Data Synchronization to Use SQL Server Change Tracking.
Accept the default value of Northwind.sdf (new) for the Client connection. The Configure Data Synchronization dialog box creates a new SQL Server Compact 3.5 database and adds it to your project. For more information about the available data connection options, see How to: Create a Data Connection to the Northwind Database.

After you select the server connection, the Configure Data Synchronization dialog box queries the remote database on the server for a list of available tables. This dialog box also enables the Add button, but only after the list of available tables is retrieved.

Note

Notice that the OK button is not enabled at the conclusion of this step. This is because no tables have been selected for synchronization. The next section explains how to add tables.

To add and configure tables for local caching

Click Add to open the Configure Tables for Offline Use dialog box.
Select the Customers table.

Note

You can modify the default synchronization behavior for each table that you select in the Configure Tables for Offline Use dialog box. For more information, see How to: Configure Data Synchronization in an Application.
Accept the default column and table values. Click OK. The Configure Data Synchronization dialog box will create tracking columns and a deleted-items table if needed.

The Customers table is added to the Cached Tables list.

To split synchronization components between the server and client projects

In the Configure Data Synchronization dialog box, click Advanced.
On the Client project location drop down menu, select OCSDeviceApp.
Click OK.

Components will be divided between the client project and the server project, after data synchronization is configured. Meanwhile, the Generate SQL scripts dialog box appears. By default, it generates scripts that maintain tracking columns and tables for deleted and updated items on the server database.
Click OK.

The generated SQL scripts are saved in the server project if needed. The Northwind.sdf client database is created in the client project and synchronized with the server database for the first time.

Note

SQL scripts are created only if modifications are required on the server. If the server already has a deleted items table and tracking columns or if you use SQL Server change tracking, no scripts are created.
When the Data Source Configuration Wizard appears, select the Customers table.
Click Finish.

NorthwindDataSet.xsd is added to the client project and all dialog boxes close.

Now that synchronization is configured, the following items are added to the client project:

Item	Description
Northwind.sdf	A local database file that contains data cached from SQL Server.
NorthwindCache.Client.sync	An XML file that contains synchronization configuration information. Double-click this file to open the Configure Data Synchronization dialog box.
NorthwindCache.Client.Designer.cs (or .vb)	A code file that contains definitions for client sync provider and the sync agent. Also contains sync tables for the local database. For more information, see Architecture and Classes for Client and Server Synchronization.
NorthwindDataSet.xsd	The typed dataset generated by the Data Source Configuration wizard. This dataset contains a Customers table that is populated with data that is stored in the local database.
References\Microsoft.Synchronization.Data References\Microsoft.Synchronization.Data.SqlServerCe	Required references to Microsoft Synchronization Services for ADO.NET.

The following items are added to the server project:

Item	Description
NorthwindCache.sync	An XML file that contains synchronization configuration information. Double-click this file to open the Configure Data Synchronization dialog box.
NorthwindCache.Designer.cs (or .vb)	Contains definitions for the Server Sync Provider and the Sync Adapter for the server database. For more information, see Architecture and Classes for Client and Server Synchronization.
NorthwindCache.SyncContract.cs (or .vb)	A code file that contains the WCF contract definition and its implementation.
SQLScripts folder	A folder of scripts. The scripts in this folder are used to track database changes on the server. Some of the scripts in this folder create the tracking columns, deleted items table. Other scripts in this folder create triggers that track changes on the server. Note: SQL scripts are created only if modifications are required on the server. If the server already has a deleted items table and tracking columns or if you use SQL Server change tracking, no scripts are created.
SQLUndoScripts folder	The scripts in this folder delete the tracking columns, the items table, and any triggers that are used to track and respond to database changes on the server. Use these scripts to undo the changes made by the Configure Data Synchronization dialog box to the database. Note: SQL scripts are created only if modifications are required on the server. If the server already has a deleted-items table and tracking columns or if you use SQL Server change tracking, no scripts are created.
References\Microsoft.Synchronization.Data References\Microsoft.Synchronization.Data.Server	Required references to Microsoft Synchronization Services for ADO.NET.

Configuring and Starting the WCF Service

To configure the WCF service (NorthwindCacheSyncService) that is generated by the Configure Data Synchronization dialog box

In Solution Explorer, double-click NorthwindCache.SyncContract.cs (or .vb) to open the file in the Code Editor.
Add the XmlSerializerFormat() attribute just before the definition INorthwindSyncContract. The Code Editor should display:
In Solution Explorer, double-click App.config.
Make the following XML modifications to the App.config file. These changes configure the project to host the NorthwindCacheSyncService generated by the Configure Data Synchronization dialog box instead of the default service (Service1) that is generated by the WCF project template.
1. Change <service name="MiddleTierServiceLibrary.Service1" behaviorConfiguration="MiddleTierServiceLibrary.Service1Behavior"> to <service name="MiddleTierServiceLibrary.NorthwindCacheSyncService" behaviorConfiguration="MiddleTierServiceLibrary.NorthwindCacheSyncServiceBehavior">
2. Change <add baseAddress="https://localhost:8731/Design_Time_Addresses/MiddleTierServiceLibrary/Service1/" /> to <add baseAddress="http://<your computer IP address>:8731/NorthwindCacheSyncService/" />
3. Change <endpoint address="" binding="wsHttpBinding" contract="MiddleTierServiceLibrary.IService1"> to <endpoint address="" binding="basicHttpBinding" contract="MiddleTierServiceLibrary.INorthwindCacheSyncContract">
  
  Note
  
  wsHttpBinding is not supported on devices.
4. Change <dns value="localhost"/> to <dns value="<your computer IP address>"/>
5. Change <behavior name="MiddleTierServiceLibrary.Service1Behavior"> to <behavior name="MiddleTierServiceLibrary.NorthwindCacheSyncServiceBehavior">
Right-click MiddleTierServiceLibrary in Solution Explorer and click Set as StartUp Project.
To start the WCF Service, click Start Without Debugging in the Debug menu.

The Deploy OCSDeviceApp dialog box appears.
Click Cancel and then Yes to continue.

Note

You are only starting the WCF service: the device emulator is not yet required.

The WCF Service Host is started (icon appears in notification area) and hosts the service. The WCF Test Client appears and enables you to test the service.

Note

Make sure that the port is accessible and not blocked by a firewall.

Coding Synchronization Features in Your Smart Device Application

The previous steps configured your data synchronization options. In addition, you must add synchronization functionality to your smart device application.

Adding a Web reference from the project to the WCF service

In Solution Explorer, right-click OCSDeviceApp, and then click Add Web Reference.

The Add Web Reference dialog box appears.
Type the address of the NorthwindCacheSyncService, such as http://IP Address:8731/NorthwindCacheSyncService/, in the URL box, and then click Go.

Note

Insure that there are no firewalls blocking port 8731 on the computer.

Once the NorthwindCacheSyncService Web service is found, the Add Reference button is enabled.

Note

The service address may be found in the App.config file.
Name the Web reference NorthwindCacheWebRef, and then click Add Reference.

NorthwindCacheWebRef appears under Web References in Solution Explorer. Visual Studio generates the file Reference.cs: however, you will not be able to see this file in Solution Explorer.
Perform the following steps to open and modify Reference.cs:
1. Double-click NorthwindCacheWebRef to open it in Object Browser.
2. Expand the node OCSDeviceApp.NorthwindCacheWebRef.
3. Right-click NorthwindCacheSyncService and click Go To Definition.
  
  Reference.cs is opened in the Code Editor.
4. Add the following code after the last using or imports statement:
```
Imports Microsoft.Synchronization
Imports Microsoft.Synchronization.Data
```
  Or, in C#:
```
using Microsoft.Synchronization;
using Microsoft.Synchronization.Data;
```
5. Remove all classes and enumerations in the file except for NorthwindCacheSyncService.
  
  Note
  
  The removed types are already defined in the newly imported Microsoft.Synchronization and Microsoft.Synchronization.Data namespaces.

To create a data-bound form that is used to view data and initiate synchronization

In Solution Explorer, double-click Form1 to open it in the Visual Studio designer.
Drag the Customers node from the Data Sources window onto Form1.
In Form1, click the left menu item and type Synchronize Now. Set its Name property to SynchronizeMenuItem.

Note

The user will ultimately click Synchronize Now to start the synchronization process.
Double-click the Synchronize Now menu to create a menu-click event handler and open the form in the Code Editor.

Add code that will start the synchronization process and refill the Customers table in the dataset. The code in the event handler should resemble the following:

Cursor.Current = Cursors.WaitCursor

' The service referenceDim webSvcProxy = New NorthwindCacheWebRef.NorthwindCacheSyncService()

' The server providerDim serverProvider = New Microsoft.Synchronization.Data.ServerSyncProviderProxy(webSvcProxy)

' The sync agentDim syncAgent = New NorthwindCacheSyncAgent()
syncAgent.RemoteProvider = serverProvider
syncAgent.Customers.SyncDirection = Microsoft.Synchronization.Data.SyncDirection.Bidirectional

' Synchronize the databasesDim stats = syncAgent.Synchronize()

' Reload the DataSet/Datagrid from the local database
CustomersTableAdapter.Fill(Me.NorthwindDataSet.Customers)

' Show synchronization statistics
MessageBox.Show("Changes Downloaded: " + stats.TotalChangesDownloaded.ToString() + _
            vbCrLf + "Changes Uploaded: " + stats.TotalChangesUploaded.ToString())

Cursor.Current = Cursors.Default

Cursor.Current = Cursors.WaitCursor;

// The WCF Service
NorthwindCacheWebRef.NorthwindCacheSyncService webSvcProxy = new 
    OCSDeviceApp.NorthwindCacheWebRef.NorthwindCacheSyncService();

// The Remote Server Provider Proxy
Microsoft.Synchronization.Data.ServerSyncProviderProxy serverProvider = new 
    Microsoft.Synchronization.Data.ServerSyncProviderProxy(webSvcProxy);

// The Sync Agent
NorthwindCacheSyncAgent syncAgent = new NorthwindCacheSyncAgent();
syncAgent.RemoteProvider = serverProvider;
syncAgent.Customers.SyncDirection = Microsoft.Synchronization.Data.SyncDirection.Bidirectional;

// Synchronize the databases
Microsoft.Synchronization.Data.SyncStatistics stats = syncAgent.Synchronize();

// Reload the DataSet/Datagrid from the local database
customersTableAdapter.Fill(northwindDataSet.Customers);

// Show synchronization statistics
MessageBox.Show("Changes Downloaded: " + stats.TotalChangesDownloaded.ToString() +
    "\r\n" + "Changes Uploaded: " + stats.TotalChangesUploaded.ToString());

Cursor.Current = Cursors.Default;

The DataGridView displays the Customers table from the local database cache (the Northwind.sdf database located in the project).

To add a customer to the local Northwind database

In Solution Explorer, Double-click Form1 to open it in the designer.
Click the menu item that is located on the right side of the form and type Insert Row. Set the menu item's Name property to InsertRowMenuItem.
Double-click the Insert Row button to create a menu-click event handler and open the form in the Code Editor.

Add code to connect to (and insert a row in) the local SQL Server Compact database.

Dim conn = New System.Data.SqlServerCe.SqlCeConnection( _
    "Data Source=" + (System.IO.Path.Combine(System.IO.Path.GetDirectoryName( _
        System.Reflection.Assembly.GetExecutingAssembly().GetName().CodeBase), "Northwind.sdf") + _
    ";Max Database Size=2047"))

Try    ' Connect to the local database
    conn.Open()

    ' Insert a rowDim cmd = conn.CreateCommand()
    cmd.CommandText = "INSERT INTO Customers ([CustomerID], [CompanyName]) Values('NEWRW', 'Northwind Traders')"
    cmd.ExecuteNonQuery()


Catch ex As Exception
Finally
    conn.Close()
EndTry
' Reload the DataSet/Datagrid from the local database
CustomersTableAdapter.Fill(Me.NorthwindDataSet.Customers)

System.Data.SqlServerCe.SqlCeConnection conn = new System.Data.SqlServerCe.SqlCeConnection(
    ("Data Source=" + (System.IO.Path.Combine(System.IO.Path.GetDirectoryName(System.Reflection.Assembly.GetExecutingAssembly().GetName().CodeBase), "Northwind.sdf") + ";Max Database Size=2047")));
try
{
    // Connect to the local database
    conn.Open();
    System.Data.SqlServerCe.SqlCeCommand cmd = conn.CreateCommand();

    // Insert a row
    cmd.CommandText = "INSERT INTO Customers ([CustomerID], [CompanyName]) Values('NEWRW', 'Northwind Traders')";
    cmd.ExecuteNonQuery();
}

finally
{
    conn.Close();
}

// Reload the DataSet/Datagrid from the local database
customersTableAdapter.Fill(northwindDataSet.Customers);

InsertRowMenuItem inserts a new row in the Customers table in the local database.