More .NET libraries
-
Rebex FTP/SSL
.NET FTP client
-
Rebex SSH Shell
.NET SSH Shell
-
Rebex Total Pack
All Rebex .NET libraries together
Back to feature list...
More file transfer operations
On this page:
Resuming interrupted transfers
When a connection is lost or aborted, you may end up with incompletely transferred file. Instead of transferring in all over again, it's possible to resume the operation and only transfer the missing part.
Upload
and Download
methods can do this - just specify ActionOnExistingFiles.ResumeIfPossible
when calling. This will:
- transfer files which were not transferred yet (don't exist at the destination)
- transfer remaining parts of files which are smaller at the destination than on source
- skip all other files
// auto-resume failed directory upload sftp.Upload(@"C:\MyData\*", "/MyData", 0, 0, ActionOnExistingFiles.ResumeIfPossible); // auto-resume failed single file download sftp.Download("/MyData/file.txt", @"C:\MyData", 0, 0, ActionOnExistingFiles.ResumeIfPossible);
' auto-resume failed directory upload sftp.Upload("C:\MyData\*", "/MyData", 0, 0, ActionOnExistingFiles.ResumeIfPossible) ' auto-resume failed single file download sftp.Download("/MyData/file.txt", "C:\MyData", 0, 0, ActionOnExistingFiles.ResumeIfPossible)
ResumeIfPossible
will not re-establish interrupted transfer automatically.
If transfer is aborted, you have to re-establish connection and start transfer with ResumeIfPossible
manually.
Overwriting existing files
When transferring multiple files using Upload
or Download
method,
use ActionOnExistingFiles
argument to specify what to do when a target file already exists.
To overwrite existing files, use one of these options:
OverwriteAll
- Overwrites all files.OverwriteOlder
- Overwrites files which are older that source files.OverwriteDifferentSize
- Overwrites files which have different size.OverwriteDifferentChecksum
- Overwrites files which have different checksum.
Note: Only some SFTP servers support checksums.
Alternatively, in order not to overwrite existing files, use one of these instead:
SkipAll
- Skip files.ResumeIfPossible
- Resume the transfer if possible.Rename
- Rename files using "filename[number].extension" pattern.ThrowException
- Fail with an error.
ActionOnExistingFiles
argument specifies default behavior.
However, you can still override it using ProblemDetected
event.
// set desired overwrite mode according to a .config file ActionOnExistingFiles action = ActionOnExistingFiles.ThrowException; switch (ConfigurationManager.AppSettings["OverwriteMode"]) { case "skip": action = ActionOnExistingFiles.SkipAll; break; case "all": action = ActionOnExistingFiles.OverwriteAll; break; case "older": action = ActionOnExistingFiles.OverwriteOlder; break; case "size": action = ActionOnExistingFiles.OverwriteDifferentSize; break; } // set granularity to whole days (ignore time component) // used when OverwriteOlder is selected sftp.Settings.TimeComparisonGranularity = TimeComparisonGranularity.Days; // upload directory with specific overwrite mode sftp.Upload(@"C:\MyData\*", "/MyData", 0, 0, action);
' set desired overwrite mode according to a .config file Dim action = ActionOnExistingFiles.ThrowException Select Case ConfigurationManager.AppSettings("OverwriteMode") Case "skip" : action = ActionOnExistingFiles.SkipAll Case "all" : action = ActionOnExistingFiles.OverwriteAll Case "older" : action = ActionOnExistingFiles.OverwriteOlder Case "size" : action = ActionOnExistingFiles.OverwriteDifferentSize End Select ' set granularity to whole days (ignore time component) ' used when OverwriteOlder is selected sftp.Settings.TimeComparisonGranularity = TimeComparisonGranularity.Days ' upload directory with specific overwrite mode sftp.Upload("C:\MyData\*", "/MyData", 0, 0, action)
Auto-renaming existing files
When transferring multiple files using Upload
or Download
method,
specify the ActionOnExistingFiles.Rename
argument to automatically rename transferred
file if the target file already exists. This will add a number between the filename and extension ("filename[number].extension" pattern).
ProblemDetected
event instead.
// upload directory, // auto-rename transferred files // if target file already exists sftp.Upload(@"C:\MyData\*", "/MyData", 0, 0, ActionOnExistingFiles.Rename); // download file, // rename it if "C:\MyData\file.txt" already exists // (e.g., "C:\MyData\file[1].txt" might be created) sftp.Download("/MyData/file.txt", @"C:\MyData", 0, 0, ActionOnExistingFiles.Rename);
' upload directory, ' auto-rename transferred files ' if target file already exists sftp.Upload("C:\MyData\*", "/MyData", 0, 0, ActionOnExistingFiles.Rename) ' download file, ' rename it if "C:\MyData\file.txt" already exists ' (e.g., "C:\MyData\file[1].txt" might be created) sftp.Download("/MyData/file.txt", "C:\MyData", 0, 0, ActionOnExistingFiles.Rename)
Progress reporting
Displaying progress of both single-file and multi-file transfers is simple with TransferProgressChanged
event. It keeps you updated with:
ProgressPercentage
- percentage of the whole operation that has been completed (useful when transferring multiple files)CurrentFileProgressPercentage
- percentage of the current file that has been transferredBytesPerSecond
- approximate current transfer speedAction
- current action (upload or download)SourceItem
- information about the currently processed itemTransferState
- current operation state (processing file or directory, data block, whole file transferred, ...)- And much more (
TargetPath
,FilesProcessed
,FilesTotal
, ...)
Traversing
event.
Sample transfer progress event handler:
System.Windows.Forms.ProgressBar fileProgressBar; System.Windows.Forms.ProgressBar totalProgressBar; System.Windows.Forms.Label transferSpeedLabel; void client_TransferProgressChanged(object sender, SftpTransferProgressChangedEventArgs e) { // update ProgressBar of the current file fileProgressBar.Value = (int)e.CurrentFileProgressPercentage; // update ProgressBar of the whole transfer totalProgressBar.Value = (int)e.ProgressPercentage; // update transfer speed transferSpeedLabel.Text = e.BytesPerSecond.ToString(); }
Dim fileProgressBar As System.Windows.Forms.ProgressBar Dim totalProgressBar As System.Windows.Forms.ProgressBar Dim transferSpeedLabel As System.Windows.Forms.Label Sub client_TransferProgressChanged(ByVal sender As Object, ByVal e As SftpTransferProgressChangedEventArgs) ' update ProgressBar of the current file fileProgressBar.Value = e.CurrentFileProgressPercentage ' update ProgressBar of the whole transfer totalProgressBar.Value = e.ProgressPercentage ' update transfer speed transferSpeedLabel.Text = e.BytesPerSecond.ToString() End Sub
Registering the event:
// register TransferProgressChanged event handler which is raised // when a significant action occurs sftp.TransferProgressChanged += client_TransferProgressChanged; // transfer files // ...
' register TransferProgressChanged event handler which is raised ' when a significant action occurs AddHandler sftp.TransferProgressChanged, AddressOf client_TransferProgressChanged ' transfer files ' ...
Transfer problem handling
When a problem occurs in Upload
or Download
method, your code can get notified about it using
the ProblemDetected
event and react accordingly.
See TransferProblemType
enum for a list of possible problems you can handle.
The SftpProblemDetectedEventArgs
argument of the event
makes it possible to determine what is going on and choose an appropriate reaction.
These are some of the properties available:
Exception
- an exception (if any) which will be raised if the problem is not handledProblemType
- the kind of problem that has occurredAction
- current action (upload, download, ...)Reaction
- selected reaction (fail, skip, overwrite, ...)
Sample ProblemDetected event handler
The following code shows a ProblemDetected
event handler
that provides a custom 'FileExists' problem handling:
- Already-existing ".txt" files are renamed
- Other already-existing files are overwritten, but only if they are older than 7 days
- All other problems will be handled using the default behavior (see below)
void client_ProblemDetected(object sender, SftpProblemDetectedEventArgs e) { // handle only existing files problem if (e.ProblemType != TransferProblemType.FileExists) return; // rename ".txt" files if (Path.GetExtension(e.LocalPath) == ".txt") { e.Rename(); return; } // initialize source and target dates (use whole date granularity) DateTime source = e.LocalItem.LastWriteTime.Value.Date; DateTime target = e.RemoteItem.LastWriteTime.Value.Date; // overwrite files which are older than 7 days if (source > target && target < DateTime.Now.AddDays(-7)) { e.Overwrite(); return; } }
Sub client_ProblemDetected(ByVal sender As Object, ByVal e As SftpProblemDetectedEventArgs) ' handle only existing files problem If e.ProblemType <> TransferProblemType.FileExists Then Return ' rename ".txt" files If Path.GetExtension(e.LocalPath) = ".txt" Then e.Rename() Return End If ' initialize source and target dates (use whole date granularity) Dim source = e.LocalItem.LastWriteTime.Value.Date Dim target = e.RemoteItem.LastWriteTime.Value.Date ' overwrite files which are older than 7 days If source > target AndAlso target < DateTime.Now.AddDays(-7) Then e.Overwrite() Return End If End Sub
Registering the event and setting the default behavior:
// register ProblemDetected event handler which is raised // when target file already exists (besides other things) sftp.ProblemDetected += client_ProblemDetected; // upload directory (skip existing files by default) sftp.Upload(@"C:\MyData\*", "/MyData", 0, 0, ActionOnExistingFiles.SkipAll);
' register ProblemDetected event handler which is raised ' when target file already exists (besides other things) AddHandler sftp.ProblemDetected, AddressOf client_ProblemDetected ' upload directory (skip existing files by default) sftp.Upload("C:\MyData\*", "/MyData", 0, 0, ActionOnExistingFiles.SkipAll)
Restoring date&time after transfer
By default, file times (creation, last access or last write time) are not synchronized after a successful file transfer.
Use Settings.RestoreDateTime
property to enable file time synchronization.
// set to restore last modified time sftp.Settings.RestoreDateTime = ItemDateTimes.LastWriteTime; // transfer files // ...
' set to restore last modified time sftp.Settings.RestoreDateTime = ItemDateTimes.LastWriteTime ' transfer files ' ...
Please note that time granularity of SFTP server and local file system can differ. For example, many SFTP servers ignore the millisecond part of file date/time.
ASCII and binary transfer modes
The default transfer mode is binary, which means data is transferred as is without any processing. However, when transferring text data between platforms which use different end-of-line sequences (Windows use <CR><LF> Unix uses <LF>), it's useful to have the sequences automatically converted by setting the transfer mode to ASCII.
Use TransferType
property to specify the desired transfer type.
Optionally, set ServerType
property to specify the target OS type as well (autodetection is not perfect).
// set server type to UNIX sftp.ServerType = SftpServerType.Unix; // set transfer type to ASCII sftp.TransferType = SftpTransferType.Ascii; // transfer files // ...
' set server type to UNIX sftp.ServerType = SftpServerType.Unix ' set transfer type to ASCII sftp.TransferType = SftpTransferType.Ascii ' transfer files ' ...
Back to feature list...