Differences
This shows you the differences between the selected revisions of the page.
| library_session_synchronizedirectories 2012-03-28 | library_session_synchronizedirectories 2024-02-15 (current) | ||
| Line 1: | Line 1: | ||
| ====== Session.SynchronizeDirectories Method ====== | ====== Session.SynchronizeDirectories Method ====== | ||
| - | [[task_synchronize_full|Synchronizes directories]]. | + | [[task_synchronize_full|Synchronizes]] content of a local directory with a remote one or vice versa or mutually. |
| - | + | ||
| - | &beta_feature | + | |
| ===== Syntax ===== | ===== Syntax ===== | ||
| Line 18: | Line 16: | ||
| <code vbnet *> | <code vbnet *> | ||
| - | Public Function SynchronizeDirectories( _ | + | Public Function SynchronizeDirectories( |
| - | ByVal mode As SynchronizationMode, _ | + | mode As SynchronizationMode, |
| - | ByVal localPath As String, _ | + | localPath As String, |
| - | ByVal remotePath As String, _ | + | remotePath As String, |
| - | ByVal removeFiles As Boolean, _ | + | removeFiles As Boolean, |
| - | ByVal Optional mirror As Boolean = False, _ | + | Optional mirror As Boolean = False, |
| - | ByVal Optional criteria As SynchronizationCriteria = 1, _ | + | Optional criteria As SynchronizationCriteria = SynchronizationCriteria.Time, |
| - | ByVal Optional options As TransferOptions = Null _ | + | Optional options As TransferOptions = Nothing |
| ) As SynchronizationResult | ) As SynchronizationResult | ||
| </code> | </code> | ||
| - | ==== Parameters ==== | + | ==== [[parameters]] Parameters ==== |
| ^ Name ^ Description ^ | ^ Name ^ Description ^ | ||
| - | | SynchronizationMode mode | [[task_synchronize_full#synchronization_mode|Synchronization mode]]. Possible values are ''SynchronizationMode.Local'', ''SynchronizationMode.Remote'' and ''SynchronizationMode.Both''. | | + | | SynchronizationMode ==mode== | [[task_synchronize_full##direction|Synchronization direction]]. Possible values are ''SynchronizationMode.Local'', ''SynchronizationMode.Remote'' and ''SynchronizationMode.Both''. | |
| - | | string localPath | Full path to local directory. | | + | | string ==localPath== | Full path to local directory. | |
| - | | string remotePath | Full path to remote directory. | | + | | string ==remotePath== | Full path to remote directory. | |
| - | | bool removeFiles | When set to ''true'', deletes obsolete files. Cannot be used for ''SynchronizationMode.Both''. | | + | | bool ==removeFiles== | When set to ''true'', deletes obsolete files. Cannot be used for ''SynchronizationMode.Both''. | |
| - | | bool mirror | When set to ''true'', synchronizes in [[task_synchronize_full#synchronization_mode|mirror mode]] (synchronizes also older files). Cannot be used for ''SynchronizationMode.Both''. Defaults to ''false''. | | + | | bool ==mirror== | When set to ''true'', synchronizes in [[task_synchronize_full#mode|mirror mode]] (synchronizes also older files). Cannot be used for ''SynchronizationMode.Both''. Defaults to ''false''. | |
| - | | SynchronizationCriteria criteria | [[ui_synchronize#comparison_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. | | + | | SynchronizationCriteria ==criteria== | [[ui_synchronize#criteria|Comparison criteria]]. The parameter is a bit field of any of ''SynchronizationCriteria.Time'' (default), ''SynchronizationCriteria.Size'' and ''SynchronizationCriteria.Checksum''. ''SynchronizationCriteria.None'' can be used as an alias to empty bit field. For backward compatibility, ''SynchronizationCriteria.Either'' can be used as an alias to ''Time %%|%% Size''. For ''SynchronizationMode.Both'', ''SynchronizationCriteria.Time'' can be used only. | |
| - | | [[library_transferoptions|TransferOptions]] options | Transfer options. Defaults to ''null'', what is equivalent to ''new TransferOptions()''. | | + | | [[library_transferoptions|TransferOptions]] ==options== | Transfer options. Defaults to ''null'', what is equivalent to ''new TransferOptions()''. | |
| ==== Return Value ==== | ==== Return Value ==== | ||
| Line 49: | Line 47: | ||
| | TimeoutException | Timeout waiting for ''winscp.com'' to respond. | | | TimeoutException | Timeout waiting for ''winscp.com'' to respond. | | ||
| - | ===== Remarks ===== | + | ===== [[remarks]] Remarks ===== |
| Event ''[[library_session_filetransferred|Session.FileTransferred]]'' is raised for every uploaded or downloaded file. | Event ''[[library_session_filetransferred|Session.FileTransferred]]'' is raised for every uploaded or downloaded file. | ||
| + | |||
| + | To further customize the synchronization, use instead a combination of [[library_session_comparedirectories|''Session.CompareDirectories'']] and [[library_comparisondifference_resolve|''ComparisonDifference.Resolve'']]. This allows synchronizing only selected differences, changing synchronization order or customizing error handling. | ||
| ===== [[example]] Examples ===== | ===== [[example]] Examples ===== | ||
| - | ==== C# Example ==== | + | |
| + | ==== [[csharp]] C# Example ==== | ||
| <code csharp> | <code csharp> | ||
| using System; | using System; | ||
| Line 65: | Line 66: | ||
| { | { | ||
| // Setup session options | // Setup session options | ||
| - | SessionOptions sessionOptions = new SessionOptions { | + | SessionOptions sessionOptions = new SessionOptions |
| + | ···········{ | ||
| Protocol = Protocol.Sftp, | Protocol = Protocol.Sftp, | ||
| HostName = "example.com", | HostName = "example.com", | ||
| UserName = "user", | UserName = "user", | ||
| Password = "mypassword", | Password = "mypassword", | ||
| - | SshHostKey = "ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" | + | SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..." |
| }; | }; | ||
| Line 81: | Line 83: | ||
| session.Open(sessionOptions); | session.Open(sessionOptions); | ||
| + | // Synchronize files | ||
| SynchronizationResult synchronizationResult; | SynchronizationResult synchronizationResult; | ||
| synchronizationResult = | synchronizationResult = | ||
| session.SynchronizeDirectories( | session.SynchronizeDirectories( | ||
| - | SynchronizationMode.Remote, @"d:\www", "/home/martin/public_html", false); | + | SynchronizationMode.Remote, @"d:\www", |
| + | ·······················"/home/martin/public_html", false); | ||
| // Throw on any error | // Throw on any error | ||
| Line 114: | Line 118: | ||
| if (e.Chmod.Error == null) | if (e.Chmod.Error == null) | ||
| { | { | ||
| - | Console.WriteLine("Permisions of {0} set to {1}", e.Chmod.FileName, e.Chmod.FilePermissions); | + | Console.WriteLine( |
| + | ····················"Permissions of {0} set to {1}", e.Chmod.FileName, e.Chmod.FilePermissions); | ||
| } | } | ||
| else | else | ||
| { | { | ||
| - | Console.WriteLine("Setting permissions of {0} failed: {1}", e.Chmod.FileName, e.Chmod.Error); | + | Console.WriteLine( |
| + | ····················"Setting permissions of {0} failed: {1}", e.Chmod.FileName, e.Chmod.Error); | ||
| } | } | ||
| } | } | ||
| Line 130: | Line 136: | ||
| if (e.Touch.Error == null) | if (e.Touch.Error == null) | ||
| { | { | ||
| - | Console.WriteLine("Timestamp of {0} set to {1}", e.Touch.FileName, e.Touch.LastWriteTime); | + | Console.WriteLine( |
| + | ····················"Timestamp of {0} set to {1}", e.Touch.FileName, e.Touch.LastWriteTime); | ||
| } | } | ||
| else | else | ||
| { | { | ||
| - | Console.WriteLine("Setting timestamp of {0} failed: {1}", e.Touch.FileName, e.Touch.Error); | + | Console.WriteLine( |
| + | ····················"Setting timestamp of {0} failed: {1}", e.Touch.FileName, e.Touch.Error); | ||
| } | } | ||
| } | } | ||
| else | else | ||
| { | { | ||
| - | // This should never happen with Session.SynchronizeDirectories | + | // This should never happen during "local to remote" synchronization |
| - | Console.WriteLine("Timestamp of {0} kept with its default (current time)", e.Destination); | + | Console.WriteLine( |
| + | ················"Timestamp of {0} kept with its default (current time)", e.Destination); | ||
| } | } | ||
| } | } | ||
| Line 146: | Line 155: | ||
| </code> | </code> | ||
| - | ==== VB.NET Example ==== | + | ==== [[vbnet]] VB.NET Example ==== |
| <code vbnet> | <code vbnet> | ||
| - | Imports System | ||
| Imports WinSCP | Imports WinSCP | ||
| Line 163: | Line 171: | ||
| .UserName = "user" | .UserName = "user" | ||
| .Password = "mypassword" | .Password = "mypassword" | ||
| - | .SshHostKey = "ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" | + | .SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..." |
| - | End with | + | End With |
| - | Using session As Session = New Session | + | Using session As New Session |
| ' Will continuously report progress of synchronization | ' Will continuously report progress of synchronization | ||
| - | AddHandler session.FileTransferred, AddressOf Example.FileTransferred | + | AddHandler session.FileTransferred, AddressOf FileTransferred |
| ' Connect | ' Connect | ||
| session.Open(sessionOptions) | session.Open(sessionOptions) | ||
| + | ' Synchronize files | ||
| Dim synchronizationResult As SynchronizationResult | Dim synchronizationResult As SynchronizationResult | ||
| - | synchronizationResult = _ | + | synchronizationResult = |
| - | session.SynchronizeDirectories( _ | + | session.SynchronizeDirectories( |
| SynchronizationMode.Remote, "d:\www", "/home/martin/public_html", False) | SynchronizationMode.Remote, "d:\www", "/home/martin/public_html", False) | ||
| ' Throw on any error | ' Throw on any error | ||
| - | synchronizationResult.Check | + | synchronizationResult.Check() |
| End Using | End Using | ||
| Line 190: | Line 199: | ||
| End Function | End Function | ||
| - | Private Shared Sub FileTransferred(ByVal sender As Object, ByVal e As TransferEventArgs) | + | Private Shared Sub FileTransferred(sender As Object, e As TransferEventArgs) |
| If e.Error Is Nothing Then | If e.Error Is Nothing Then | ||
| Line 198: | Line 207: | ||
| End If | End If | ||
| - | If Not e.Chmod Is Nothing Then | + | If e.Chmod IsNot Nothing Then |
| If e.Chmod.Error Is Nothing Then | If e.Chmod.Error Is Nothing Then | ||
| - | Console.WriteLine("Permisions of {0} set to {1}", e.Chmod.FileName, e.Chmod.FilePermissions) | + | Console.WriteLine( |
| + | ····················"Permissions of {0} set to {1}", e.Chmod.FileName, e.Chmod.FilePermissions) | ||
| Else | Else | ||
| - | Console.WriteLine("Setting permissions of {0} failed: {1}", e.Chmod.FileName, e.Chmod.Error) | + | Console.WriteLine( |
| + | ····················"Setting permissions of {0} failed: {1}", e.Chmod.FileName, e.Chmod.Error) | ||
| End If | End If | ||
| Else | Else | ||
| Line 208: | Line 219: | ||
| End If | End If | ||
| - | If Not e.Touch Is Nothing Then | + | If e.Touch IsNot Nothing Then |
| If e.Touch.Error Is Nothing Then | If e.Touch.Error Is Nothing Then | ||
| - | Console.WriteLine("Timestamp of {0} set to {1}", e.Touch.FileName, e.Touch.LastWriteTime) | + | Console.WriteLine( |
| + | ····················"Timestamp of {0} set to {1}", e.Touch.FileName, e.Touch.LastWriteTime) | ||
| Else | Else | ||
| - | Console.WriteLine("Setting timestamp of {0} failed: {1}", e.Touch.FileName, e.Touch.Error) | + | Console.WriteLine( |
| + | ····················"Setting timestamp of {0} failed: {1}", e.Touch.FileName, e.Touch.Error) | ||
| End If | End If | ||
| Else | Else | ||
| - | ' This should never happen with Session.SynchronizeDirectories | + | ' This should never happen during "local to remote" synchronization |
| - | Console.WriteLine("Timestamp of {0} kept with its default (current time)", e.Destination) | + | Console.WriteLine( |
| + | ················"Timestamp of {0} kept with its default (current time)", e.Destination) | ||
| End If | End If | ||
| Line 223: | Line 237: | ||
| End Class | End Class | ||
| </code> | </code> | ||
| + | |||
| + | ==== [[powershell]] PowerShell Example ==== | ||
| + | Learn more about [[library_powershell|using WinSCP .NET assembly from PowerShell]]. | ||
| + | |||
| + | <code 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 | ||
| + | } | ||
| + | </code> | ||
| + | |||
| + | ==== [[jscript]] JScript (WSH) Example ==== | ||
| + | In this example the JScript script is embedded into WSF file, to allow [[library_com_wsh#enums|access to enumeration values]]. | ||
| + | |||
| + | <code javascript> | ||
| + | <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> | ||
| + | </code> | ||
| + | |||
| + | ==== [[reallife]] Real-Life Example ==== | ||
| + | |||
| + | * [[library_example_delete_after_successful_download|*]]. | ||
| + | |||