Differences
This shows you the differences between the selected revisions of the page.
library_session_getfiles 2012-03-21 | library_session_getfiles 2022-08-12 (current) | ||
Line 2: | Line 2: | ||
[[task_download|Downloads]] one or more files from remote directory to local directory. | [[task_download|Downloads]] one or more files from remote directory to local directory. | ||
- | &beta_feature | + | You can have WinSCP [[guide_automation#generating|generate a code template]] for ''Session.GetFiles'' for you. |
+ | |||
+ | The method is quite powerful, but due to a wide range of it uses, its syntax can be cumbersome initially. For specific tasks, consider using convenient alternatives: [[library_session_getfilestodirectory|''Session.GetFilesToDirectory'']] and [[library_session_getfiletodirectory|''Session.GetFileToDirectory'']]. | ||
===== Syntax ===== | ===== Syntax ===== | ||
- | <code csharp> | + | <code csharp *> |
public TransferOperationResult GetFiles( | public TransferOperationResult GetFiles( | ||
string remotePath, | string remotePath, | ||
Line 14: | Line 16: | ||
</code> | </code> | ||
- | ==== Parameters ==== | + | <code vbnet *> |
+ | Public Function GetFiles( | ||
+ | remotePath As String, | ||
+ | localPath As String, | ||
+ | Optional remove As Boolean = False, | ||
+ | Optional options As TransferOptions = Nothing | ||
+ | ) As TransferOperationResult | ||
+ | </code> | ||
+ | |||
+ | ==== [[parameters]] Parameters ==== | ||
^ Name ^ Description ^ | ^ Name ^ Description ^ | ||
- | | string remotePath | Full path to remote file or directory to download. Filename in the path can be replaced with [[file_mask|wildcard]] to select multiple files. When file name is omited (path ends with slash), all files and subdirectories in the remote directory are downloaded. | | + | | string ==remotePath== | Full path to remote directory followed by slash and [[library_wildcard|wildcard]] to select files or subdirectories to download. To download all files in a directory, use mask ''*''. ·| |
- | | string localPath | Full path to download the file to. When downloading multiple files, the filename in the path should be replaced with [[operation_mask|operation mask]] or omited (path ends with backslash). | | + | | string ==localPath== | Full path to download the file to. When downloading multiple files, the filename in the path should be replaced with [[operation_mask|operation mask]] or omitted (path ends with backslash). | |
- | | bool remove | When set to ''true'', deletes source remote file(s) after transfer. Defaults to ''false''. | | + | | bool ==remove== | When set to ''true'', deletes source remote file(s) after a successful transfer. Defaults to ''false''. | |
| [[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()''. | | ||
Line 24: | Line 35: | ||
''[[library_transferoperationresult|TransferOperationResult]]''. See also [[library_session#results|Capturing results of operations]]. | ''[[library_transferoperationresult|TransferOperationResult]]''. See also [[library_session#results|Capturing results of operations]]. | ||
- | ===== Exceptions ===== | + | ===== [[exceptions]] Exceptions ===== |
^ Exception ^ Condition ^ | ^ Exception ^ Condition ^ | ||
| InvalidOperationException | Session is not opened. | | | InvalidOperationException | Session is not opened. | | ||
| ArgumentException \\ ArgumentOutOfRangeException | Invalid combination of values of ''[[library_transferoptions|TransferOptions]]'' properties. | | | ArgumentException \\ ArgumentOutOfRangeException | Invalid combination of values of ''[[library_transferoptions|TransferOptions]]'' properties. | | ||
| [[library_sessionlocalexception|SessionLocalException]] | Error communicating with ''[[executables#winscp.com|winscp.com]]''. \\ See the exception documentation for details. | | | [[library_sessionlocalexception|SessionLocalException]] | Error communicating with ''[[executables#winscp.com|winscp.com]]''. \\ See the exception documentation for details. | | ||
+ | | [[library_sessionremoteexception|SessionRemoteException]] | Session has failed. \\ Downloading of files has failed. \\ See the exception documentation for details. | | ||
| TimeoutException | Timeout waiting for ''winscp.com'' to respond. | | | TimeoutException | Timeout waiting for ''winscp.com'' to respond. | | ||
===== Remarks ===== | ===== Remarks ===== | ||
- | Event ''[[library_session_filetransferred|Session.FileTransferred]]'' is raised for every downloaded file. | + | Event ''[[library_session_filetransferred|Session.FileTransferred]]'' is raised for every downloaded file. Also raises [[library_session_filetransferprogress|''Session.FileTransferProgress'']] throughout the transfer. |
+ | |||
+ | The download aborts on the first error. See how to [[library_example_recursive_download_custom_error_handling|implement recursive directory tree download with custom error handling]]. | ||
+ | |||
+ | ===== [[example]] Examples ===== | ||
- | ===== Example ===== | ||
==== [[csharp]] C# Example ==== | ==== [[csharp]] C# Example ==== | ||
<code csharp> | <code csharp> | ||
using System; | using System; | ||
- | using System.Globalization; | ||
- | using System.IO; | ||
using WinSCP; | using WinSCP; | ||
Line 49: | Line 62: | ||
{ | { | ||
// 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 62: | Line 76: | ||
session.Open(sessionOptions); | session.Open(sessionOptions); | ||
- | string stamp = DateTime.Now.ToString("yyyyMMdd", CultureInfo.InvariantCulture); | + | // Download files |
- | string fileName = "export_" + stamp + ".txt"; | + | TransferOptions transferOptions = new TransferOptions(); |
- | string remotePath = "/home/user/sysbatch/" + fileName; | + | transferOptions.TransferMode = TransferMode.Binary; |
- | string localPath = "d:\\backup\\" + fileName; | + | |
- | + | ···············TransferOperationResult transferResult; | |
- | // Manual "remote to local" synchronization. | + | ···············transferResult = |
- | + | session.GetFiles("/home/user/*", @"d:\download\", false, transferOptions); | |
- | // You can achieve the same using: | + | |
- | // session.SynchronizeDirectories( | + | ···············// Throw on any error |
- | // SynchronizationMode.Local, localPath, remotePath, false, false, SynchronizationCriteria.Time, | + | ···············transferResult.Check(); |
- | // new TransferOptions { IncludeMask = fileName }).Check(); | + | |
- | if (session.FileExists(remotePath)) | + | ···············// Print results |
- | { | + | ···············foreach (TransferEventArgs transfer in transferResult.Transfers) |
- | bool download; | + | |
- | if (!File.Exists(localPath)) | + | |
- | { | + | |
- | ·······················Console.WriteLine("File {0} exists, local backup {1} does not", remotePath, localPath); | + | |
- | ·······················download = true; | + | |
- | } | + | |
- | else | + | |
- | { | + | |
- | DateTime remoteWriteTime = session.GetFileInfo(remotePath).LastWriteTime; | + | |
- | DateTime localWriteTime = File.GetLastWriteTime(localPath); | + | |
- | + | ||
- | if (remoteWriteTime > localWriteTime) | + | |
- | ························{ | + | |
- | ····························Console.WriteLine( | + | |
- | ································"File {0} as well as local backup {1} exist, " + | + | |
- | ································"but remote file is newer ({2}) than local backup ({3})", | + | |
- | remotePath, localPath, remoteWriteTime, localWriteTime); | + | |
- | download = true; | + | |
- | ·······················} | + | |
- | else | + | |
- | { | + | |
- | Console.WriteLine( | + | |
- | "File {0} as well as local backup {1} exist, " + | + | |
- | ·······························"but remote file is not newer ({2}) than local backup ({3})", | + | |
- | remotePath, localPath, remoteWriteTime, localWriteTime); | + | |
- | download = false; | + | |
- | } | + | |
- | } | + | |
- | + | ||
- | if (download) | + | |
- | { | + | |
- | ························// Download the file and throw on any error | + | |
- | ·······················session.GetFiles(remotePath, localPath).Check(); | + | |
- | + | ||
- | Console.WriteLine("Download to backup done."); | + | |
- | } | + | |
- | } | + | |
- | else | + | |
{ | { | ||
- | Console.WriteLine("File {0} does not exist yet", remotePath); | + | Console.WriteLine("Download of {0} succeeded", transfer.FileName); |
} | } | ||
} | } | ||
Line 131: | Line 107: | ||
==== [[vbnet]] VB.NET Example ==== | ==== [[vbnet]] VB.NET Example ==== | ||
<code vbnet> | <code vbnet> | ||
- | Imports System | ||
- | Imports System.Globalization | ||
- | Imports System.IO | ||
Imports WinSCP | Imports WinSCP | ||
Line 148: | Line 121: | ||
.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 |
' Connect | ' Connect | ||
session.Open(sessionOptions) | session.Open(sessionOptions) | ||
- | Dim stamp As String = DateTime.Now.ToString("yyyyMMdd", CultureInfo.InvariantCulture) | + | ' Download files |
- | Dim fileName As String = "export_" & stamp & ".txt" | + | Dim transferOptions As New TransferOptions |
- | Dim remotePath As String = "/home/user/sysbatch/" & fileName | + | transferOptions.TransferMode = TransferMode.Binary |
- | Dim localPath As String = "d:\backup\" & fileName | + | |
- | + | ||
- | ' Manual "remote to local" synchronization. | + | |
- | ' You can achieve the same using: | + | Dim transferResult As TransferOperationResult |
- | ' session.SynchronizeDirectories( _ | + | ···············transferResult = |
- | ' SynchronizationMode.Local, localPath, remotePath, False, False, SynchronizationCriteria.Time, _ | + | session.GetFiles("/home/user/*", "d:\download\", False, transferOptions) |
- | ' New TransferOptions With { .IncludeMask = fileName }).Check | + | |
- | If session.FileExists(remotePath) Then | + | ···············' Throw on any error |
- | ····················Dim download As Boolean | + | ···············transferResult.Check() |
- | ···················If Not File.Exists(localPath) Then | + | |
- | Console.WriteLine("File {0} exists, local backup {1} does not", remotePath, localPath) | + | ···············' Print results |
- | download = True | + | ···············For Each transfer In transferResult.Transfers |
- | Else | + | ···················Console.WriteLine("Download of {0} succeeded", transfer.FileName) |
- | Dim remoteWriteTime As DateTime = session.GetFileInfo(remotePath).LastWriteTime | + | Next |
- | Dim localWriteTime As DateTime = File.GetLastWriteTime(localPath) | + | |
- | + | ||
- | If remoteWriteTime > localWriteTime Then | + | |
- | ····························Console.WriteLine( _ | + | |
- | ································"File {0} as well as local backup {1} exist, " & _ | + | |
- | ································"but remote file is newer ({2}) than local backup ({3})", _ | + | |
- | remotePath, localPath, remoteWriteTime, localWriteTime) | + | |
- | download = True | + | |
- | ·······················Else | + | |
- | Console.WriteLine( _ | + | |
- | "File {0} as well as local backup {1} exist, " & _ | + | |
- | ·······························"but remote file is not newer ({2}) than local backup ({3})", _ | + | |
- | remotePath, localPath, remoteWriteTime, localWriteTime) | + | |
- | ···························download = False | + | |
- | ·······················End If | + | |
- | End If | + | |
- | + | ||
- | If download Then | + | |
- | ' Download the file and throw on any error | + | |
- | session.GetFiles(remotePath, localPath).Check | + | |
- | + | ||
- | ·······················Console.WriteLine("Download to backup done.") | + | |
- | End If | + | |
- | Else | + | |
- | Console.WriteLine("File {0} does not exist yet", remotePath) | + | |
- | End If | + | |
End Using | End Using | ||
Line 210: | Line 154: | ||
End Class | End Class | ||
+ | </code> | ||
+ | |||
+ | ==== [[powershell]] PowerShell Example ==== | ||
+ | Learn more about [[library_powershell|using WinSCP .NET assembly from PowerShell]]. | ||
+ | |||
+ | <code powershell> | ||
+ | try | ||
+ | { | ||
+ | # Load WinSCP .NET assembly | ||
+ | Add-Type -Path "WinSCPnet.dll" | ||
+ | |||
+ | # Setup session options | ||
+ | $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 | ||
+ | { | ||
+ | # Connect | ||
+ | $session.Open($sessionOptions) | ||
+ | |||
+ | # Download files | ||
+ | $transferOptions = New-Object WinSCP.TransferOptions | ||
+ | $transferOptions.TransferMode = [WinSCP.TransferMode]::Binary | ||
+ | |||
+ | $transferResult = | ||
+ | $session.GetFiles("/home/user/*", "d:\download\", $False, $transferOptions) | ||
+ | |||
+ | # Throw on any error | ||
+ | $transferResult.Check() | ||
+ | |||
+ | # Print results | ||
+ | foreach ($transfer in $transferResult.Transfers) | ||
+ | { | ||
+ | Write-Host "Download of $($transfer.FileName) succeeded" | ||
+ | } | ||
+ | } | ||
+ | finally | ||
+ | { | ||
+ | # Disconnect, clean up | ||
+ | $session.Dispose() | ||
+ | } | ||
+ | |||
+ | exit 0 | ||
+ | } | ||
+ | catch | ||
+ | { | ||
+ | Write-Host "Error: $($_.Exception.Message)" | ||
+ | exit 1 | ||
+ | } | ||
</code> | </code> | ||
Line 220: | Line 220: | ||
<script language="JScript"> | <script language="JScript"> | ||
- | // Setup session options | + | try |
- | var sessionOptions = WScript.CreateObject("WinSCP.SessionOptions"); | + | { |
- | sessionOptions.Protocol = Protocol_Sftp; | + | ····// Setup session options |
- | sessionOptions.HostName = "example.com"; | + | ····var sessionOptions = WScript.CreateObject("WinSCP.SessionOptions"); |
- | sessionOptions.UserName = "user"; | + | ····sessionOptions.Protocol = Protocol_Sftp; |
- | sessionOptions.Password = "mypassword"; | + | ····sessionOptions.HostName = "example.com"; |
- | sessionOptions.SshHostKey = "ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"; | + | ····sessionOptions.UserName = "user"; |
- | + | ····sessionOptions.Password = "mypassword"; | |
- | var session = WScript.CreateObject("WinSCP.Session"); | + | ····sessionOptions.SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..."; |
+ | ···· | ||
+ | ····var session = WScript.CreateObject("WinSCP.Session"); | ||
- | // Connect | + | try |
- | session.Open(sessionOptions); | + | |
- | + | ||
- | var today = new Date(); | + | |
- | var stamp = | + | |
- | today.getFullYear() + | + | |
- | (today.getMonth() + 1 < 10 ? "0" : "") + (today.getMonth() + 1) + | + | |
- | (today.getDate() < 10 ? "0" : "") + today.getDate(); | + | |
- | var fileName = "export_" + stamp + ".txt"; | + | |
- | var remotePath = "/home/user/sysbatch/" + fileName; | + | |
- | var localPath = "d:\\backup\\" + fileName; | + | |
- | + | ||
- | var fs = WScript.CreateObject("Scripting.FileSystemObject"); | + | |
- | + | ||
- | // Manual "remote to local" synchronization. | + | |
- | + | ||
- | // You can achieve the same using: | + | |
- | // var transferOptions = WScript.CreateObject("WinSCP.TransferOptions"); | + | |
- | // transferOptions.IncludeMask = fileName; | + | |
- | // session.SynchronizeDirectories( | + | |
- | // SynchronizationMode_Local, localPath, remotePath, false, false, SynchronizationCriteria_Time, | + | |
- | // transferOptions).Check(); | + | |
- | if (session.FileExists(remotePath)) | + | |
- | { | + | |
- | var download; | + | |
- | if (!fs.FileExists(localPath)) | + | |
- | { | + | |
- | WScript.Echo("File " + remotePath + " exists, local backup " + localPath + " does not"); | + | |
- | download = true; | + | |
- | } | + | |
- | else | + | |
{ | { | ||
- | var remoteWriteTime = new Date(session.GetFileInfo(remotePath).LastWriteTime); | + | // Connect |
- | var localWriteTime = fs.GetFile(localPath).DateLastModified; | + | session.Open(sessionOptions); |
- | if (remoteWriteTime > localWriteTime) | + | // Download files |
+ | var transferOptions = WScript.CreateObject("WinSCP.TransferOptions"); | ||
+ | transferOptions.TransferMode = TransferMode_Binary; | ||
+ | |||
+ | var transferResult = | ||
+ | session.GetFiles("/home/user/*", "d:\\download\\", false, transferOptions); | ||
+ | |||
+ | // Throw on any error | ||
+ | transferResult.Check(); | ||
+ | |||
+ | // Print results | ||
+ | var enumerator = new Enumerator(transferResult.Transfers); | ||
+ | for (; !enumerator.atEnd(); enumerator.moveNext()) | ||
{ | { | ||
- | WScript.Echo( | + | WScript.Echo("Download of " + enumerator.item().FileName + " succeeded"); |
- | ················"File " + remotePath + " as well as local backup " + localPath + " exist, " + | + | |
- | "but remote file is newer (" + remoteWriteTime + ") than local backup (" + localWriteTime + ")"); | + | |
- | download = true; | + | |
- | } | + | |
- | else | + | |
- | { | + | |
- | WScript.Echo( | + | |
- | "File " + remotePath + " as well as local backup " + localPath + " exist, " + | + | |
- | "but remote file is not newer (" + remoteWriteTime + ") than " + | + | |
- | "local backup local backup (" + localWriteTime + ")"); | + | |
- | download = false; | + | |
} | } | ||
} | } | ||
- | + | ····finally | |
- | ····if (download) | + | |
{ | { | ||
- | // Download the file and throw on any error | + | // Disconnect, clean up |
- | session.GetFiles(remotePath, localPath).Check(); | + | session.Dispose(); |
- | + | ||
- | WScript.Echo("Download to backup done."); | + | |
} | } | ||
} | } | ||
- | else | + | catch (e) |
{ | { | ||
- | WScript.Echo("File " + remotePath + " does not exist yet"); | + | WScript.Echo("Error: " + e.message); |
+ | ···WScript.Quit(1); | ||
} | } | ||
- | |||
- | // Disconnect, clean up | ||
- | session.Dispose(); | ||
</script> | </script> | ||
Line 321: | Line 289: | ||
.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 | ||
Line 330: | Line 298: | ||
session.Open sessionOptions | session.Open sessionOptions | ||
- | Dim today, stamp | + | ' Download files |
- | today = Date | + | Dim transferOptions |
- | stamp = Year(today) | + | Set transferOptions = WScript.CreateObject("WinSCP.TransferOptions") |
- | If Month(today) < 10 Then | + | transferOptions.TransferMode = TransferMode_Binary |
- | stamp = stamp & "0" | + | |
- | End If | + | Dim transferResult |
- | stamp = stamp & Month(today) | + | Set transferResult = session.GetFiles("/home/user/*", "d:\toupload\", False, transferOptions) |
- | if Day(today) < 10 Then | + | |
- | stamp = stamp & "0" | + | ' Throw on any error |
- | End If | + | transferResult.Check |
- | stamp = stamp & Day(today) | + | |
- | + | ' Print results | |
- | Dim fileName, remotePath, localPath | + | Dim transfer |
- | fileName = "export_" & stamp & ".txt" | + | For Each transfer In transferResult.Transfers |
- | remotePath = "/home/user/sysbatch/" & fileName | + | ···WScript.Echo "Download of " & transfer.FileName & " succeeded" |
- | localPath = "d:\backup\" & fileName | + | Next |
- | + | ||
- | Dim fs | + | |
- | Set fs = WScript.CreateObject("Scripting.FileSystemObject") | + | |
- | + | ||
- | ' Manual "remote to local" synchronization. | + | |
- | + | ||
- | ' You can achieve the same using: | + | |
- | ' Dim transferOptions | + | |
- | ' Set transferOptions = WScript.CreateObject("WinSCP.TransferOptions") | + | |
- | ' transferOptions.IncludeMask = fileName | + | |
- | ' session.SynchronizeDirectories( _ | + | |
- | ' SynchronizationMode_Local, localPath, remotePath, false, false, SynchronizationCriteria_Time, _ | + | |
- | ' transferOptions).Check | + | |
- | + | ||
- | Dim download, remoteWriteTime, localWriteTime | + | |
- | + | ||
- | If session.FileExists(remotePath) Then | + | |
- | If Not fs.FileExists(localPath) Then | + | |
- | WScript.Echo "File " & remotePath & " exists, local backup " & localPath & " does not" | + | |
- | download = True | + | |
- | Else | + | |
- | remoteWriteTime = CDate(session.GetFileInfo(remotePath).LastWriteTime) | + | |
- | localWriteTime = fs.GetFile(localPath).DateLastModified | + | |
- | + | ||
- | If remoteWriteTime > localWriteTime Then | + | |
- | WScript.Echo _ | + | |
- | ················"File " & remotePath & " as well as local backup " & localPath & " exist, " & _ | + | |
- | ················"but remote file is newer (" & remoteWriteTime & ") than local backup (" & localWriteTime & ")" | + | |
- | download = True | + | |
- | ········Else | + | |
- | WScript.Echo _ | + | |
- | "File " & remotePath & " as well as local backup " & localPath & " exist, " & _ | + | |
- | ················"but remote file is not newer (" & remoteWriteTime & ") than " & _ | + | |
- | "local backup local backup (" & localWriteTime & ")" | + | |
- | ············download = False | + | |
- | ········End If | + | |
- | ····End If | + | |
- | + | ||
- | If download Then | + | |
- | ' Download the file and throw on any error | + | |
- | session.GetFiles(remotePath, localPath).Check() | + | |
- | + | ||
- | ·······WScript.Echo "Download to backup done." | + | |
- | End If | + | |
- | Else | + | |
- | WScript.Echo "File " & remotePath & " does not exist yet" | + | |
- | End If | + | |
' Disconnect, clean up | ' Disconnect, clean up | ||
Line 400: | Line 321: | ||
</job> | </job> | ||
</code> | </code> | ||
+ | |||
+ | ==== Real-Life Examples ==== | ||
+ | |||
+ | * [[script_download_timestamped_filename|*]]; | ||
+ | * [[script_download_most_recent_file|*]]; | ||
+ | * [[library_example_recursive_search_text|*]]; | ||
+ | * [[library_example_recursive_download_custom_error_handling|*]]; | ||
+ | * [[library_example_check_existence_timestamp|*]]; | ||
+ | * [[extension_archive_and_download|*]]. | ||
+ | |||
+ | |||