Tracing the Synchronization Process
This topic shows how to use the tracing infrastructure and tracing class in Sync Framework. The examples in this topic focus on the following Sync Framework types and events:
The ApplyChangeFailed event and DbApplyChangeFailedEventArgs object.
For information about how to run sample code, see "Example Applications in the How-to Topics" in Synchronizing SQL Server and SQL Server Compact.
Understanding Tracing in Synchronization Services
Tracing involves recording application operations, data, and metadata, and providing this information to a listener. A listener frequently writes trace information to a file, but could also handle the information in other ways. Sync Framework includes tracing for the database synchronization providers. In distributed applications, tracing can be very important because it enables you to troubleshoot issues that might otherwise be difficult to discover.
Tracing in Sync Framework is composed of the following components:
A tracing infrastructure that is based on the .NET Framework implementation of tracing, specifically the TraceListener class. The most important operations of the database providers are traced, and key metadata is provided to one or more listeners.
The SyncTracer object. This enables you to determine which level of tracing is enabled and to write messages to the trace output based on application events.
In addition to the tracing components that Sync Framework provides, troubleshooting typically involves other tools, such as a debugger or SQL Server Profiler. For example, trace output could include information about a SQL Server database, and then you would use SQL Server Profiler to obtain more detail about database activity that was generated by the server synchronization provider.
Using the Tracing Infrastructure
By default, tracing is not enabled for Sync Framework applications. To configure a trace listener, include an application configuration (AppName.exe.config) file in the same folder as your managed application executable. For more information about this file, see the Visual Studio documentation. In this file, you can add a listener, set its type and related parameters, remove a listener, or clear all the listeners that were previously set by the application. For more information, see the .NET Framework documentation about tracing. The configuration file should resemble the following example.
The following XML nodes are included in the example code:
A listener of type System.Diagnostics.TextWriterTraceListener (TextWriterTraceListener), with the output file name: TraceSample.log.
A switch called SyncTracer. This has a value of 3. The following table shows all the values and how they relate to trace output.
Switch value
Tracing level
Output
0
off
No messages to trace listeners.
1
error
Only error messages to trace listeners.
2
warning
Error and warning messages to trace listeners.
3
info
Informational, warning, and error messages to trace listeners.
4
verbose
All messages to trace listeners.
Tracing does have some overhead. Therefore, you should balance tracing against the performance requirements of your application. In most cases, info and verbose settings are only appropriate during application development and troubleshooting.
The following configuration file shows an example for devices.
The file should be named trace.config.txt and should be placed in the application directory on the device. If you include the file in a Visual Studio solution, it can be deployed with the application.
The following file segment is from a trace that was configured by using a SyncTracer value of 3. Each line begins with the kind of output. In this case, all the output is INFO. If an error occurred, the relevant lines would begin with ERROR.
INFO, MyApp.vshost, 10, 07/01/2010 17:43:03:027, Connecting to server using string: Data Source=localhost;Initial Catalog=SyncSamplesDb;Integrated Security=True
INFO, MyApp.vshost, 10, 07/01/2010 17:43:03:027, ----- Server Enumerating Changes to Client for Group "Customer" -----
INFO, MyApp.vshost, 10, 07/01/2010 17:43:03:027, Client Id: bc5610f6-bf9c-4ccd-8599-839e54e953e2
INFO, MyApp.vshost, 10, 07/01/2010 17:43:03:027, Mapped Originator Id: 0
INFO, MyApp.vshost, 10, 07/01/2010 17:43:03:042,
INFO, MyApp.vshost, 10, 07/01/2010 17:43:03:042, ----- Enumerating Inserts for Table Customer -----
INFO, MyApp.vshost, 10, 07/01/2010 17:43:03:058, Changes Enumerated: 5
INFO, MyApp.vshost, 10, 07/01/2010 17:43:03:058, --- End Enumerating Inserts for Table Customer ---
Using the SyncTracer Object
The SyncTracer object enables you to write application-specific tracing data to the trace file. This can provide contextual information about what an application is doing at a specific time. This object enables you to perform the following tasks:
Determine which level of tracing is enabled, by using the following methods:
Write messages to the trace output based on application events, by using the following methods, and other overloads for each method:
For example, to output an informational message, you can use the following code:
SyncTracer.Info("Informational message")
If the Info level is enabled, the message is written to the output; otherwise, it is ignored.
More complex messages can be formed also, such as the following. The numbers that are specified set the level of indentation in the output file.
SyncTracer.Verbose("Processing table t1")
SyncTracer.Verbose(1, "Applying Deletes")
SyncTracer.Verbose(2, "{0} rows deleted", numDeleted)
SyncTracer.Verbose(1, "Applying Inserts")
SyncTracer.Verbose(2, "{0} rows inserted", numInserted)
The output is as follows:
Processing table t1
Applying Deletes
7 Rows Deleted
Applying Inserts
9 Rows inserted
The following code example writes information to the console about which tracing levels are enabled. The configuration file specifies a value of 3 for the SyncTracer switch. This corresponds to Info. Therefore, Error, Warning, and Info return True, and Verbose returns False.
The following code example shows how to write formatted warning messages about data conflicts to the trace output. For more information about conflicts, see How to: Handle Data Conflicts and Errors for Database Synchronization (SQL Server). Verbose tracing includes information about conflicts. In this application, verbose tracing is disabled, and the application flags conflicts with a warning instead.
Checking which levels of tracing are enabled can help you avoid potentially costly processing. In the example code, the application avoids additional processing if verbose tracing is already enabled. Conversely, the application might generate output only when a certain tracing level is enabled.
Security Considerations for Tracing
Trace files can include information about server and client computers, application data, and logins. (Passwords are not written to the trace file.) If verbose tracing is enabled, each changed row from the database is written to the trace file. Help protect the trace file by using the appropriate access control lists.
Complete Code Example
The following complete code example includes the code examples that are described earlier in this topic and additional code to perform synchronization. Before you run the application, perform the following steps:
Create a project in Visual Studio.
Add references to the Sync Framework DLLs and the Utility class that is available in Utility Class for Database Provider How-to Topics.
Create a configuration file and copy the XML code from the example shown earlier in this topic.
Be aware of the calls to methods in the Utility class:
Utility.MakeFailingChangeOnNode(Utility.ConnStr_SqlSync_Client) This makes a change at the client that fails when it is applied at the server. The constraint violation and related application exception are automatically written to the trace file as warnings.
Utility.MakeConflictingChangeOnNode(Utility.ConnStr_SqlSync_Client, "Customer") and Utility.MakeConflictingChangeOnNode(Utility.ConnStr_SqlSync_Server, "Customer") These make changes at the client and server that conflict when they are synchronized. The conflicts are written to the trace file in the SampleSyncProvider_ApplyChangeFailed event handler.
After you run the application, open the trace output file to see the messages that are written automatically; and the conflict warnings, which are the result of application code.