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 174: Line 181:
        $session.Open($sessionOptions)         $session.Open($sessionOptions)
-        $stamp = Get-Date -f "yyyyMMdd" +        # Download files 
-        $fileName = "export_$stamp.txt" +        $transferOptions = New-Object WinSCP.TransferOptions 
-        $remotePath = "/home/user/sysbatch/$fileName" +        $transferOptions.TransferMode = [WinSCP.TransferMode]::Binary 
-        $localPath = "d:\backup\$fileName" +  
- +        $transferResult
-········# Manual "remote to local" synchronization. +            $session.GetFiles("/home/user/*", "d:\download\", $False, $transferOptions
- +  
-        # You can achieve the same using: + ·······# Throw on any error 
-        # $transferOptions = New-Object WinSCP.TransferOptions + ·······$transferResult.Check() 
-        # $transferOptions.FileMask = $fileName +  
-        # $session.SynchronizeDirectories( + ·······# Print results 
-        #    [WinSCP.SynchronizationMode]::Local, $localPath, $remotePath, + ·······foreach ($transfer in $transferResult.Transfers)
-        #    $False, $False, [WinSCP.SynchronizationCriteria]::Time,  +
-        #    $transferOptions).Check() +
-        if ($session.FileExists($remotePath)) +
-        { +
-            if (!(Test-Path $localPath)) +
-            { +
-                Write-Host ( +
-                    "File {0} exists, local backup {1} does not" -f +
-                    $remotePath, $localPath) +
-                $download = $True +
-            +
-            else +
-            { +
-                $remoteWriteTime = $session.GetFileInfo($remotePath).LastWriteTime +
-                $localWriteTime = (Get-Item $localPath).LastWriteTime +
- +
-                if ($remoteWriteTime -gt $localWriteTime) +
-                { +
-                    Write-Host ( +
-························("File {0} as well as local backup {1} exist, " + +
- ························"but remote file is newer ({2}) than local backup ({3})") -f +
-                        $remotePath, $localPath, $remoteWriteTime, $localWriteTime+
-                   $download = $True +
- ···············+
-               else +
-               { +
-                   Write-Host ( +
- ·······················(&quot;File {0} as well as local backup {1} exist, " + +
-                        "but remote file is not newer ({2}) than local backup ({3})") -f +
-                       $remotePath, $localPath, $remoteWriteTime, $localWriteTime) +
- ···················$download = $False +
- ···············+
-            } +
- +
-            if ($download) +
-           { +
-               # Download the file and throw on any error +
-················$session.GetFiles($remotePath, $localPath).Check() +
- +
-                Write-Host "Download to backup done." +
-            } +
-        } +
-        else+
        {         {
-            Write-Host ("File {0} does not exist yet" -f $remotePath)+            Write-Host "Download of $($transfer.FileName) succeeded"
        }         }
    }     }
Line 241: Line 205:
    exit 0     exit 0
} }
-catch [Exception]+catch
{ {
-    Write-Host $_.Exception.Message+    Write-Host "Error: $($_.Exception.Message)"
    exit 1     exit 1
} }
Line 264: 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 273: Line 237:
        session.Open(sessionOptions);         session.Open(sessionOptions);
-        var today = new Date();  +        // Download files 
-        var stamp = +        var transferOptions = WScript.CreateObject("WinSCP.TransferOptions")
-           today.getFullYear() + + ·······transferOptions.TransferMode = TransferMode_Binary; 
-            (today.getMonth() + 1 < 10 ? "0&quot; : "";) + (today.getMonth() + 1) + +  
- ···········(today.getDate() < 10 ? ";0" : "") + today.getDate(); +        var transferResult = 
-        var fileName = &quot;export_" + stamp + &quot;.txt&quot;; + ···········session.GetFiles("/home/user/*", "d:\\download\\", false, transferOptions); 
-        var remotePath = "/home/user/sysbatch/" + fileName+ ········ 
-        var localPath = "d:\\backup\\" + fileName+        // Throw on any error 
- +        transferResult.Check(); 
- ·······var fs = WScript.CreateObject("Scripting.FileSystemObject"); + ········ 
- ··············· +        // Print results 
-        // Manual "remote to local" synchronization. +        var enumerator = new Enumerator(transferResult.Transfers); 
- + ·······for (; !enumerator.atEnd(); enumerator.moveNext())
-        // You can achieve the same using: +
-        // var transferOptions = WScript.CreateObject("WinSCP.TransferOptions"); +
-       // transferOptions.FileMask = 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); +
- ···············var localWriteTime = fs.GetFile(localPath).DateLastModified; +
- +
- ···············if (remoteWriteTime > localWriteTime) +
-                { +
-                    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; +
-                } +
-            } +
- +
-            if (download) +
-            { +
-                // Download the file and throw on any error +
-                session.GetFiles(remotePath, localPath).Check(); +
- +
-                WScript.Echo("Download to backup done."); +
-            } +
-        } +
-        else+
        {         {
-            WScript.Echo("File " + remotePath + " does not exist yet");+            WScript.Echo("Download of " + enumerator.item().FileName + " succeeded");
        }         }
    }     }
Line 370: 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 379: 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 " &amp; 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.FileMask = 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 &quot; &amp; remotePath &amp; " as well as local backup " & localPath & " exist, " &amp; _ +
-················&quot;but remote file is newer (" &amp; remoteWriteTime &amp; ") than local backup (" & localWriteTime & ")" +
-           download = True +
-········Else +
-           WScript.Echo +
-               "File " & remotePath & " as well as local backup " & localPath & " exist, " & _ +
-················&quot;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 &quot;File &quot; & remotePath & " does not exist yet+
-End If+
' Disconnect, clean up ' Disconnect, clean up
Line 452: 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|*]]; 
 +  * [[extension_archive_and_download|*]].

Last modified: by martin