Architecture and Classes ( Microsoft Synchronization Services)

Microsoft Synchronization Services for ADO.NET is a set of DLLs that provides a composable application programming interface (API). Depending on the architecture and needs of your application, you can use all or only some of the components provided. Synchronization Services enables synchronization between a SQL Server Compact Edition client database and a server database or any other data source, such as a service that provides stock quotes in XML. For synchronizing two databases, Synchronization Services supports two-tier and N-tier architectures using any server database for which an ADO.NET provider is available. For synchronizing between a client database and other types of data sources, Synchronization Services supports a service-based architecture. This architecture requires more application code than two-tier and N-tier architectures, but it does not require a developer to take a different approach to synchronization. Rather, it provides a great deal of flexibility for extending the architecture of your application to include synchronization.

The following diagrams show the components involved in two-tier, N-tier, and service-based architectures. The diagrams each show a single client, but there are often multiple clients synchronizing with a single server. Synchronization Services uses a hub-and-spoke model. All changes from each client are synchronized with the server before the changes are sent from the server to other clients (clients do not exchange changes directly with each other). Synchronization Services provides snapshot, download-only, upload-only, and bidirectional synchronization:

Snapshot and download-only synchronization are typically used to store and update reference data, such as a product list, on a client. Data changes that are made at the server are downloaded to the client database during synchronization. Snapshot synchronization completely refreshes data every time the client is synchronized; it is appropriate when you don't want to track incremental changes, or the server does not have the ability to do so. Download-only synchronization downloads only the incremental changes that have occurred since the previous synchronization.


Upload-only synchronization is typically used to insert data, such as a sales order, on a client. Inserts and other data changes made in the client database are uploaded to the server during synchronization.


Bidirectional synchronization is typically used for data, such as customer contact information, that can be updated at the client and server. Any conflicting changes must be handled during synchronization.


Components in the Architecture Diagrams
The components in the architecture diagrams include the client and server databases and a set of classes from the Synchronization Services API. The N-tier and service-based architectures also includes Proxy, Web Service, and Transport components that you must write.

The first diagram shows a two-tier architecture with a client database and a server database.






With the exception of the two databases, all items in the diagram correspond to Synchronization Services classes, which are contained in the following DLLs:

Microsoft.Synchronization.Data.dll contains Synchronization Agent, Synchronization Tables, and Synchronization Groups.


Microsoft. Synchronization.Data.Client.dll contains the Client Synchronization Provider.


Microsoft. Synchronization.Data.Server.dll contains the Server Synchronization Provider and Synchronization Adapters.


All the DLLs depend on System.dll and System.Data.dll from .NET Frameworks 2.0 or later. Microsoft.Synchronization.Data.Client.dll also depends on System.Data.SqlServerCe.dll from SQL Server Compact Edition. For 2-tier applications, all Synchronization Services DLLs reside on the client; for N-tier applications, Microsoft.Synchronization.Data.dll and Microsoft.Synchronization.Data.Server.dll reside on a separate computer that provides a synchronization service.





The second diagram shows an N-tier architecture, which requires a proxy, a service, and a transport mechanism to communicate between the client database and the server database. This architecture is more common than a two-tier architecture, because an N-tier architecture does not require a direct connection between the client and server databases.





The third diagram shows a service-based architecture. This architecture includes a client database, but does not include a server database or the corresponding Server Synchronization Provider and Synchronization Adapters. To use this type of architecture, your application must be able to communicate to the Synchronization Agent through a custom proxy and custom service that provides the same functionality that the Server Synchronization Provider and Synchronization Adapters usually provide, such as retrieving changes to synchronize.


Client Database
The client database for Synchronization Services applications is SQL Server Compact Edition. Synchronization Services provides an infrastructure to track incremental changes in the client database. This infrastructure is enabled the first time any table is synchronized using a method other than snapshot synchronization. Synchronization Services adds the following objects to the client database:

The system table __sysOCSDeletedRows is used to track deletes for all tables that are involved in synchronization.


The system table __sysTxCommitSequence is used to ensure transactions are tracked in the proper sequence.


The columns __sysChangeTxBsn and __sysInsertTxBsn are used to track inserts and updates. The columns are added to each table involved in synchronization.


Server Database
The server database can be any database for which an ADO.NET provider is available. For this Community Technology Preview (CTP) release, the Synchronization Services API has been tested primarily using SQL Server 2005, but we encourage you to try the API with SQL Server 2000 and recent versions of Oracle, IBM, and Sybase databases. If you want to track incremental changes in the server database, you must prepare the database to do so. For more information, see How to: Prepare a Server Database for Synchronization.

Synchronization Services Classes
The following classes are represented in the diagram: SyncAgent, ClientSyncProvider, ServerSyncProvider, SyncTables, SyncGroup, and SyncAdapter.

Synchronization Agent
The synchronization agent is the engine that drives synchronization. It loops through each of the tables to be synchronized; calls the client synchronization provider to retrieve and apply changes at the client database; and calls the server synchronization provider to retrieve and apply changes at the server database. The synchronization agent also maintains session level information for the synchronization and bubbles up success messages, errors, and statistics to the application on the client. For more information, see SyncAgent.

Client Synchronization Provider
The client synchronization provider communicates with the client and shields the synchronization agent from the specific implementation of the client database. The Synchronization Services includes a provider for the SQL Server Compact Edition database. The principal activities of the client synchronization provider are:

Storing information about tables on the client that are enabled for synchronization.


Retrieving changes that occurred in the client database since the last synchronization.


Applying incremental changes to the client database.


Detecting conflicting updates.


For more information, see SqlCeClientSyncProvider.

Server Synchronization Provider
The server synchronization provider communicates with the server and shields the synchronization agent from the specific implementation of the server database. The principal activities of the server synchronization provider are:

Storing information about tables on the server that are enabled for synchronization.


Enabling applications to retrieve changes that occurred in the server database since the last synchronization.


Applying incremental changes to the server database.


Detecting conflicting updates.


For more information, see DbServerSyncProvider.

Synchronization Table and Synchronization Group
A synchronization table is defined for each table that is synchronized. It stores settings, such as the direction of synchronization. Each client can request only the tables it needs, which might not include all the tables that the Server Synchronization Provider makes available. For example, there might be twenty tables, ten of which are configured for bidirectional synchronization in the Server Synchronization Provider. A client might request only twelve of the tables as download-only. Although the server supports upload, the client isn't required to make changes or to synchronize all tables. For more information, see SyncTable.

After a synchronization table is defined it can be added to a synchronization group. A synchronization group is a mechanism to ensure consistent application of changes for a set of tables. If tables are included in a synchronization group, changes to those tables are transferred as a unit and applied at the server in a single transaction. If any change in the group fails, changes for the entire group are retried on the next synchronization. For more information, see SyncGroup.

Synchronization Adapter
Modeled after the data adapter in ADO.NET, the synchronization adapter is defined for each table that is synchronized. It makes available to the server synchronization provider the specific commands needed to interact with the server database, such as the InsertCommand that propagates inserts on the client database to the server database. Because Synchronization Adapters use the ADO.NET DbCommand object, the developer can use any command structure supported by ADO.NET, including inline Transact-SQL, stored procedures, views, functions, and so on. The commands simply require a single result that defines the structure and data to be transferred and applied. For more information, see SyncAdapter.

Proxy, Service, and Transport
Proxy, Service, and Transport are used in N-tier and service-based architectures:

In N-tier applications, Microsoft.Synchronization.Data.Server.dll is used but it does not reside on the client. It typically resides on a middle tier that has a direct connection to the server database. In this case, a proxy and service are required to communicate between the client and the middle tier:


On the client, application code references a proxy for the server synchronization provider rather than directly referencing the provider. The proxy communicates with a service on the middle tier.


On the middle tier, the service inherits from and exposes the same methods as ServerSyncProvider (the abstract class from which DbServerSyncProvider inherits). The server synchronization provider methods are then executed over a direct connection to the server database. Results are routed through the middle tier and back to the client.


In service-based applications, Microsoft.Synchronization.Data.Server.dll is not used on the client. The application code must provide the same functionality that the Server Synchronization Provider and Synchronization Adapters normally provide:


On the client, application code references a proxy for the application code that handles server synchronization provider tasks such as retrieving changes from the data source. The proxy communicates with a service on the middle tier.


On the middle tier, the service inherits from and exposes the same methods as ServerSyncProvider (the abstract class from which DbServerSyncProvider inherits). The methods are then executed by your application code over a direct connection to the server database. Results are routed through the middle tier and back to the client.



Additional Classes in the API
The diagrams in this topic show the major classes in the API, but there are a large number of classes that are not shown. To read information about all of the available classes, see Microsoft.Synchronization.Data, Microsoft.Synchronization.Data.Client,and Microsoft.Synchronization.Data.Server. In the meantime, the following descriptions provide an introduction to four other important classes that you should be familiar with.

Synchronization Anchor
A reference point in time for a set of tables synchronized from the server. Synchronization anchors enable an application to determine which changes should be synchronized during a given session. During synchronization, the client synchronization provider stores in the client database: a last received anchor, which identifies the last change downloaded from the server; and a last sent anchor, which identifies the last change uploaded from the client. On the next synchronization, an application can use these anchors to identify the starting point for synchronizing the next set of changes. For more information, see SyncAnchor.

Synchronization Session Statistics
A set of statistics that the Synchronization Agent provides for each synchronization session. The statistics include information about synchronization times, the number of changes processed, and any conflicts or exceptions that occurred. For more information, see SyncStatistics.

Synchronization Session Variables
Variables that are made available to the developer to use as parameters for the select, insert, update, and delete commands executed at the server. The variables can be used in a number of ways, including: to provide support for conflict detection; to avoid downloading changes to a client more than once; to provide different table schema based on the client database version. The Server Synchronization Provider includes built-in session variables and allows you to create additional variables to pass information to the server. For more information, see SyncSession.

SQL Server Synchronization Adapter Builder
Modeled after the command builder in ADO.NET, the synchronization adapter builder is an aid to developing code for the synchronization commands that are executed by the server synchronization provider. The synchronization adapter builder produces select, insert, update, and delete commands for SQL Server databases based on information that you provide about the tables involved in synchronization. For more information, see SqlSyncAdapterBuilder and Tools to Aid Development (Synchronization Services).