Synchro

• Download setup file - 659 Kb
• Download source - 609 Kb

Introduction

The Synchro control is a multithreaded user control allowing folder copy and synchronization. The control is visually a progress bar that can be added to a form. After its properties have been set, it can be launched by its method SyncStart. A separate thread is run so the program interface remains reactive. When it is done, it raises an event SyncDone. It may also be used in a console application, as a single thread.

The example application uses all the control properties and shows how to get information about the control status and treat the final event. It allows synchronizing several folders at the same time and saving parameters as documents. It runs both interactively or as a command line (see help for the syntax). It was not written to replace Robocopy (from Windows Resource Kit) as a tool typically used in a scheduled task: I use Robocopy to synchronize servers since it will restart in case of errors. Synchro (the application) is however much easier to use by common people.

Complete documentation and user's guide are available on my home page.

Using the code

The control is in the ctlSynchro folder. The folder can be added to your project. It is currently localized in French and English.

Put the control (say ctlSynchro1) onto your form and set its properties:

• Public strSource As String: Source directory.
• Public strTarget As String: Target folder.
• Public strExcludedStrings As String: File and folder name patterns excluded from the copy.
• Public synOptions As SyncOptions: Synchronization options, a combination of option values.
• Public strLogFile As String: Log file name.
• Public blnConsoleMode As Boolean: Choose between form/multithread or console/single thread mode.

Option values are:

• SyncCopySubDirectories = 1
• SyncCopyEmptySubDirectories = 2
• SyncOverWriteReadOnly = 4
• SyncPreserveNewerFiles = 8. This option uses the UTC time of the last file modification. It works on a NTFS file system only. Tested on a Netware file server, it always rewrites the files. Not tested on Windows 98.
• SyncCopyOnlyExistingFiles = 16
• SyncSynchronize = 32
• SyncDontPromptBeforeCreatingFiles = 64
• SyncDontPromptBeforeDeletingFiles = 128
• SyncPromptBeforeClosingWindow = 256
• SyncDontStopOnErrors = 512
• SyncLog = 1024

The example application (frmDocument form) uses checkboxes to set the options and the CalculateOptions Sub to set synOptions according to them.

Start the job with ctlSynchro1.SyncStart.

At any time, the following public properties are used to follow what the control is doing:

• Public strWhatsOn As String: Describe what the synchro thread is doing. Displayed in the "File being processed" box of the application.
• Public lngSyncCopySize As Long: Bytes to copy.
• Public lngSyncCopyDone As Long: Bytes already copied. Not used in the example: the progress bar is enough.
• Public strCopied As String(): List of completed actions. Displayed in the form list.
• Public RunningStatus As SyncStatus: Status of the copy. See below.
• Public thrSynchro As Threading.Thread: The thread run for actual synchronization itself, for special purposes.
• Public ExitStatus As SyncStatus: Status returned in console mode. Useless in multithread mode (use the status returned by SyncDone).

Running status may be:

• SyncStopped = 0: Not started or finished. The parent window should not be closed if the status is not stopped or stopping.
• SyncDeferred = 1: Deferred until the handle of the parent window is created. Never a problem if you use the .NET GDI to put the control into the form.
• SyncReady = 2: Ready: The handle has been created.
• SyncRunning = 4: Running.
• SyncCancelling = 8: Cancel requested, waiting for the synchro thread to stop. Cancel may be requested by the user (the Stop button of the example) or by the control itself if an error has occurred.
• SyncStopping = 16: Almost finished. The parent window can be closed but no other synchronization can be launched.

The frmDocument_closing Sub shows how to check that the status is actually SyncStopping or SyncStopped before closing the form.

During the process, it may be useful to show detailed information about what is going on. By default, the progress bar is the only thing visible. A way to do this is to use a timer. In the example, a timer is activated just after SyncStart and regularly (the frequency is chosen as an option) runs RefreshDisplay. See the code for details.

The process can be aborted by the SyncStop method (called by the Stop button on the form).

When the synchronization is done, a SyncDone event is raised by the control. A handler must be added to the form code. It may use a message box to confirm the results. In the example, LocRM is the resource manager used to localize the program and string names are quite explicit. The arguments (SynchroResults class) return the exit status of the process (see the code below for all values) and the options used when SyncStart was launched (the current options of the control may have been changed if another synchronization has just been started).

 Private Sub SynchroDone(ByVal sender As System.Object, _
      ByVal e As SynchroResults) Handles CtlSynchro1.SyncDone
  ' Run when the synchro is finished


  ' Stop the display timer

  Timer1.Stop()
  ' Flush the display

  RefreshDisplay(Me, EventArgs.Empty)
  ' Clean the display

  If (e.Options And SyncOptions.SyncPromptBeforeClosingWindow)_
            = SyncOptions.SyncPromptBeforeClosingWindow Then
    ' Nothing is being processed any longer

    Me.txtFileOn.Text = ""
    ' Prompt it is finished

    Select Case e.Status
     Case SyncStatus.SyncSucceeded
       MsgBox(LocRM.GetString("strCopyFinished"), _
                   MsgBoxStyle.Information, Me.Text)
     Case SyncStatus.SyncCancelled
       MsgBox(LocRM.GetString("strCopyCancelled"), _
                   MsgBoxStyle.Information, Me.Text)
     Case SyncStatus.SyncFailed
       MsgBox(LocRM.GetString("strCopyFailed"), _
                   MsgBoxStyle.Information, Me.Text)
     Case SyncStatus.SyncNothingToDo
       MsgBox(LocRM.GetString("strNothingToDo"), _
                   MsgBoxStyle.Information, Me.Text)
    End Select
    ' Change the buttons after copy

    btnStart.Enabled = True
    btnStop.Enabled = False
  Else
    Me.Close()
  End If
End Sub

Finally, the thread thrSynchro can be accessed directly for advanced purposes: you may want to suspend it or wait for it to complete (join).

Other people's work

• The Arguments class, a command line parser, is a straight Basic adaptation of the C# version available on Code Project.
• FolderBrowser, the folder browser control by Rama Krishna, is on Code Project. The C# project was slightly modified and included in the solution.
• AboutBox the about box, and the .NET Animation Control are from Code Project too.

History

• 1.5
  • Minor bug correction.
  • Added animation.
  • Added /g option.
• 1.4
  • The engine is now a control, it can be reused easily.
  • The .NET framework is used to handle files instead of the FileSystemObject.
  • Multithreaded.
  • Much cleaner console mode.
• 1.3: Resizing added.
• 1.2: Exclusion option added.
• 1.1: Help added.
• 1.0: First public version.