library_session_getfiles » Revisions »

Differences

This shows you the differences between the selected revisions of the page.

library_session_getfiles 2012-02-22 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.
-&future_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 
-            sessionOptions.Protocol = Protocol.Sftp; +            { 
-           sessionOptions.HostName = "example.com"; +················Protocol = Protocol.Sftp, 
-           sessionOptions.UserName = "user"; + ···············HostName = "example.com", 
-           sessionOptions.Password = "mypassword"; + ···············UserName = "user", 
-           sessionOptions.SshHostKey = "ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx";+ ···············Password = "mypassword", 
 + ···············SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..." 
 +            };
            using (Session session = new Session())             using (Session session = new Session())
Line 61: 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(&quot;/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 &gt; 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, " + +
- ·······························&quot;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 130: 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 147: 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(&quot;yyyyMMdd";, CultureInfo.InvariantCulture) +                &#039; Download files 
-                Dim fileName As String = "export_" & stamp & ".txt" +                Dim transferOptions As New TransferOptions 
-                Dim remotePath As String = &quot;/home/user/sysbatch/" & fileName +                transferOptions.TransferMode = TransferMode.Binary
-                Dim localPath As String = &quot;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(&quot;/home/user/*", "d:\download\", False, transferOptions) 
-                '    New TransferOptions With { .IncludeMask = fileName }).Check +  
-                If session.FileExists(remotePath) Then + ···············&#039; 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 &gt; localWriteTime Then +
-····························Console.WriteLine( _ +
-································"File {0} as well as local backup {1} exist, " &amp; _ +
-································&quot;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, " & _ +
- ·······························&quot;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 209: 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 219: 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"); +        // Connect 
-        download = true; +        session.Open(sessionOptions);
-    } +
-    else +
-    { +
-        var remoteWriteTime = new Date(session.GetFileInfo(remotePath).LastWriteTime); +
-        var localWriteTime = fs.GetFile(localPath).DateLastModified;+
-        if (remoteWriteTime > localWriteTime) +        // Download files 
-        { +        var transferOptions = WScript.CreateObject("WinSCP.TransferOptions"); 
- ···········WScript.Echo( +       transferOptions.TransferMode = TransferMode_Binary; 
-················"File " + remotePath + "; as well as local backup " + localPath + " exist, " + +  
-················"but remote file is newer (&quot; + remoteWriteTime + &quot;) than local backup (&quot; + localWriteTime + &quot;)"); +       var transferResult = 
- ···········download = true; +           session.GetFiles("/home/user/*", "d:\\download\\", false, transferOptions); 
- ·······} +          
- ·······else+ ·······// 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 + &quot; exist, " + +
-                "but remote file is not newer (" + remoteWriteTime + ") than &quot; + +
- ···············"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 + &quot; does not exist yet&quot;);+    WScript.Echo("Error: " + e.message); 
 + ···WScript.Quit(1);
} }
Line 306: Line 278:
<reference object="WinSCP.Session"/> <reference object="WinSCP.Session"/>
<script language="VBScript"> <script language="VBScript">
 +
 +Option Explicit
' Setup session options ' Setup session options
 +Dim sessionOptions
Set sessionOptions = WScript.CreateObject("WinSCP.SessionOptions") Set sessionOptions = WScript.CreateObject("WinSCP.SessionOptions")
-sessionOptions.Protocol = Protocol_Sftp +With sessionOptions 
-sessionOptions.HostName = "example.com" +····.Protocol = Protocol_Sftp 
-sessionOptions.UserName = "user" +····.HostName = "example.com" 
-sessionOptions.Password = "mypassword" +····.UserName = "user" 
-sessionOptions.SshHostKey = "ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" +····.Password = "mypassword" 
- +····.SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx...&quot; 
 +End With 
 + 
 +Dim session
Set session = WScript.CreateObject("WinSCP.Session") Set session = WScript.CreateObject("WinSCP.Session")
- 
-session.DebugLogPath = "debug.log" 
-session.DisableVersionCheck = True 
' Connect ' Connect
session.Open sessionOptions session.Open sessionOptions
-today = Date +' Download files 
-stamp = Year(today) +Dim transferOptions 
-If Month(today) &lt; 10 Then +Set transferOptions = WScript.CreateObject(&quot;WinSCP.TransferOptions&quot;) 
- ···stamp = stamp &amp;·"0" +transferOptions.TransferMode = TransferMode_Binary 
-End If +  
-stamp = stamp &amp; Month(today) +Dim transferResult 
-if Day(today) &lt; 10 Then +Set transferResult = session.GetFiles(&quot;/home/user/*", "d:\toupload\&quot;, False, transferOptions) 
- ···stamp = stamp &amp; "0" +· 
-End If +' Throw on any error 
-stamp = stamp & Day(today)+transferResult.Check 
 +  
 +&#039; Print results 
 +Dim transfer 
 +For Each transfer In transferResult.Transfers 
 +    WScript.Echo "Download of " &amp; transfer.FileName & &quot; succeeded" 
 +Next
-fileName = &quot;export_"; &amp; stamp &amp; ".txt" +&#039; Disconnect, clean up 
-remotePath = "/home/user/sysbatch/" & fileName +session.Dispose
-localPath = "d:\backup\" & fileName+
-Set fs = WScript.CreateObject(&quot;Scripting.FileSystemObject&quot;) +&lt;/script&gt; 
-         +&lt;/job&gt; 
-&#039; Manual &quot;remote to local&quot; synchronization.+&lt;/code&gt;
-&#039; You can achieve the same using: +==== Real-Life Examples ====
-' Set transferOptions = WScript.CreateObject("WinSCP.TransferOptions") +
-' transferOptions.IncludeMask = fileName +
-' session.SynchronizeDirectories( _ +
-'    SynchronizationMode_Local, localPath, remotePath, false, false, SynchronizationCriteria_Time, _ +
-'    transferOptions).Check +
-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 &gt; localWriteTime Then +··* [[script_download_timestamped_filename|*]]; 
-············WScript.Echo _ +  * [[script_download_most_recent_file|*]]; 
-                ";File " &amp; remotePath &amp; &quot; as well as local backup &quot; &; localPath & " exist, " & _ +  * [[library_example_recursive_search_text|*]]; 
-               "but remote file is newer (" &amp; remoteWriteTime &amp; ") than local backup (" & localWriteTime & ")&quot; +  * [[library_example_recursive_download_custom_error_handling|*]]; 
-           download = True +  * [[library_example_check_existence_timestamp|*]]; 
- ·······Else +  * [[extension_archive_and_download|*]].
-············WScript.Echo _ +
-                ";File " & remotePath & " as well as local backup " & localPath & " exist, " & _ +
-               "but remote file is not newer (" &amp; remoteWriteTime &amp; &quot;) than "; & _ +
-               "local backup local backup (" &amp; localWriteTime &amp; &quot;)" +
-            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 
- 
-</script> 
-</job> 
-</code> 

Last modified: by martin

Documentation

Support

Associations

Follow Us