This is an old revision of the document!

Session.SynchronizeDirectories Method

Synchronizes content of a local directory with a remote one or vice versa or mutually.

Advertisement

Syntax

C#
public SynchronizationResult SynchronizeDirectories(
    SynchronizationMode mode,
    string localPath,
    string remotePath,
    bool removeFiles,
    bool mirror = false,
    SynchronizationCriteria criteria = SynchronizationCriteria.Time,
    TransferOptions options = null
)
VB.NET
Public Function SynchronizeDirectories(
    mode As SynchronizationMode,
    localPath As String,
    remotePath As String,
    removeFiles As Boolean,
    Optional mirror As Boolean = False,
    Optional criteria As SynchronizationCriteria = SynchronizationCriteria.Time,
    Optional options As TransferOptions = Nothing
) As SynchronizationResult

Parameters

Name Description
SynchronizationMode mode Synchronization direction. Possible values are SynchronizationMode.Local, SynchronizationMode.Remote and SynchronizationMode.Both.
string localPath Full path to local directory.
string remotePath Full path to remote directory.
bool removeFiles When set to true, deletes obsolete files. Cannot be used for SynchronizationMode.Both.
bool mirror When set to true, synchronizes in mirror mode (synchronizes also older files). Cannot be used for SynchronizationMode.Both. Defaults to false.
SynchronizationCriteria criteria Comparison criteria. In the latest stable version, possible values are SynchronizationCriteria.None, SynchronizationCriteria.Time (default), SynchronizationCriteria.Size and SynchronizationCriteria.Either. In the latest beta version, the parameter is a bit field of any of SynchronizationCriteria.Time (default), SynchronizationCriteria.Size and SynchronizationCriteria.Checksum. SynchronizationCriteria.None can be used as alias to empty bit field. For SynchronizationMode.Both SynchronizationCriteria.Time can be used only.
TransferOptions options Transfer options. Defaults to null, what is equivalent to new TransferOptions().

Advertisement

Return Value

SynchronizationResult. See also Capturing results of operations.

Exceptions

Exception Condition
InvalidOperationException Session is not opened.
ArgumentException
ArgumentOutOfRangeException
Invalid combination of values of TransferOptions properties, SynchronizationMode, mirror or SynchronizationCriteria.
SessionLocalException Error communicating with winscp.com.
See the exception documentation for details.
TimeoutException Timeout waiting for winscp.com to respond.

Remarks

Event Session.FileTransferred is raised for every uploaded or downloaded file.

To further customize the synchronization, use instead a combination of Session.CompareDirectories and ComparisonDifference.Resolve. This allows synchronizing only selected differences, changing synchronization order or customizing error handling.

Examples

C# Example

using System;
using WinSCP;
 
class Example
{
    public static int Main()
    {
        try
        {
            // Setup session options
            SessionOptions sessionOptions = new SessionOptions
            {
                Protocol = Protocol.Sftp,
                HostName = "example.com",
                UserName = "user",
                Password = "mypassword",
                SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..."
            };
 
            using (Session session = new Session())
            {
                // Will continuously report progress of synchronization
                session.FileTransferred += FileTransferred;
 
                // Connect
                session.Open(sessionOptions);
 
                // Synchronize files
                SynchronizationResult synchronizationResult;
                synchronizationResult =
                    session.SynchronizeDirectories(
                        SynchronizationMode.Remote, @"d:\www",
                        "/home/martin/public_html", false);
 
                // Throw on any error
                synchronizationResult.Check();
            }
 
            return 0;
        }
        catch (Exception e)
        {
            Console.WriteLine("Error: {0}", e);
            return 1;
        }
    }
 
    private static void FileTransferred(object sender, TransferEventArgs e)
    {
        if (e.Error == null)
        {
            Console.WriteLine("Upload of {0} succeeded", e.FileName);
        }
        else
        {
            Console.WriteLine("Upload of {0} failed: {1}", e.FileName, e.Error);
        }
 
        if (e.Chmod != null)
        {
            if (e.Chmod.Error == null)
            {
                Console.WriteLine(
                    "Permissions of {0} set to {1}", e.Chmod.FileName, e.Chmod.FilePermissions);
            }
            else
            {
                Console.WriteLine(
                    "Setting permissions of {0} failed: {1}", e.Chmod.FileName, e.Chmod.Error);
            }
        }
        else
        {
            Console.WriteLine("Permissions of {0} kept with their defaults", e.Destination);
        }
 
        if (e.Touch != null)
        {
            if (e.Touch.Error == null)
            {
                Console.WriteLine(
                    "Timestamp of {0} set to {1}", e.Touch.FileName, e.Touch.LastWriteTime);
            }
            else
            {
                Console.WriteLine(
                    "Setting timestamp of {0} failed: {1}", e.Touch.FileName, e.Touch.Error);
            }
        }
        else
        {
            // This should never happen during "local to remote" synchronization
            Console.WriteLine(
                "Timestamp of {0} kept with its default (current time)", e.Destination);
        }
    }
}

Advertisement

VB.NET Example

Imports WinSCP
 
Friend Class Example
 
    Public Shared Function Main() As Integer
 
        Try 
            ' Setup session options
            Dim sessionOptions As New SessionOptions
            With sessionOptions
                .Protocol = Protocol.Sftp
                .HostName = "example.com"
                .UserName = "user"
                .Password = "mypassword"
                .SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..."
            End With
 
            Using session As New Session
                ' Will continuously report progress of synchronization
                AddHandler session.FileTransferred, AddressOf FileTransferred
 
                ' Connect
                session.Open(sessionOptions)
 
                ' Synchronize files
                Dim synchronizationResult As SynchronizationResult
                synchronizationResult =
                    session.SynchronizeDirectories(
                        SynchronizationMode.Remote, "d:\www", "/home/martin/public_html", False)
 
                ' Throw on any error
                synchronizationResult.Check()
            End Using
 
            Return 0
        Catch e As Exception
            Console.WriteLine("Error: {0}", e)
            Return 1
        End Try
 
    End Function
 
    Private Shared Sub FileTransferred(sender As Object, e As TransferEventArgs)
 
        If e.Error Is Nothing Then
            Console.WriteLine("Upload of {0} succeeded", e.FileName)
        Else
            Console.WriteLine("Upload of {0} failed: {1}", e.FileName, e.Error)
        End If
 
        If e.Chmod IsNot Nothing Then
            If e.Chmod.Error Is Nothing Then
                Console.WriteLine(
                    "Permissions of {0} set to {1}", e.Chmod.FileName, e.Chmod.FilePermissions)
            Else
                Console.WriteLine(
                    "Setting permissions of {0} failed: {1}", e.Chmod.FileName, e.Chmod.Error)
            End If
        Else
            Console.WriteLine("Permissions of {0} kept with their defaults", e.Destination)
        End If
 
        If e.Touch IsNot Nothing Then
            If e.Touch.Error Is Nothing Then
                Console.WriteLine(
                    "Timestamp of {0} set to {1}", e.Touch.FileName, e.Touch.LastWriteTime)
            Else
                Console.WriteLine(
                    "Setting timestamp of {0} failed: {1}", e.Touch.FileName, e.Touch.Error)
            End If
        Else
            ' This should never happen during "local to remote" synchronization
            Console.WriteLine(
                "Timestamp of {0} kept with its default (current time)", e.Destination)
        End If
 
    End Sub
 
End Class

Advertisement

PowerShell Example

Learn more about using WinSCP .NET assembly from PowerShell.

# Load WinSCP .NET assembly
Add-Type -Path "WinSCPnet.dll"
 
# Session.FileTransferred event handler
 
function FileTransferred
{
    param($e)
 
    if ($e.Error -eq $Null)
    {
        Write-Host "Upload of $($e.FileName) succeeded"
    }
    else
    {
        Write-Host "Upload of $($e.FileName) failed: $($e.Error)"
    }
 
    if ($e.Chmod -ne $Null)
    {
        if ($e.Chmod.Error -eq $Null)
        {
            Write-Host "Permissions of $($e.Chmod.FileName) set to $($e.Chmod.FilePermissions)"
        }
        else
        {
            Write-Host "Setting permissions of $($e.Chmod.FileName) failed: $($e.Chmod.Error)"
        }
 
    }
    else
    {
        Write-Host "Permissions of $($e.Destination) kept with their defaults"
    }
 
    if ($e.Touch -ne $Null)
    {
        if ($e.Touch.Error -eq $Null)
        {
            Write-Host "Timestamp of $($e.Touch.FileName) set to $($e.Touch.LastWriteTime)"
        }
        else
        {
            Write-Host "Setting timestamp of $($e.Touch.FileName) failed: $($e.Touch.Error)"
        }
 
    }
    else
    {
        # This should never happen during "local to remote" synchronization
        Write-Host "Timestamp of $($e.Destination) kept with its default (current time)"
    }
}
 
# Main script
 
try
{
    $sessionOptions = New-Object WinSCP.SessionOptions -Property @{
        Protocol = [WinSCP.Protocol]::Sftp
        HostName = "example.com"
        UserName = "user"
        Password = "mypassword"
        SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..."
    }
 
    $session = New-Object WinSCP.Session
    try
    {
        # Will continuously report progress of synchronization
        $session.add_FileTransferred( { FileTransferred($_) } )
 
        # Connect
        $session.Open($sessionOptions)
 
        # Synchronize files
        $synchronizationResult = $session.SynchronizeDirectories(
            [WinSCP.SynchronizationMode]::Remote, "d:\www", "/home/martin/public_html", $False)
 
        # Throw on any error
        $synchronizationResult.Check()
    }
    finally
    {
        # Disconnect, clean up
        $session.Dispose()
    }
 
    exit 0
}
catch
{
    Write-Host "Error: $($_.Exception.Message)"
    exit 1
}

Advertisement

JScript (WSH) Example

In this example the JScript script is embedded into WSF file, to allow access to enumeration values.

<job>
<reference object="WinSCP.Session" />
<script language="JScript">
 
// Session.FileTransferred event handler
 
function session_FileTransferred(sender, e)
{
    if (e.Error == null)
    {
        WScript.Echo("Upload of " + e.FileName + " succeeded");
    }
    else
    {
        WScript.Echo("Upload of " + e.FileName + " failed: " + e.Error);
    }
 
    if (e.Chmod != null)
    {
        if (e.Chmod.Error == null)
        {
            WScript.Echo(
                "Permissions of " + e.Chmod.FileName + " set to " + e.Chmod.FilePermissions);
        }
        else
        {
            WScript.Echo(
                "Setting permissions of " + e.Chmod.FileName + " failed: " + e.Chmod.Error);
        }
    }
    else
    {
        WScript.Echo("Permissions of " + e.Destination + " kept with their defaults");
    }
 
    if (e.Touch != null)
    {
        if (e.Touch.Error == null)
        {
            WScript.Echo(
                "Timestamp of " + e.Touch.FileName + " set to " + e.Touch.LastWriteTime);
        }
        else
        {
            WScript.Echo(
                "Setting timestamp of " + e.Touch.FileName + " failed: " + e.Touch.Error);
        }
    }
    else
    {
        // This should never happen during "local to remote" synchronization
        WScript.Echo(
            "Timestamp of " + e.Destination + " kept with its default (current time)");
    }
}
 
// Main script
 
try
{
    // Setup session options
    var sessionOptions = WScript.CreateObject("WinSCP.SessionOptions");
    sessionOptions.Protocol = Protocol_Sftp;
    sessionOptions.HostName = "example.com";
    sessionOptions.UserName = "user";
    sessionOptions.Password = "mypassword";
    sessionOptions.SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx...";
 
    var session = WScript.CreateObject("WinSCP.Session", "session_");
 
    try
    {
        // Connect
        session.Open(sessionOptions);
 
        // Synchronize files
        var synchronizationResult = session.SynchronizeDirectories(
            SynchronizationMode_Remote, "D:\\www", "/home/martin/public_html", false);
 
        // Throw on any error
        synchronizationResult.Check();
    }
    finally
    {
        // Disconnect, clean up
        session.Dispose();
    }
}
catch (e)
{
    WScript.Echo("Error: " + e.message);
    WScript.Quit(1);
}
 
</script>
</job>

Advertisement

Real-Life Example

Last modified: by martin