Session.GetFiles Method

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

Syntax
- Parameters
- Return Value
Exceptions
Remarks
Examples

Syntax

public TransferOperationResult GetFiles(
    string remotePath,
    string localPath,
    bool remove = false,
    TransferOptions options = null
)

VB.NET

Public Function GetFiles( _
    ByVal remotePath As String, _
    ByVal localPath As String, _
    ByVal Optional remove As Boolean = False, _
    ByVal Optional options As TransferOptions = Null _
) 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 transfer. Defaults to `false`.
TransferOptions options	Transfer options. Defaults to `null`, what is equivalent to `new TransferOptions()`.

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.
TimeoutException	Timeout waiting for `winscp.com` to respond.

Remarks

Event Session.FileTransferred is raised for every downloaded file.

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 System.Globalization;
using System.IO;
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 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
            };
 
            using (Session session = new Session())
            {
                // Connect
                session.Open(sessionOptions);
 
                string stamp = DateTime.Now.ToString("yyyyMMdd", CultureInfo.InvariantCulture);
                string fileName = "export_" + stamp + ".txt";
                string remotePath = "/home/user/sysbatch/" + fileName;
                string localPath = "d:\\backup\\" + fileName;
 
                // Manual "remote to local" synchronization.
 
                // You can achieve the same using:
                // session.SynchronizeDirectories(
                //     SynchronizationMode.Local, localPath, remotePath, false, false, SynchronizationCriteria.Time, 
                //     new TransferOptions { FileMask = fileName }).Check();
                if (session.FileExists(remotePath))
                {
                    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 > 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, " +
                                "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);
                }
            }
 
            return 0;
        }
        catch (Exception e)
        {
            Console.WriteLine("Error: {0}", e);
            return 1;
        }
    }
}

VB.NET Example

Imports System
Imports System.Globalization
Imports System.IO
Imports WinSCP
 
Friend Class Example
 
    Public Shared Function Main() As Integer
 
        Try 
            ' Setup session options
            Dim mySessionOptions As New SessionOptions
            With mySessionOptions
                .Protocol = Protocol.Sftp
                .HostName = "example.com"
                .UserName = "user"
                .Password = "mypassword"
                .SshHostKeyFingerprint = "ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
            End With
 
            Using mySession As Session = New Session
                ' Connect
                mySession.Open(mySessionOptions)
 
                Dim stamp As String = DateTime.Now.ToString("yyyyMMdd", CultureInfo.InvariantCulture)
                Dim fileName As String = "export_" & stamp & ".txt"
                Dim remotePath As String = "/home/user/sysbatch/" & fileName
                Dim localPath As String = "d:\backup\" & fileName
 
                ' Manual "remote to local" synchronization.
 
                ' You can achieve the same using:
                ' mySession.SynchronizeDirectories( _
                '     SynchronizationMode.Local, localPath, remotePath, False, False, SynchronizationCriteria.Time, _
                '     New TransferOptions With { .FileMask = fileName }).Check
                If mySession.FileExists(remotePath) Then
                    Dim download As Boolean
                    If Not File.Exists(localPath) Then
                        Console.WriteLine("File {0} exists, local backup {1} does not", remotePath, localPath)
                        download = True
                    Else
                        Dim remoteWriteTime As DateTime = mySession.GetFileInfo(remotePath).LastWriteTime
                        Dim localWriteTime As DateTime = File.GetLastWriteTime(localPath)
 
                        If remoteWriteTime > localWriteTime Then
                            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, " & _
                                "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
                        mySession.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
 
            Return 0
        Catch e As Exception
            Console.WriteLine("Error: {0}", e)
            Return 1
        End Try
 
    End Function
 
End Class

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
    $sessionOptions.Protocol = [WinSCP.Protocol]::Sftp
    $sessionOptions.HostName = "example.com"
    $sessionOptions.UserName = "user"
    $sessionOptions.Password = "mypassword"
    $sessionOptions.SshHostKeyFingerprint = "ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
 
    $session = New-Object WinSCP.Session
 
    try
    {
        # Connect
        $session.Open($sessionOptions)
 
        $stamp = Get-Date -f "yyyyMMdd"
        $fileName = "export_$stamp.txt"
        $remotePath = "/home/user/sysbatch/$fileName"
        $localPath = "d:\backup\$fileName"
 
        # Manual "remote to local" synchronization.
 
        # You can achieve the same using:
        # $transferOptions = New-Object WinSCP.TransferOptions
        # $transferOptions.FileMask = $fileName
        # $session.SynchronizeDirectories(
        #     [WinSCP.SynchronizationMode]::Local, $localPath, $remotePath,
        #     $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 (
                        ("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)
        }
    }
    finally
    {
        # Disconnect, clean up
        $session.Dispose()
    }
 
    exit 0
}
catch [Exception]
{
    Write-Host $_.Exception.Message
    exit 1
}

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 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx";
     
    var session = WScript.CreateObject("WinSCP.Session");
 
    try
    {
        // Connect
        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.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");
        }
    }
    finally
    {
        // Disconnect, clean up
        session.Dispose();
    }
}
catch (e)
{
    WScript.Echo("Error: " + e.message);
    WScript.Quit(1);
}
 
</script>
</job>

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 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
End With
 
Dim session 
Set session = WScript.CreateObject("WinSCP.Session")
 
' Connect
session.Open sessionOptions
 
Dim today, stamp
today = Date
stamp = Year(today)
If Month(today) < 10 Then
    stamp = stamp & "0"
End If
stamp = stamp & Month(today)
if Day(today) < 10 Then
    stamp = stamp & "0"
End If
stamp = stamp & Day(today)
 
Dim fileName, remotePath, localPath
fileName = "export_" & stamp & ".txt"
remotePath = "/home/user/sysbatch/" & fileName
localPath = "d:\backup\" & fileName
 
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 " & 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
        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
 
' Disconnect, clean up
session.Dispose
 
</script>
</job>