How to: Synchronize Files by Using Managed Code
This topic shows how to use a managed language, such as C# or Visual Basic, to create an application that synchronizes files and subfolders by using the Sync Framework file synchronization provider.
The examples in this topic focus on the following Sync Framework types:
Understanding File Synchronization
Sync Framework implements a synchronization provider that can be used to synchronize files and subfolders that are contained in a folder on a file system. This provider exposes several configurable settings to give a finer degree of control over exactly how synchronization occurs and which items are synchronized. To synchronize files between two folders, an application completes the following basic steps:
Creates an FileSyncProvider object to represent each folder.
Passes the two providers to an SyncOrchestrator object, and specifies one as the source provider and the other as the destination provider.
Calls Synchronize to start the synchronization session.
For more information about synchronizing files, see Synchronizing Files.
Example
The example code in this section is from a console application that synchronizes two directories, including the subdirectories and files in those directories. The example code shows the following tasks:
How to set synchronization options.
How to explicitly perform change detection for a replica.
How to specify a filter that controls which items are included in synchronization.
How to handle conflicts that can occur during synchronization.
How to synchronize two replicas.
After showing these code examples, we include the complete code for the application so that you can build and run it.
Setting Synchronization Options
The FileSyncOptions object enables you to set several options for file synchronization, including how to detect changes and whether to delete items during synchronization or move them to the Recycle Bin. The following code example sets four options, three of which are related to item deletes. The option ExplicitDetectChanges means that Sync Framework will not perform change detection unless the application explicitly calls DetectChanges. This is explained in the next section "Performing Change Detection".
Performing Change Detection
By default, Sync Framework performs change detection at both replicas whenever Synchronize is called. Change detection enables Sync Framework to determine which items should be sent from the source to the destination and which items, if any, are in conflict. By specifying ExplicitDetectChanges, you can control when change detection is performed. The following code example calls change detection for each replica before Synchronize is ever called. This example is meant to illustrate DetectChanges, but it does have the benefit of having one change detection pass rather than the two that would occur when we perform bidirectional synchronization later in the application.
Specifying a Static Filter
Static filters can be set to exclude files by name (including wildcard names) and by attribute. Static filters can also be set to exclude the contents of whole subfolders. Or, an explicit list of file names to include (including wildcard names) can be specified. To be included in the scope, a file or a folder must pass all filters. For example, if all files that have a .txt extension are excluded from the scope and MyFile.txt is specified in the list of files to explicitly include in the scope, MyFile.txt will be excluded because of its .txt extension.
The following code example uses the FileSyncScopeFilter object to create a filter that excludes all *.lnk files. A filter has no relationship to its creating provider. To connect a filter to a provider, pass the filter to one of the constructors for FileSyncProvider or by setting the ScopeFilter property. In the sample application, we do this in the DetectChangesOnFileSystemReplica() method because the filter is relevant only for change detection. Because the filter is independent of the provider, only one filter should be created per synchronization session; providers should not use different filters, because this can lead to non-convergence of data.
In addition to static filters, you can also exclude files during synchronization by handling an event raised by the provider. For more information, see Controlling Which Files Are Synchronized.
Handling Conflicts
Sync Framework detects and resolves concurrency conflicts and constraint conflicts for files and folders. A concurrency conflict occurs when the same item is changed at both replicas since the last synchronization session between those replicas. A constraint conflict occurs if a file or folder with the same name is added to both replicas. Conflicts are resolved by keeping the file or folder with the most recent change and deleting (or moving) the file or folder with the older change. For files, you also have the option of specifying that the source or destination should win the conflict, regardless of which change occurred first. The following code example registers event handlers for the ItemConflicting and ItemConstraint events that are available through the SyncCallbacks object. The methods that are called resolve all conflicts in favor of the source and write information to the console.
Synchronizing Two Replicas
After options and filters are set, the application synchronizes the two replicas by instantiating a SyncOrchestrator, and calling the Synchronize method. The following code example specifies the provider for each replica, sets options, registers event handlers, specifies a synchronization direction of Upload, and calls Synchronize. The method is called twice to perform bidirectional synchronization between the replicas.
Complete Code Example
The following code is the complete code for this example. The previous examples in this section were taken from this code. To run this code:
Create a console application project, and add the code to the project.
Add references to Microsoft.Synchronzation.dll and Microsoft.Synchronzation.Files.dll.
Build the project to create an executable.
Run the executable from the command line to synchronize the files and subdirectories of two replica directories: MyExeName.exe \path\to\directoryA \path\to\directoryB.
In the Visual Basic example, the code explicitly sets the MTAThread attribute on the Main() method. File synchronization provider requires applications to use the multithreaded apartment (MTA) threading model.
See Also
Reference
Microsoft.Synchronization.Files