Directory Transfer

API

Tip: For detailed documentation refer to the IntelliSense tips that appear when you call a given API method.

• UploadDirectory() - Uploads the specified directory onto the server. If any rules are provided then we only upload the files and folders matching all the rules. Returns one [FtpResult per file or folder, containing its detailed transfer status. All exceptions during uploading are caught, and the exception is stored in the related FtpResult and uploading continues. Optionally verifies the hash of the files & retries transfer if hash mismatches. Provides detailed progress tracking and metrics via callbacks by sending an FtpProgress object.

  • In Mirror mode, we will upload missing files, and delete any extra files from the server that are not present on disk. This is very useful when publishing an exact copy of a local folder onto an FTP server.

  • In Update mode, we will only upload missing files and preserve any extra files on the server. This is useful when you want to simply upload missing files to a server.

• DownloadDirectory() - Downloads the specified directory onto the local file system. If any rules are provided then we only download the files and folders matching all the rules. Returns one [FtpResult per file or folder, containing its detailed transfer status. All exceptions during downloading are caught, and the exception is stored in the related FtpResult and downloading continues. 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.

  • In Mirror mode, we will download missing files, and delete any extra files from disk that are not present on the server. This is very useful when creating an exact local backup of an FTP directory.

  • In Update mode, we will only download missing files and preserve any extra files on disk. This is useful when you want to simply download missing files from an FTP directory.

Settings

• All the file transfer settings are also applicable for directory transfer.

• Config.UploadDirectoryDeleteExcluded - Controls if the UploadDirectory API deletes the excluded files when uploading in Mirror mode. If true, then any files that are excluded will be deleted from the FTP server if they are excluded from the local system. This is done to keep the server in sync with the local system. But if it is false, the excluded files are not touched on the server, and simply ignored. Default: true.

• Config.DownloadDirectoryDeleteExcluded - Controls if the DownloadDirectory API deletes the excluded files when downloading in Mirror mode. If true, then any files that are excluded will be deleted from the local filesystem if they are excluded from the FTP server. This is done to keep the local filesystem in sync with the FTP server. But if it is false, the excluded files are not touched on the local filesystem, and simply ignored. Default: true.

Examples

C#

• DownloadDirectory.cs
• DownloadDirectoryWithRules.cs
• UploadDirectory.cs
• UploadDirectoryWithRules.cs

VB.NET

• DownloadDirectory.vb
• DownloadDirectoryWithRules.vb
• UploadDirectory.vb
• UploadDirectoryWithRules.vb

What is the difference between the Mirror and Update modes?

Mirror mode is a bit more dangerous because files are deleted from the target if they are not present in the source. This is very useful when you want to create an exact backup, for example, and when you want the backup to contain only the files that are in the source and nothing more.

Update mode is safer and simply transfers the missing files (or overwrites all the files if FtpRemoteExists.Overwrite is used). And Update mode does not delete anything from the target.

How do I tell if some files failed to transfer?

You can check the list of FtpResult objects returned by the method. You can filter all the objects where result.IsSuccess = false and then you can read the result.Exception property to get the exact error that caused it to fail.

• If any files already existed in the target and they were skipped, then the result object will have result.IsSkipped = true and result.IsSuccess = true.

• If any files did not pass the rules provided and thus were skipped for copying, then the result object will have result.IsSkipped = true and result.IsSkippedByRule = true and result.IsSuccess = true.

• The files that were actually copied or overwritten will have result.IsSkipped = false and result.IsSuccess = true.

What kinds of rules are supported and how do rules work?

See the Rules page for info and code examples.

How can I track the progress of folder transfers?

See this File Transfer FAQ for basic information on progress tracking. In addition to the basic properties you can access these properties in the FtpProgress object to find out which file is being transferred:

• LocalPath - Stores the absolute local path of the the current file being transferred.

• RemotePath - Stores the absolute remote path of the the current file being transferred.

• FileIndex - Stores the 0-based index of the the file in the listing.

• FileCount - Stores the total count of the files to be transferred. This does not include directories.