Tag Archives: Sync

Microsoft Sync Framework

I was excited to learn that Microsoft has developed a sync framework which is free and available for download. Programming for the web normally saves the need to sync stuff, because there are no client databases which can go out of sync, and server-side databases have their bulit-in replication solutions. So there’s usually very little development that you must do on your own for syncing data sources. There are also solutions for syncing file systems, so you may choose these when required. However, there are certain scenarios in which you have to develop sync code yourself. These include for example syncing sources from a remote hardware which is “occasionally connected”, such as mobile or tabular devices; Non-web solutions for desktops; syncing between databases which are not of the same type (Oracle and SQL Server etc.); or a mere custom action involving sync in your application. While sync in itself isn’t rocket science, it’s still a non-trivial, time-consuming and bug potential feat. That’s why I wanted to learn a little more of this sync framework, which has been around for quite some time now.

I was hoping that as the Sync framework was around for some time, that I’ll find plentiful of blog, samples and articles. I was also hoping that the official sync web site would be friendly and that it’ll get me up and running in no-time. This wasn’t the case. While there was a useful sample code for using the file synchronization, available directly from the sync home page, the database samples were no where to be found, and the home page was filled with datasheets and architecture descriptions which may be important, but lack the samples to accompany them. It took me some time to detect the samples after installing the SDK, in the Program Files folders, as there’s no shortcut from the start menu to that location. The SDK was also a pain to install because there are multiple downloads involved instead of a single file installation. In particular, it seems like MS forces you to answer a survey in order to download the v4 CTP. In order to hasten installation, I suggest that you go to the v4 CTP “installation” url, scroll down and follow the instructions according to your OS (32/64 bit). Regardless, the samples here were created in v2.1 of the sync framework and require the following installations:

  1. SyncSDK v2.1.
  2. Synchronization v2.1.
  3. Database Providers v3.1.

If you’d still like to download the v4 CTP, go here. According to the documentation, the November Refresh contains an iPhone sample and a “Tooling Wizard UI” which allows you to configure sync related operations.

File sync

I decided to write about File sync first, as this seemed most trivial and easy to accomplish using MS’ built-in file sync provider and sample. In order to implement a file sync solution, simply add references to Microsoft.Synchronization and Microsoft.Synchronization.Files assemblies from your project, create dummy folders for source and target directories with dummy files, and write the following code:

That’s it! Several lines of code and we have a fully operational file sync, including sub folders sync. I find it quite amazing, and it can give us some idea as to how easy it should be to sync other providers. The code is self explanatory, but I do have some comments:

  1. The default sync direction is bi-directional Upload and Download, but this can be controlled via the SyncOrchestrator.Direction property.
  2. The FileSyncProvider different constructors work with “local file paths”, but it also works with a UNC path. It does not seem to be working with “file://” and I assume that it does not work with “ftp://” paths either.
  3. The FileSyncProvider creates a metadata file, which contains replica information required for the synchronization.
  4. You can provide a FileSyncScopeFilter file filter object to the FileSyncProvider constructors, thus have more control over which files are synced.
  5. You can set the options enumeration flags to recycle the different overwritten files instead of permanently deleting them.
  6. The Synchronization( ) method returns a stats object containing basic data about the completed synchronization.

The above sample is the most basic a developer may require for synchronization. On top of this sample, you can bind synchronization events and conflict resolution. For example, you can wire an event handler to the ApplyingChange event and control whether files should be skipped synchronization at runtime. Note that this will only work if FileSyncProvider.DetectChanges( ) is called either implicitly by the SyncOrchestrator.Synchronize( ) method, or explicitly if the FileSyncProvider options specifies that DetectChanges is to be called explicitly.

Note: If you come across the following exception, check out that the project file is set to compile to the correct platform or to “Any CPU”:

Retrieving the COM class factory for component with CLSID {031913FE-EB2A-49F2-B2BE-B996B2448CD4} failed due to the following error: 80040154 Class not registered (Exception from HRESULT: 0x80040154 (REGDB_E_CLASSNOTREG)).

SQL Server sync

Now I felt like it was time to move on to what I considered the major requirement for the sync framework – database synchronization. I decided to settle for synching 2 SQLServer Express schemas at first. No Compact, Azure or another non-SQL DB – just to get things started. I setup two SQL Server 2008 Express databases and wrote the following code, which was simply based on the FileSyncProvider written earlier:

I really didn’t know what to expect, because I could not find a simple straight forward example. I read that the sync creates it’s own metadata database independently from the actual data being synchronized, but I didn’t know if that will be automatic like the FileSyncProvider had done. So, at first, I got the following error:

Retrieving the COM class factory for component with CLSID {EC413D66-6221-4EBB-AC55-4900FB321011} failed

Apparently you have to install the Synchronization-v2.1-x86-ENU.msi in order to use database synchronization from VS2010, even if you’re running on a x64 based machine. I installed, ran the code and this time I got the following DbNotProvisionedException error:

The current operation could not be completed because the database is not provisioned for sync or you not have permissions to the sync configuration tables.

Unlike FileSyncProvider, this isn’t entirely an automated process. You have to “provision” your databases first in order to get this to work. In the Program Files Sync SDK folder, there are some examples which help out to understand how to do this, specifically SharingAppDemo-CEProviderEndToEnd and WebSharingAppDemo-CEProviderEndToEnd projects in the SDK folder. After experimenting a little, I came up with the following code:

Note lines 22-23. Line 22 prepares the server for provisioning, and line 23 prepares the client for provisioning. In the sample code from the SDK, comments which accompany the server side provisioning samples indicate that this code is typically run at “design time”, and not at sync time, and that it should not be “baked” into the client application. So bear in mind that in real-world applications, lines 22-23 should not co-exist next to each other.

Also note lines 18-19. As you can see, there’s a provisioning “scope” which I believe allows you to synchronize specific parts of the databases, rather then synchronize entire databases.

The code for those methods is as follows:

Lines 33-47 is the method implementation for server side provisioning:

  • Line 37 checks whether provisioning is required on the server side for the given scope.
  • Lines 39-40 defines the table(s) which are included in the synchronization process for the specified scope.
  • Line 42 populates the information from the scope definition.
  • Line 44 defines the behavior upon provisioning.
  • Line 45 performs the actual provisioning.

Lines 49-58 is the method implementation for client side provisioning:

  • Line 52 checks whether provisioning is required in the client side, for the specified scope.
  • Line 54 retrieves the provisioning information from the server side (no need to redefine the tables as we did in the server side provisioning).
  • Line 55 populates the provisioning information according to the retrieved server description.
  • Line 56 performs the actual provisioning in the client.

This newer code seems to do the trick. The databases seem to be synchronizing well, post insert, delete and update statements, both ways.

I tried to rename a table column but the synchronize can’t seem to detect that change and I received an exception. I found this article, which addresses sync scope schema changes. The article states that this is one of the most requested features of the sync framework, so maybe we can expect some automatic implementation in future versions to come.

More Resources


This wasn’t as trivial as I expected it to be. The FileSyncProvider is indeed very simple to use and code, mostly because theĀ Introduction to Microsoft Sync Framework File Synchronization Provider article is available directly from the sync home page. However, the database synchronization counterpart official document contains no sample code and focuses mainly on architecture, with no links to actual concrete code samples. I spent quite some time in detecting those code samples in the SDK (as there’s no link to them from the Start menu either). Don’t get me wrong – I think that the sync framework can be a great solution; more over, I reckon that there are official links and blogs that show more and more examples, but these should be available directly from the homepage, so developers can get started within 30 minutes to sync their databases.

BTW: Sync framework v4 CTP is from October 2010, “Refreshed” in November. That’s from last year. Is this going to be another one of MS’ deprecated projects? Except for the recently released (Sep 2011) Sync Framework Toolkit (available from the blogs), there are hardly any recent blogs. Prior to the Sync Framework Toolkit blog entry, the next recent post is dated six months ago. How do we developers know if we should put more effort and rely on this framework?


Posted by on 27/09/2011 in Software Development