Microsoft Sync Framework

27 Sep

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



15 responses to “Microsoft Sync Framework

  1. jtabadero

    04/10/2011 at 16:51

    The Sync Framework v4 CTP you are pointing to is outdated. MS cancelled releasing a v4 and released what was in the CTP as the open-source Sync Framework Toolkit instead.

    See: for the announcement and download link.

    You can find most of the sample codes at:

    In addition, the documentation that comes with Sync Framework SDK comes with step-by-step tutorials/walkthroughs.

    • evolpin

      04/10/2011 at 20:45

      I guess that this is what I was trying to express: the sync website is not updated with the proper resources. For example, the Sync Framework 4 CTP that “I pointed too”, is from the front/home page of the sync website. If it is indeed outdated and replaced by the Sync Framework Toolkit as you say, then it should have been reflected in the website.

      Thanks for pointing this out though, and including those links.

  2. exae

    26/10/2011 at 00:18

    static void PrepareClientForProviing(SqlSyncProvider provider)
    SqlConnection connection = (SqlConnection)provider.Connection;
    SqlSyncScopeProvisioning config = new SqlSyncScopeProvisioning(connection);
    if (config.ScopeExists(provider.ScopeName) == false)
    DbSyncScopeDescription scopeDesc = new DbSyncScopeDescription(provider.ScopeName);
    Cannot provision a scope that includes zero tables. Please add tables to your DbSyncScopeDescription to define the set of tables for this scope.

  3. exae

    26/10/2011 at 00:23

    static void PrepareClientForProviing(SqlSyncProvider provider)
    SqlConnection connection = (SqlConnection)provider.Connection;
    SqlSyncScopeProvisioning config = new SqlSyncScopeProvisioning(connection);
    if (config.ScopeExists(provider.ScopeName) == false)
    DbSyncScopeDescription scopeDesc = new DbSyncScopeDescription(provider.ScopeName);
    scopeDesc.Tables.Add(SqlSyncDescriptionBuilder.GetDescriptionForTable(“Products”, connection));

    thanks evolpin.

  4. victor

    28/07/2012 at 07:47

    Is Sync Framework worth using if there is very little documentation on it and also very few samples. I can’t find a sample that works with Visual Studio 2010 and n-tier with SQL Server Express. I think replication is the easy way to sync DBs.

    • evolpin

      28/07/2012 at 08:03

      I think that if you only need to sync DBs, you better consider a replication. I would consider using the Sync framework for something “less conventional”, like syncing stuff that has no built-in sync feature, or when you require more control over what you wish to sync.

      • Carlos Alberto

        21/09/2012 at 19:10

        Hi evolphin, thank you very much for the explanation.

        I’m tryng to use Framework Sync based on a sql server 2008 express edition server which needs to be synchronized with other participants using sql server compact 3.5sp2, besides that, participants should be able to syncronize to each other (with no server intervention), since I need to deal with binary fields in some tables I’ve just decided to use the FileStream attribute feature starting from version 2008 of sql server express to achieve best scalability, I read this feature is not supported in sql server compact 3.5sp2 not even for version 4, mi intention was to make synchronization transparent, I know it sounds really nice, but now that I know it’s simple impossible, ¿What would you recommend?

        Thank you very much in advance

      • evolpin

        23/09/2012 at 09:01

        I’m not familiar with the Compact DB so I can’t really provide a good advice here, but several options come to mind: switching from FileStream data type; Syncing to a different data type on the Compact DB; Converting the binary to Base64 w/compression and storing in a varchar field (if the files are of small size).

  5. Fara

    01/03/2014 at 14:54

    I am new bee please guide me how I can resolve this issue.

    Cannot find a valid scope with the name ‘SyncExpressDB’ in table ‘[scope_info]’. Ensure that this scope exists and that it has a corresponding valid configuration in the configuration table ‘[scope_config]’.

    and please tell me that what is “SyncDB” In your code is Scope1
    var provider1 = new SqlSyncProvider(“SyncDB”, serverconn);

    This error is coming in PrepareClientForProvisioning method

  6. yusuf

    15/04/2014 at 14:53

    ERROR is occured : Cannot add the SyncAdapter to the SyncAdapterCollection. A SyncAdapter for table ‘EMPLOYEE’ already exists.

  7. best website solutions

    18/04/2014 at 13:33

    very very help full save my lots of time thanks

  8. best website solutions

    18/04/2014 at 13:34

    is there a way we provide ftp folder path to destination

  9. Abhinav

    09/08/2014 at 11:59

    Thanks for solution now it works………

  10. fruitbus

    21/10/2014 at 10:40

    Great post, thanks! The article is very useful.

    * I guess this tutorial also will be interesting for the readers –

  11. Andrew Klinman

    27/04/2015 at 21:10

    The only thing that doesn’t seem to work regarding this is when deleting a file at the source the corresponding destination file is not deleted. Is there any way to do this, so that we don’t end up with a bunch of “orphan” files?


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: