Session.GetFiles Method

Downloads one or more files from remote directory to local directory.

You can have WinSCP 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: Session.GetFilesToDirectory and Session.GetFileToDirectory.

Advertisement

Syntax

C#
public TransferOperationResult GetFiles(
    string remotePath,
    string localPath,
    bool remove = false,
    TransferOptions options = null
)
VB.NET
Public Function GetFiles(
    remotePath As String,
    localPath As String,
    Optional remove As Boolean = False,
    Optional options As TransferOptions = Nothing
) As TransferOperationResult

Parameters

Name Description
string remotePath Full path to remote directory followed by slash and 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 or omitted (path ends with backslash).
bool remove When set to true, deletes source remote file(s) after a successful transfer. Defaults to false.
TransferOptions options Transfer options. Defaults to null, what is equivalent to new TransferOptions().

Advertisement

Return Value

TransferOperationResult. See also Capturing results of operations.

Exceptions

Exception Condition
InvalidOperationException Session is not opened.
ArgumentException
ArgumentOutOfRangeException
Invalid combination of values of TransferOptions properties.
SessionLocalException Error communicating with winscp.com.
See the exception documentation for details.
SessionRemoteException Session has failed.
Downloading of files has failed.
See the exception documentation for details.
TimeoutException Timeout waiting for winscp.com to respond.

Remarks

Event Session.FileTransferred is raised for every downloaded file. Also raises Session.FileTransferProgress throughout the transfer.

The download aborts on the first error. See how to implement recursive directory tree download with custom error handling.

Examples

C# Example

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;
        }
    }
}

Advertisement

VB.NET Example

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

Advertisement

PowerShell Example

Learn more about using WinSCP .NET assembly from 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
}

Advertisement

JScript (WSH) Example

In this example the JScript script is embedded into WSF file, to allow access to enumeration values.

<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>

Advertisement

VBScript (WSH) Example

In this example the VBScript script is embedded into WSF file, to allow access to enumeration values.

<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>

Advertisement

Real-Life Examples

Last modified: by martin