How to: Use Session Variables
This topic shows you how to use session variables in Sync Framework. The examples in this topic focus on the following Sync Framework types:
For information about how to run sample code, see "Example Applications in the How to Topics" in Programming Common Client and Server Synchronization Tasks.
Understanding Session Variables
Sync Framework provides a set of session variables that enable you to pass values to SyncAdapter and DbServerSyncProvider commands during synchronization. These variables are specified like other parameters to queries or stored procedures in ADO.NET commands. During a synchronization session, when each ADO.NET command object is invoked by the DbServerSyncProvider, the provider goes through the synchronization parameters collection (SyncParameters) to determine if it can match each parameter to a ADO.NET command parameter based on name. If there is a match to a built-in session variable, or to a custom parameter that you have defined, the variable is populated by Sync Services before the provider calls the command.
For example, the following query selects changes from the Customer table by using the sync_last_received_anchor, sync_new_received_anchor, and sync_client_id session variables.
"SELECT CustomerId, CustomerName, SalesPerson, CustomerType FROM
Sales.Customer WHERE InsertTimestamp > @sync_last_received_anchor AND
InsertTimestamp <= @sync_new_received_anchor AND InsertId <>
@sync_client_id"
The values for these variables are supplied by Sync Framework during synchronization. You can use the variable names directly as in the previous query, or you can use the constants that are available from the SyncSession object.
"SELECT CustomerId, CustomerName, SalesPerson, CustomerType FROM
Sales.Customer WHERE InsertTimestamp > @" +
SyncSession.SyncLastReceivedAnchor +
" AND InsertTimestamp <= @" +
SyncSession.SyncNewReceivedAnchor +
" AND InsertId <> @"
SyncSession.SyncClientId
The following table lists all of the available session variables and how they are used.
Session variable |
Usage |
|---|---|
sync_client_id, sync_client_id_hash, sync_client_id_binary, and sync_originator_id |
Used to identify the client that is currently synchronizing. An ID is typically used for conflict detection and to prevent echoing of changes back to the client during bidirectional synchronization. For more information, see How to: Exchange Bidirectional Incremental Data Changes Between a Client and Server. By default, Sync Framework identifies each client with a GUID, which is returned by sync_client_id. You can also create a hash of the ID and use sync_client_id_hash in queries. sync_client_id_binary is useful when you track changes by using SQL Server change tracking. You can map the GUID from sync_client_id to an integer and use sync_originator_id. For more information, see the "Examples" section later in this topic. |
sync_last_received_anchor and sync_new_received_anchor |
Used to define the set of changes to be synchronized during a session. During the current synchronization, the command specified for the SelectNewAnchorCommand property provides a new anchor value. Changes that are made after the last received anchor value and before the new received anchor value are synchronized. The new received anchor is then stored and used as the last received anchor value for the next synchronization. For more information, see "Determining Which Data Changes to Download to a Client" in Tracking Changes in the Server Database. |
sync_force_write |
Used with an ApplyAction of RetryWithForceWrite to force the application of a change that failed because of a conflict or an error. For more information, see How to: Handle Data Conflicts and Errors. |
sync_row_count |
Returns the number of rows that were affected by the last operation at the server. In SQL Server databases, @@ROWCOUNT provides the value for this variable. A row count of 0 indicates that an operation failed, typically because of a conflict or an error. For more information, see How to: Handle Data Conflicts and Errors. |
sync_initialized |
Returns whether the current synchronization is the initial synchronization (a value of 0), or a subsequent synchronization (a value of 1). |
sync_table_name and sync_group_name |
Used if you must specify a table name or group name in a query. |
sync_batch_count, sync_batch_size, and sync_max_received_anchor |
Used if you batch changes. For more information, see How to: Specify the Order and Batch Size of Changes. |
sync_session_id |
Returns a GUID value that identifies the current synchronization session. |
Example
The following code examples show how to use session variables when you are synchronizing the Vendor table in the Sync Framework sample database.
Key Parts of the API
This section provides code examples that point out the key parts of the API that involve session variables. The following code example specifies a query for the SelectNewAnchorCommand property, which sets the value for the sync_new_received_anchor variable. This value is used by the synchronization commands that select changes from the server database.
The following code example specifies a command to select incremental updates from the server to apply to the client. The command includes anchor variables and the sync_originator_id variable. The value for the sync_originator_id variable is supplied by the query that is specified for the SelectClientIdCommand property. This query and property are described at the end of this section.
The following code example specifies a command to apply updates from the client to the server. In addition to anchor and ID variables, this command includes the sync_force_write and sync_row_count variables.
The following code example specifies a command to select incremental deletes from the server to apply to the client. In addition to anchor and ID parameters, this command includes the sync_initialized variable. In this case, rows are selected from the tombstone table only if this is a subsequent synchronization. Rows in the tombstone table are not relevant during an initial synchronization.
The following code example specifies a command to map a client ID to an originator ID. This is not required, but it can be useful to use an integer to represent a client instead of the GUID that Sync Framework uses. The stored procedure is described in the next code example.
The following code example creates a mapping table and stored procedure to read from and populate the table. The stored procedure takes a client ID (a GUID) as an input and returns an originator ID (an integer). A mapping row is inserted for the server, and additional rows are added as new clients synchronize. After a client synchronizes once, the mapping table contains an entry for this client. Because the SyncAdapter commands use the originator ID, tracking columns in the Vendor table are of type int instead of uniqueidentifier.
Complete Code Example
The following complete code example includes the code examples that are described earlier and additional code to perform synchronization. The example requires the Utility class that is available in Utility Class for Database Provider How-to Topics.