Skip to content

File Transfer

Jump to bottom
Robin Rodricks edited this page Jul 28, 2022 · 49 revisions

API

High-level API:

  • UploadStream() - Uploads a Stream to the server. Returns true if succeeded, false if failed. Exceptions are thrown for critical errors. Supports very large files since it uploads data in chunks. Note: Your stream needs to provide its length at the start of the upload, as we cannot upload streams with unknown length.

  • UploadBytes() - Uploads a byte[] to the server. Returns true if succeeded, false if failed. Exceptions are thrown for critical errors. Supports very large files since it uploads data in chunks.

  • DownloadStream() - Downloads a file from the server to a Stream. Returns true if succeeded, false if failed or file does not exist. Exceptions are thrown for critical errors. Supports very large files since it downloads data in chunks.

  • DownloadBytes() - Downloads a file from the server to a byte[]. Returns true if succeeded, false if failed or file does not exist. Exceptions are thrown for critical errors. Supports very large files since it downloads data in chunks.

  • UploadFile() - Uploads a file from the local file system to the server. Use FtpRemoteExists.Resume to resume a partial upload and FtpRemoteExists.AddToEnd to append the given data to the end. Returns FtpStatus to indicate success, skipped or failed. Exceptions are thrown for critical errors. Supports very large files since it uploads data in chunks. Optionally verifies the hash of a file & retries transfer if hash mismatches. Provides detailed progress tracking and metrics via callbacks by sending an FtpProgress object.

  • DownloadFile() - Downloads a file from the server to the local file system. Use FtpLocalExists.Resume to resume a partial download. Returns FtpStatus to indicate success, skipped or failed. Exceptions are thrown for critical errors. Supports very large files since it downloads data in chunks. Local directories are created if they do not exist. Optionally verifies the hash of a file & retries transfer if hash mismatches. Provides detailed progress tracking and metrics via callbacks by sending an FtpProgress object.

  • UploadFiles() - Uploads multiple files from the local file system to a single folder on the server. Returns the number of files uploaded. Skipped files are not counted. User-defined error handling for exceptions during file upload (ignore/abort/throw). Optionally verifies the hash of a file & retries transfer if hash mismatches. Faster than calling UploadFile() multiple times. Provides detailed progress tracking and metrics via callbacks by sending an FtpProgress object.

  • DownloadFiles() - Downloads multiple files from server to a single directory on the local file system. Returns the number of files downloaded. Skipped files are not counted. User-defined error handling for exceptions during file download (ignore/abort/throw). Optionally verifies the hash of a file & retries transfer if hash mismatches. Provides detailed progress tracking and metrics via callbacks by sending an FtpProgress object.

Settings

To increase file transfer speed

  • TransferChunkSize - Chunk size (in bytes) used during upload/download of files. Default: 65536 (65 KB).

  • LocalFileBufferSize - Buffer size (in bytes) used for reading and writing files on the local file system. Default: 4096 (4 KB).

To limit file transfer speed

  • UploadRateLimit - Rate limit for uploads (in kbyte/s), honored by high level API. Default: 0 (Unlimited).

  • DownloadRateLimit - Rate limit for downloads (in kbyte/s), honored by high level API. Default: 0 (Unlimited).

To configure transfer methods

  • UploadDataType - Upload files in ASCII or Binary mode? Default: FtpDataType.Binary.

  • DownloadDataType - Download files in ASCII or Binary mode? Default: FtpDataType.Binary.

  • DownloadZeroByteFiles - If zero-byte files should be downloaded or not. Default: true.

  • RetryAttempts - The retry attempts allowed when a verification failure occurs during download or upload. Default: 1.

  • NoopInterval - Time to wait (in milliseconds) between sending NOOP commands to keep the control socket alive during long file transfers. Setting this interval too low will have a negative impact on performance. Setting this interval to 0 disables NOOP commands altogether. Decrease this setting if you are getting timeouts during file transfers. Read the PR notes for suggested values for this property. Default: 15000 (15 seconds).

Examples

C#

VB.NET

How can I track the progress of file transfers?

All of the high-level methods provide a progress argument that can be used to track upload/download progress.

To use this, first create a callback method to provide to the Upload/Download method. This will be called with an FtpProgress object, containing the percentage transferred as well as various statistics.

If you are creating your UI in WinForms, create a ProgressBar with the Minimum = 0 and Maximum = 100.

Using the asynchronous API:

// Callback method that accepts a FtpProgress object
Progress<FtpProgress> progress = new Progress<FtpProgress>(x => {

	// When progress in unknown, -1 will be sent
	if (x.Progress < 0){
		progressBar.IsIndeterminate = true;
	}else{
		progressBar.IsIndeterminate = false;
		progressBar.Value = x;
	}
});

Using the synchronous API:

// Callback method that accepts a FtpProgress object
Action<FtpProgress> progress = new Action<FtpProgress>(x => {

	// When progress in unknown, -1 will be sent
	if (x.Progress < 0){
		progressBar.IsIndeterminate = true;
	}else{
		progressBar.IsIndeterminate = false;
		progressBar.Value = x;
	}
});

Now call the Upload/Download method providing the new progress object that you just created.

Using the asynchronous API:

await client.DownloadFileAsync(localPath, remotePath, FtpLocalExists.Overwrite, FluentFTP.FtpVerify.Retry, progress);

Using the synchronous API:

client.DownloadFile(localPath, remotePath, FtpLocalExists.Overwrite, FluentFTP.FtpVerify.Retry, progress);

For .NET 2.0 users, pass an implementation of the IProgress class. The Report() method of the object you pass will be called with the progress value.

How can I upload data created on the fly?

Use Upload() for uploading a Stream or byte[].

How can I download data without saving it to disk?

Use Download() for downloading to a Stream or byte[].

How can I resume downloading a file?

Use DownloadFile() or DownloadFiles() with the existsMode set to FtpLocalExists.Append.

// download only the missing part of the file
// by comparing its file size to the size of the local file
client.DownloadFile(@"C:\MyVideo.mp4", "/htdocs/MyVideo.mp4", FtpLocalExists.Append);

Other options are:

  • FtpLocalExists.Skip - If the local file exists, we blindly skip downloading it without any more checks.

  • FtpLocalExists.Overwrite - If the local file exists, we restart the download and overwrite the file.

  • FtpLocalExists.Append - If the local file exists, we resume the download by checking the local file size, and append the missing data to the file.

How can I resume uploading a file?

Using the new UploadFile() API:

// we compare the length of the offline file vs the online file,
// and only write the missing part to the server
client.UploadFile("C:\bigfile.iso", "/htdocs/bigfile.iso", FtpRemoteExists.Resume);

How can I throttle the speed of upload/download?

Set the UploadRateLimit and DownloadRateLimit properties to control the speed of data transfer. Only honored by the high-level API, for both the synchronous and async versions, such as:

  • Upload() / Download()
  • UploadFile() / DownloadFile()
  • UploadFiles() / DownloadFiles()

See this post for more information on the recent improvements to throttling.

How do I append to a file?

Using the UploadFile() API to upload only the newly added part of the file (eg. for log files):

// append data to an existing copy of the file
File.AppendAllText(@"C:\readme.txt", "text to be appended" + Environment.NewLine);

// only the new part of readme.txt will be written to the server
client.UploadFile("C:\readme.txt", "/htdocs/readme.txt", FtpRemoteExists.Resume);

Using the UploadFile() API to upload the given file to the end of the remote file:

// the entire readme.txt will be written to the end of the file on the serer
client.UploadFile("C:\readme.txt", "/htdocs/readme.txt", FtpRemoteExists.AddToEnd);

Using the stream-based OpenAppend() API:

using (FtpClient conn = new FtpClient()) {
	conn.Host = "localhost";
	conn.Credentials = new NetworkCredential("ftptest", "ftptest");
	
	using (Stream ostream = conn.OpenAppend("/full/or/relative/path/to/file")) {
		try {
			ostream.Position = ostream.Length;
			var sr = new StreamWriter(ostream);
			sr.WriteLine(...);
		}
		finally {
			ostream.Close();
			conn.GetReply(); // to read the success/failure response from the server
		}
	}
}

How can I upload/download files with Unicode filenames when my server does not support UTF8?

Set the connection encoding manually to ensure that special characters work properly.

The default codepage that you should use is 1252 Windows Western. It has support for English + European characters (accented chars).

client.Encoding = System.Text.Encoding.GetEncoding(1252); // ANSI codepage 1252 (Windows Western)

Here is the full list of codepages based on the charset you need:

  • 874 – English + Thai
  • 1250 – English + Central Europe
  • 1251 – English + Cyrillic (Russian)
  • 1252 – English + European (accented characters)
  • 1253 – English + Greek
  • 1254 – English + Turkish
  • 1255 – English + Hebrew
  • 1256 – English + Arabic
  • 1257 – English + Baltic
  • 1258 – English + Vietnamese

Examples

Connection

Features

Troubleshooting

Testing

Contributing

API

Clone this wiki locally