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|*]].

Last modified: by martin