Differences

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

library_session_getfiles 2012-02-18		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("/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 > 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);	+	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("yyyyMMdd", CultureInfo.InvariantCulture)	+	' Download files
-	Dim fileName As String = "export_" & stamp & ".txt"	+	Dim transferOptions As New TransferOptions
-	Dim remotePath As String = "/home/user/sysbatch/" & fileName	+	transferOptions.TransferMode = TransferMode.Binary
-	Dim localPath As String = "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("/home/user/*", "d:\download\", False, transferOptions)
-	' New TransferOptions With { .IncludeMask = fileName }).Check	+
-	If session.FileExists(remotePath) Then	+	···············' 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 > 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	+
-	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;	+
-	sessionOptions.HostName = "example.com";	+
-	sessionOptions.UserName = "user";	+
-	sessionOptions.Password = "mypassword";	+
-	sessionOptions.SshHostKey = "ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx";	+
-		+
-	var session = WScript.CreateObject("WinSCP.Session");	+
-		+
-	// 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.IncludeMask = fileName;	+
-	// session.SynchronizeDirectories(	+
-	// SynchronizationMode_Local, localPath, remotePath, false, false, SynchronizationCriteria_Time,	+
-	// transferOptions).Check();	+
-	if (session.FileExists(remotePath))	+
	{		{
-	var download;	+	// Setup session options
-	if (!fs.FileExists(localPath))	+	var sessionOptions = WScript.CreateObject("WinSCP.SessionOptions");
-	{	+	sessionOptions.Protocol = Protocol_Sftp;
-	·······WScript.Echo("File " + remotePath + " exists, local backup " + localPath + " does not");	+	···sessionOptions.HostName = "example.com";
-	·······download = true;	+	sessionOptions.UserName = "user";
-	····}	+	···sessionOptions.Password = "mypassword";
-	else	+	sessionOptions.SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx...";
		+	····
		+	var session = WScript.CreateObject(";WinSCP.Session");
		+
		+	try
	{		{
-	var remoteWriteTime = new Date(session.GetFileInfo(remotePath).LastWriteTime);	+	// Connect
-	var localWriteTime = fs.GetFile(localPath).DateLastModified;	+	session.Open(sessionOptions);

-	if (remoteWriteTime > localWriteTime)	+	// 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(	+	WScript.Echo("Download of " + enumerator.item().FileName + " succeeded");
-	················"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;	+
	}		}
	}		}
-		+	····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 + " does not exist yet");	+	WScript.Echo("Error: " + e.message);
		+	···WScript.Quit(1);
	}		}

	Line 296:		Line 269:
	</job>		</job>
	</code>		</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\|*]].
		+
		+

Differences

Documentation

Support

Associations

Follow Us