Session.SynchronizeDirectories Method

Syntax
- Parameters
- Return Value
Exceptions
Remarks
Examples

Syntax

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( _
    ByVal mode As SynchronizationMode, _
    ByVal localPath As String, _
    ByVal remotePath As String, _
    ByVal removeFiles As Boolean, _
    ByVal Optional mirror As Boolean = False, _
    ByVal Optional criteria As SynchronizationCriteria = 1, _
    ByVal Optional options As TransferOptions = Nothing _
) As SynchronizationResult

Parameters

Name	Description
SynchronizationMode mode	Synchronization mode. 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. Possible values are `SynchronizationCriteria.None`, `SynchronizationCriteria.Time` (default), `SynchronizationCriteria.Size` and `SynchronizationCriteria.Either`. For `SynchronizationMode.Both` `SynchronizationCriteria.Time` can be used only.
TransferOptions options	Transfer options. Defaults to `null`, what is equivalent to `new TransferOptions()`.

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.

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 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
            };
 
            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("Permisions 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);
        }
    }
}

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 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
            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(ByVal sender As Object, ByVal 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("Permisions 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

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 {0} succeeded" -f $e.FileName)
    }
    else
    {
        Write-Host ("Upload of {0} failed: {1}" -f $e.FileName, $e.Error)
    }
 
    if ($e.Chmod -ne $Null)
    {
        if ($e.Chmod.Error -eq $Null)
        {
            Write-Host ("Permisions of {0} set to {1}" -f $e.Chmod.FileName, $e.Chmod.FilePermissions)
        }
        else
        {
            Write-Host ("Setting permissions of {0} failed: {1}" -f $e.Chmod.FileName, $e.Chmod.Error)
        }
 
    }
    else
    {
        Write-Host ("Permissions of {0} kept with their defaults" -f $e.Destination)
    }
 
    if ($e.Touch -ne $Null)
    {
        if ($e.Touch.Error -eq $Null)
        {
            Write-Host ("Timestamp of {0} set to {1}" -f $e.Touch.FileName, $e.Touch.LastWriteTime)
        }
        else
        {
            Write-Host ("Setting timestamp of {0} failed: {1}" -f $e.Touch.FileName, $e.Touch.Error)
        }
 
    }
    else
    {
        # This should never happen during "local to remote" synchronization
        Write-Host ("Timestamp of {0} kept with its default (current time)" -f $e.Destination)
    }
}
 
# Main script
 
try
{
    $sessionOptions = New-Object WinSCP.SessionOptions -Property @{
        Protocol = [WinSCP.Protocol]::Sftp
        HostName = "example.com"
        UserName = "user"
        Password = "mypassword"
        SshHostKeyFingerprint = "ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
    }
 
    $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 [Exception]
{
    Write-Host ("Error: {0}" -f $_.Exception.Message)
    exit 1
}

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("Permisions 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 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx";
 
    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>