library_session_getfiles » Revisions »

Differences

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

library_session_getfiles 2011-12-29 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 =====
-<code csharp> +<code csharp *> 
-public OperationResult<TransferArgs> GetFiles(+public TransferOperationResult GetFiles(
    string remotePath,     string remotePath,
    string localPath,     string localPath,
Line 12: 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()''. |
==== Return Value ==== ==== Return Value ====
-''[[library_operationresult|OperationResult<T>]]'' holding collection of ''[[library_transferargs|TransferArgs]]''. 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. |
-| SessionException | Error communicating with ''[[executables#winscp.com|winscp.com]]''. |+| [[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 ''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 ===== 
 + 
 +==== [[csharp]] C# Example ==== 
 +<code csharp> 
 +using System; 
 +using WinSCP; 
 + 
 +class Example 
 +{ 
 +    public static int Main() 
 +    { 
 +        try 
 +        { 
 +            // Setup session options 
 +            SessionOptions sessionOptions = new SessionOptions 
 +            { 
 +                Protocol = Protocol.Sftp, 
 +                HostName = "example.com", 
 +                UserName = "user", 
 +                Password = "mypassword", 
 +                SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..." 
 +            }; 
 + 
 +            using (Session session = new Session()) 
 +            { 
 +                // Connect 
 +                session.Open(sessionOptions); 
 + 
 +                // Download files 
 +                TransferOptions transferOptions = new TransferOptions(); 
 +                transferOptions.TransferMode = TransferMode.Binary; 
 +  
 +                TransferOperationResult transferResult; 
 +                transferResult = 
 +                    session.GetFiles("/home/user/*", @"d:\download\", false, transferOptions); 
 +  
 +                // Throw on any error 
 +                transferResult.Check(); 
 +  
 +                // Print results 
 +                foreach (TransferEventArgs transfer in transferResult.Transfers) 
 +                { 
 +                    Console.WriteLine("Download of {0} succeeded", transfer.FileName); 
 +                } 
 +            } 
 + 
 +            return 0; 
 +        } 
 +        catch (Exception e) 
 +        { 
 +            Console.WriteLine("Error: {0}", e); 
 +            return 1; 
 +        } 
 +    } 
 +} 
 +</code> 
 + 
 +==== [[vbnet]] VB.NET Example ==== 
 +<code vbnet> 
 +Imports WinSCP 
 + 
 +Friend Class Example 
 + 
 +    Public Shared Function Main() As Integer 
 + 
 +        Try  
 +            ' Setup session options 
 +            Dim sessionOptions As New SessionOptions 
 +            With sessionOptions 
 +                .Protocol = Protocol.Sftp 
 +                .HostName = "example.com" 
 +                .UserName = "user" 
 +                .Password = "mypassword" 
 +                .SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..." 
 +            End With 
 + 
 +            Using session As New Session 
 +                ' Connect 
 +                session.Open(sessionOptions) 
 + 
 +                ' Download files 
 +                Dim transferOptions As New TransferOptions 
 +                transferOptions.TransferMode = TransferMode.Binary 
 +  
 +                Dim transferResult As TransferOperationResult 
 +                transferResult = 
 +                    session.GetFiles("/home/user/*", "d:\download\", False, transferOptions) 
 +  
 +                ' Throw on any error 
 +                transferResult.Check() 
 +  
 +                ' Print results 
 +                For Each transfer In transferResult.Transfers 
 +                    Console.WriteLine("Download of {0} succeeded", transfer.FileName) 
 +                Next 
 +            End Using 
 + 
 +            Return 0 
 +        Catch e As Exception 
 +            Console.WriteLine("Error: {0}", e) 
 +            Return 1 
 +        End Try 
 + 
 +    End Function 
 + 
 +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> 
 + 
 +==== [[jscript]] JScript (WSH) Example ==== 
 +In this example the JScript script is embedded into WSF file, to allow [[library_com_wsh#enums|access to enumeration values]]. 
 + 
 +<code javascript> 
 +<job>                                                               
 +<reference object="WinSCP.Session"/> 
 +<script language="JScript"> 
 +  
 +try 
 +{ 
 +    // Setup session options 
 +    var sessionOptions = WScript.CreateObject("WinSCP.SessionOptions"); 
 +    sessionOptions.Protocol = Protocol_Sftp; 
 +    sessionOptions.HostName = "example.com"; 
 +    sessionOptions.UserName = "user"; 
 +    sessionOptions.Password = "mypassword"; 
 +    sessionOptions.SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..."; 
 +     
 +    var session = WScript.CreateObject("WinSCP.Session"); 
 + 
 +    try 
 +    { 
 +        // Connect 
 +        session.Open(sessionOptions); 
 + 
 +        // 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("Download of " + enumerator.item().FileName + " succeeded"); 
 +        } 
 +    } 
 +    finally 
 +    { 
 +        // Disconnect, clean up 
 +        session.Dispose(); 
 +    } 
 +} 
 +catch (e) 
 +{ 
 +    WScript.Echo("Error: " + e.message); 
 +    WScript.Quit(1); 
 +} 
 + 
 +</script> 
 +</job> 
 +</code> 
 + 
 + 
 +==== [[vbscript]] VBScript (WSH) Example ==== 
 +In this example the VBScript script is embedded into WSF file, to allow [[library_com_wsh#enums|access to enumeration values]]. 
 + 
 +<code vb> 
 +<job>                                                               
 +<reference object="WinSCP.Session"/> 
 +<script language="VBScript"> 
 + 
 +Option Explicit 
 +  
 +' Setup session options 
 +Dim sessionOptions 
 +Set sessionOptions = WScript.CreateObject("WinSCP.SessionOptions") 
 +With sessionOptions 
 +    .Protocol = Protocol_Sftp 
 +    .HostName = "example.com" 
 +    .UserName = "user" 
 +    .Password = "mypassword" 
 +    .SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..." 
 +End With 
 + 
 +Dim session  
 +Set session = WScript.CreateObject("WinSCP.Session") 
 + 
 +' Connect 
 +session.Open sessionOptions 
 + 
 +' Download files 
 +Dim transferOptions 
 +Set transferOptions = WScript.CreateObject("WinSCP.TransferOptions") 
 +transferOptions.TransferMode = TransferMode_Binary 
 +  
 +Dim transferResult 
 +Set transferResult = session.GetFiles("/home/user/*", "d:\toupload\", False, transferOptions) 
 +  
 +' Throw on any error 
 +transferResult.Check 
 +  
 +' Print results 
 +Dim transfer 
 +For Each transfer In transferResult.Transfers 
 +    WScript.Echo "Download of " & transfer.FileName & " succeeded" 
 +Next 
 + 
 +' Disconnect, clean up 
 +session.Dispose 
 + 
 +</script> 
 +</job> 
 +</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|*]]. 
-~~NOTOC~~ 

Last modified: by martin

Documentation

Support

Associations

Follow Us