Differences
This shows you the differences between the selected revisions of the page.
| library_session_getfiles 2016-03-07 | library_session_getfiles 2022-08-12 (current) | ||
| Line 1: | Line 1: | ||
| ====== Session.GetFiles Method ====== | ====== Session.GetFiles Method ====== | ||
| [[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. | ||
| + | |||
| + | 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 ===== | ||
| Line 13: | Line 17: | ||
| <code vbnet *> | <code vbnet *> | ||
| - | Public Function GetFiles( _ | + | Public Function GetFiles( |
| - | ByVal remotePath As String, _ | + | remotePath As String, |
| - | ByVal localPath As String, _ | + | localPath As String, |
| - | ByVal Optional remove As Boolean = False, _ | + | Optional remove As Boolean = False, |
| - | ByVal Optional options As TransferOptions = Null _ | + | Optional options As TransferOptions = Nothing |
| ) As TransferOperationResult | ) As TransferOperationResult | ||
| </code> | </code> | ||
| - | ==== Parameters ==== | + | ==== [[parameters]] Parameters ==== |
| ^ Name ^ Description ^ | ^ Name ^ Description ^ | ||
| - | | 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 ==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 omitted (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 31: | 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. | | ||
| Line 40: | Line 44: | ||
| ===== 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]]. | 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]] Examples ===== | ||
| + | |||
| ==== [[csharp]] C# Example ==== | ==== [[csharp]] C# Example ==== | ||
| <code csharp> | <code csharp> | ||
| Line 63: | Line 68: | ||
| UserName = "user", | UserName = "user", | ||
| Password = "mypassword", | Password = "mypassword", | ||
| - | SshHostKeyFingerprint = "ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" | + | SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..." |
| }; | }; | ||
| Line 76: | Line 81: | ||
| TransferOperationResult transferResult; | TransferOperationResult transferResult; | ||
| - | transferResult = session.GetFiles("/home/user/*", "d:\\download\\", false, transferOptions); | + | transferResult = |
| + | ···················session.GetFiles("/home/user/*", @"d:\download\", false, transferOptions); | ||
| // Throw on any error | // Throw on any error | ||
| Line 115: | Line 121: | ||
| .UserName = "user" | .UserName = "user" | ||
| .Password = "mypassword" | .Password = "mypassword" | ||
| - | .SshHostKeyFingerprint = "ssh-rsa 2048 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 127: | Line 133: | ||
| Dim transferResult As TransferOperationResult | Dim transferResult As TransferOperationResult | ||
| - | transferResult = session.GetFiles("/home/user/*", "d:\download\*", False, transferOptions) | + | transferResult = |
| + | ···················session.GetFiles("/home/user/*", "d:\download\", False, transferOptions) | ||
| ' Throw on any error | ' Throw on any error | ||
| Line 164: | Line 171: | ||
| UserName = "user" | UserName = "user" | ||
| Password = "mypassword" | Password = "mypassword" | ||
| - | SshHostKeyFingerprint = "ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" | + | SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..." |
| } | } | ||
| Line 178: | Line 185: | ||
| $transferOptions.TransferMode = [WinSCP.TransferMode]::Binary | $transferOptions.TransferMode = [WinSCP.TransferMode]::Binary | ||
| - | $transferResult = $session.GetFiles("/home/user/*", "d:\download\", $False, $transferOptions) | + | $transferResult = |
| + | ···········$session.GetFiles("/home/user/*", "d:\download\", $False, $transferOptions) | ||
| # Throw on any error | # Throw on any error | ||
| Line 186: | Line 194: | ||
| foreach ($transfer in $transferResult.Transfers) | foreach ($transfer in $transferResult.Transfers) | ||
| { | { | ||
| - | Write-Host ("Download of {0} succeeded" -f $transfer.FileName) | + | Write-Host "Download of $($transfer.FileName) succeeded" |
| } | } | ||
| } | } | ||
| Line 197: | Line 205: | ||
| exit 0 | exit 0 | ||
| } | } | ||
| - | catch [Exception] | + | catch |
| { | { | ||
| - | Write-Host $_.Exception.Message | + | Write-Host "Error: $($_.Exception.Message)" |
| exit 1 | exit 1 | ||
| } | } | ||
| Line 220: | Line 228: | ||
| sessionOptions.UserName = "user"; | sessionOptions.UserName = "user"; | ||
| sessionOptions.Password = "mypassword"; | sessionOptions.Password = "mypassword"; | ||
| - | sessionOptions.SshHostKeyFingerprint = "ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"; | + | sessionOptions.SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..."; |
| var session = WScript.CreateObject("WinSCP.Session"); | var session = WScript.CreateObject("WinSCP.Session"); | ||
| Line 233: | Line 241: | ||
| transferOptions.TransferMode = TransferMode_Binary; | transferOptions.TransferMode = TransferMode_Binary; | ||
| - | var transferResult = session.GetFiles("/home/user/*", "d:\\download\\", false, transferOptions); | + | var transferResult = |
| + | ···········session.GetFiles("/home/user/*", "d:\\download\\", false, transferOptions); | ||
| // Throw on any error | // Throw on any error | ||
| Line 239: | Line 248: | ||
| // Print results | // Print results | ||
| - | for (var enumerator = new Enumerator(transferResult.Transfers); !enumerator.atEnd(); enumerator.moveNext()) | + | var enumerator = new Enumerator(transferResult.Transfers); |
| + | for (; !enumerator.atEnd(); enumerator.moveNext()) | ||
| { | { | ||
| WScript.Echo("Download of " + enumerator.item().FileName + " succeeded"); | WScript.Echo("Download of " + enumerator.item().FileName + " succeeded"); | ||
| Line 279: | Line 289: | ||
| .UserName = "user" | .UserName = "user" | ||
| .Password = "mypassword" | .Password = "mypassword" | ||
| - | .SshHostKeyFingerprint = "ssh-rsa 2048 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 314: | Line 324: | ||
| ==== Real-Life Examples ==== | ==== Real-Life Examples ==== | ||
| - | * [[script_download_timestamped_filename|Downloading file to timestamped-filename]]; | + | * [[script_download_timestamped_filename|*]]; |
| - | * [[script_download_most_recent_file|Downloading the most recent file]]; | + | * [[script_download_most_recent_file|*]]; |
| - | * [[library_example_recursive_search_text|Search recursively for text in remote directory / Grep files over SFTP/FTP protocol]]; | + | * [[library_example_recursive_search_text|*]]; |
| - | * [[library_example_recursive_download_custom_error_handling|Recursively download directory tree with custom error handling]]; | + | * [[library_example_recursive_download_custom_error_handling|*]]; |
| - | * [[library_example_check_existence_timestamp|Checking file existence and timestamp]]. | + | * [[library_example_check_existence_timestamp|*]]; |
| + | * [[extension_archive_and_download|*]]. | ||