.editorconfig (26, 2017-10-25)
.vs (0, 2017-11-08)
.vs\config (0, 2017-11-08)
.vs\config\applicationhost.config (85645, 2017-11-08)
.vs\FluentFTP (0, 2017-11-08)
.vs\FluentFTP\v15 (0, 2017-11-08)
.vs\FluentFTP\v15\.suo (83968, 2017-11-08)
appveyor.yml (397, 2017-10-25)
build.bat (72, 2017-10-25)
FluentFTP (0, 2017-11-08)
FluentFTP.Examples (0, 2017-11-08)
FluentFTP.Examples\BeginConnect.cs (1486, 2017-10-25)
FluentFTP.Examples\BeginCreateDirectory.cs (1641, 2017-10-25)
FluentFTP.Examples\BeginDeleteDirectory.cs (1575, 2017-10-25)
FluentFTP.Examples\BeginDeleteFile.cs (1521, 2017-10-25)
FluentFTP.Examples\BeginDereferenceLink.cs (2289, 2017-10-25)
FluentFTP.Examples\BeginDirectoryExists.cs (1597, 2017-10-25)
FluentFTP.Examples\BeginDisconnect.cs (1511, 2017-10-25)
FluentFTP.Examples\BeginExecute.cs (1710, 2017-10-25)
FluentFTP.Examples\BeginFileExists.cs (1592, 2017-10-25)
FluentFTP.Examples\BeginGetFileSize.cs (1596, 2017-10-25)
FluentFTP.Examples\BeginGetListing.cs (1737, 2017-10-25)
FluentFTP.Examples\BeginGetModifiedTime.cs (1635, 2017-10-25)
FluentFTP.Examples\BeginGetNameListing.cs (1855, 2017-10-25)
FluentFTP.Examples\BeginGetWorkingDirectory.cs (1642, 2017-10-25)
FluentFTP.Examples\BeginOpenAppend.cs (2058, 2017-10-25)
FluentFTP.Examples\BeginOpenRead.cs (2583, 2017-10-25)
FluentFTP.Examples\BeginOpenWrite.cs (2052, 2017-10-25)
FluentFTP.Examples\BeginRename.cs (1550, 2017-10-25)
FluentFTP.Examples\BeginSetWorkingDirectory.cs (1557, 2017-10-25)
FluentFTP.Examples\bin (0, 2017-11-08)
FluentFTP.Examples\bin\Debug (0, 2017-11-08)
FluentFTP.Examples\bin\Debug\net45 (0, 2017-11-08)
FluentFTP.Examples\bin\Debug\net45\Examples.exe (27136, 2017-11-08)
FluentFTP.Examples\bin\Debug\net45\Examples.pdb (14664, 2017-11-08)
FluentFTP.Examples\bin\Debug\net45\Examples.runtimeconfig.dev.json (114, 2017-11-08)
FluentFTP.Examples\bin\Debug\net45\Examples.runtimeconfig.json (28, 2017-11-08)
FluentFTP.Examples\bin\Debug\net45\FluentFTP.dll (263680, 2017-11-08)
... ...
# FluentFTP
[](https://www.nuget.org/packages/FluentFTP)
FluentFTP is a fully managed FTP and FTPS library for .NET & .NET Standard, optimized for speed. It provides extensive FTP commands, File uploads/downloads, SSL/TLS connections, Automatic directory listing parsing, File hashing/checksums, File permissions/CHMOD, FTP proxies, UTF-8 support, Async/await support and more.
It is written entirely in C#, with no external dependencies. FluentFTP is released under the permissive MIT License, so it can be used in both proprietary and free/open source applications.
## Features
- Full support for [FTP](#ftp-support), [FTPS](#faq_ftps) (FTP over SSL), [FTPS with client certificates](#faq_certs) and [FTPS with CCC](#faq_ccc) (for FTP firewalls)
- **File management:**
- File and directory listing for [all major server types](#faq_listings) (Unix, Windows/IIS, Azure, Pure-FTPd, ProFTPD, Vax, VMS, OpenVMS, Tandem, HP NonStop Guardian, IBM OS/400, AS400, Windows CE, etc)
- Easily upload and download a file from the server with [progress tracking](#faq_progress)
- Automatically [verify the hash](#faq_verifyhash) of a file & retry transfer if hash mismatches
- Configurable error handling (ignore/abort/throw) for multi-file transfers
- Easily read and write file data from the server using standard streams
- Create, append, read, write, rename, move and delete files and folders
- Recursively deletes folders and all its contents
- Get file/folder info (exists, size, security flags, modified date/time)
- Get and set [file permissions](#file-permissions) (owner, group, other)
- Absolute or relative paths (relative to the ["working directory"](#file-management))
- Get the [hash/checksum](#file-hashing) of a file (SHA-1, SHA-256, SHA-512, and MD5)
- Dereference of symbolic links to calculate the linked file/folder
- **FTP protocol:**
- Extensive support for [FTP commands](#ftp-support), including some server-specific commands
- Easily send [server-specific](https://github.com/hgupta9/FluentFTP/issues/88) FTP commands using the `Execute()` method
- Explicit and Implicit [SSL connections](#faq_ftps) are supported for the control and data connections using .NET's `SslStream`
- Passive and active data connections (PASV, EPSV, PORT and EPRT)
- Supports DrFTPD's PRET command, and the Unix CHMOD command
- Supports [FTP Proxies](#faq_loginproxy) (User@Host, HTTP 1.1)
- [FTP command logging](#faq_log) using `TraceListeners` (passwords omitted) to [trace](#faq_trace) or [log output](#faq_logfile) to a file
- SFTP is not supported as it is FTP over SSH, a completely different protocol (use [SSH.NET](https://github.com/sshnet/SSH.NET) for that)
- **Asynchronous support:**
- Synchronous and asynchronous methods using `async`/`await` for all operations
- Asynchronous methods for .NET 4.0 and below using `IAsyncResult` pattern (Begin*/End*)
- Improves thread safety by cloning the FTP control connection for file transfers (optional)
- Implements its own internal locking in an effort to keep transactions synchronized
- **Extensible:**
- Easily add support for more proxy types (simply extend [`FTPClientProxy`](https://github.com/hgupta9/FluentFTP/blob/master/FluentFTP/Proxy/FtpClientProxy.cs))
- Easily add unsupported directory listing parsers (see the [`CustomParser`](https://github.com/hgupta9/FluentFTP/blob/f48af030b565237ddd5d7c8937378884d20e1627/FluentFTP.Examples/CustomParser.cs) example)
- Easily add custom logging/tracing functionality using [`FtpTrace.AddListener`](#faq_log)
## Releases
Stable binaries are released on NuGet, and contain everything you need to use FTP/FTPS in your .Net/CLR application. For usage see the [Example Usage](#example-usage) section and the [Documentation](#documentation) section below.
- [Nuget](https://www.nuget.org/packages/FluentFTP) (latest)
- [Releases](https://github.com/hgupta9/FluentFTP/releases) (occasionally updated)
FluentFTP works on .NET and .NET Standard/.NET Core.
| Platform | Binaries Folder |
|--------------- |----------- |
| **.NET 2.0** | net20 |
| **.NET 3.5** | net35 |
| **.NET 4.0** | net40 |
| **.NET 4.5** | net45 |
| **.NET Standard 1.4** | netstandard1.4 |
| **.NET Standard 1.6** | netstandard1.6 |
FluentFTP is also supported on these platforms: (via .NET Standard)
- **Mono** 4.6
- **Xamarin.iOS** 10.0
- **Xamarin.Android** 10.0
- **Universal Windows Platform** 10.0
Binaries for all platforms are built from a single VS 2017 Project. You will need VS 2017 to build or contribute to FluentFTP.
## Example Usage
```csharp
// create an FTP client
FtpClient client = new FtpClient("123.123.123.123");
// if you don't specify login credentials, we use the "anonymous" user account
client.Credentials = new NetworkCredential("david", "pass123");
// begin connecting to the server
client.Connect();
// get a list of files and directories in the "/htdocs" folder
foreach (FtpListItem item in client.GetListing("/htdocs")) {
// if this is a file
if (item.Type == FtpFileSystemObjectType.File){
// get the file size
long size = client.GetFileSize(item.FullName);
}
// get modified date/time of the file or folder
DateTime time = client.GetModifiedTime(item.FullName);
// calculate a hash for the file on the server side (default algorithm)
FtpHash hash = client.GetHash(item.FullName);
}
// upload a file
client.UploadFile(@"C:\MyVideo.mp4", "/htdocs/big.txt");
// rename the uploaded file
client.Rename("/htdocs/big.txt", "/htdocs/big2.txt");
// download the file again
client.DownloadFile(@"C:\MyVideo_2.mp4", "/htdocs/big2.txt");
// delete the file
client.DeleteFile("/htdocs/big2.txt");
// delete a folder recursively
client.DeleteDirectory("/htdocs/extras/");
// check if a file exists
if (client.FileExists("/htdocs/big2.txt")){ }
// check if a folder exists
if (client.DirectoryExists("/htdocs/extras/")){ }
// upload a file and retry 3 times before giving up
client.RetryAttempts = 3;
client.UploadFile(@"C:\MyVideo.mp4", "/htdocs/big.txt", FtpExists.Overwrite, false, FtpVerify.Retry);
// disconnect! good bye!
client.Disconnect();
```
## Documentation
- [API Documentation](#api)
- [Connection](#connection)
- [Directory Listing](#directory-listing)
- [File Transfer](#file-transfer)
- [File Management](#file-management)
- [File Permissions](#file-permissions)
- [File Hashing](#file-hashing)
- [FTPS](#ftps)
- [Settings](#advanced-settings)
- [Utilities](#utilities)
- [Logging](#logging)
- [FTP Support Table](#ftp-support)
- [Examples](https://github.com/hgupta9/FluentFTP/tree/master/FluentFTP.Examples)
- [Release Notes](#release-notes)
- [Misc Notes](#notes)
- [Credits](#credits)
## FAQs
**Logging FAQs**
- [How do I trace FTP commands for debugging?](#faq_trace)
- [How do I log all FTP commands to a file for debugging?](#faq_logfile)
- [How do I log only critical errors to a file?](#faq_logfile2)
- [How do I disable logging of function calls?](#faq_logfunc)
- [How do I omit sensitive information from the logs?](#faq_hidelog)
- [How do I use third-party logging frameworks like NLog?](#faq_log)
**Connection FAQs**
- [How do I connect with SSL/TLS? / How do I use FTPS?](#faq_ftps)
- [How do I validate the server's certificate when using FTPS?](#faq_ftps)
- [How do I connect with FTPS and then switch back down to plaintext FTP?](#faq_ccc)
- [How do I connect with SFTP?](#faq_sftp)
- [How do I login with an anonymous FTP account?](#faq_loginanon)
- [How do I login with an FTP proxy?](#faq_loginproxy)
- [How do I use client certificates to login with FTPS?](#faq_certs)
- [How do I bundle an X509 certificate from a file?](#faq_x509)
**File Transfer FAQs**
- [How can I track the progress of file transfers?](#faq_progress)
- [How can I upload data created on the fly?](#faq_uploadbytes)
- [How can I download data without saving it to disk?](#faq_downloadbytes)
- [How can I throttle the speed of upload/download?](#faq_throttle)
- [How do I verify the hash/checksum of a file and retry if the checksum mismatches?](#faq_verifyhash)
- [How do I upload only the missing part of a file?](#faq_uploadmissing)
- [How do I append to a file?](#faq_append)
- [How do I download files using the low-level API?](#faq_downloadlow)
- [How can I upload/download files with Unicode filenames when my server does not support UTF8?](#faq_utf)
**File Management FAQs**
- [How does GetListing() work internally?](#faq_listings)
- [What kind of hashing commands are supported?](#faq_hashing)
**Misc FAQs**
- [What does `EnableThreadSafeDataConnections` do?](#faq_etsdc)
- [How can I contribute some changes to FluentFTP?](#faq_fork)
- [How do I submit a pull request?](#faq_fork)
**Common Issues**
- [I'm getting login errors but I can login fine in Firefox/Filezilla](#faq_loginanon)
- [FluentFTP fails to install in Visual Studio 2010 : 'System.Runtime' already has a dependency defined for 'FluentFTP'.](#trouble_install)
- [After uploading a file with special characters like "Caffe.png" it appears as "Caff?.bmp" on the FTP server. The server supports only ASCII but "e" is ASCII. FileZilla can upload this file without problems.](#trouble_specialchars)
- [I cannot delete a file if the filename contains Russian letters. FileZilla can delete this file without problems.](#trouble_specialchars2)
- [I keep getting TimeoutException's in my Azure WebApp](#trouble_azure)
- [Many commands don't work on Windows CE](#trouble_windowsce)
- [After successfully transfering a single file with OpenWrite/OpenAppend, the subsequent files fail with some random error, like "Malformed PASV response"](#trouble_getreply)
- [SSL Negotiation is very slow during FTPS login](#trouble_ssl)
- [Unable to read data from the transport connection : An existing connection was forcibly closed by the remote host](#trouble_closedhost)
## API
Complete API documentation for the `FtpClient` class, which handles all FTP/FTPS functionality.
**Note:** All methods support synchronous and asynchronous versions. Simply add the "Async" postfix to a method for `async`/`await` syntax in .NET 4.5+, or add the "Begin"/"End" prefix to a method for .NET 4.0 and below.
### Connection
- **new FtpClient**() - Creates and returns a new FTP client instance.
- **Host** - The FTP server IP or hostname. Required.
- **Port** - The FTP port to connect to. **Default:** Auto (21 or 990 depending on FTPS config)
- **Credentials** - The FTP username & password to use. Must be a valid user account registered with the server. **Default:** `anonymous/anonymous`
- **Connect**() - Connects to an FTP server (uses TLS/SSL if configured).
- **Disconnect**() - Closes the connection to the server immediately.
- **Execute**() - Execute a custom or unspported command.
- **SystemType** - Gets the type of system/server that we're connected to.
- **IsConnected** - Checks if the connection is still alive.
- **Capabilities** - Gets the server capabilties (represented by flags).
- **HasFeature**() - Checks if a specific feature (`FtpCapability`) is supported by the server.
### Directory Listing
- **GetListing**() - Get a [file listing](#faq_listings) of the given directory. Returns one `FtpListItem` per file or folder with all available properties set. Each item contains:
- `Type` : The type of the object. (File, Directory or Link)
- `Name` : The name of the object. (minus the path)
- `FullName` : The full file path of the object.
- `Created ` : The created date/time of the object. **Default:** `DateTime.MinValue` if not provided by server.
- `Modified` : The last modified date/time of the object. If you get incorrect values, try adding the `FtpListOption.Modify` flag which loads the modified date/time using another `MDTM` command. **Default:** `DateTime.MinValue` if not provided by server.
- `Size` : The size of the file in bytes. If you get incorrect values, try adding the `FtpListOption.Size` flag which loads the file size using another `SIZE` command. **Default:** `0` if not provided by server.
- `LinkTarget` : The full file path the link points to. Only filled for symbolic links.
- `LinkObject` : The file/folder the link points to. Only filled for symbolic links if `FtpListOption.DerefLink` flag is used.
- `SpecialPermissions` : Gets special permissions such as Stiky, SUID and SGID.
- `Chmod` : The CHMOD permissions of the object. For example ***4 or 755. **Default:** `0` if not provided by server.
- `OwnerPermissions` : User rights. Any combination of 'r', 'w', 'x' (using the `FtpPermission` enum). **Default:** `FtpPermission.None` if not provided by server.
- `GroupPermissions` : Group rights. Any combination of 'r', 'w', 'x' (using the `FtpPermission` enum). **Default:** `FtpPermission.None` if not provided by server.
- `OtherPermissions` : Other rights. Any combination of 'r', 'w', 'x' (using the `FtpPermission` enum). **Default:** `FtpPermission.None` if not provided by server.
- `RawPermissions` : The raw permissions string recieved for this object. Use this if other permission properties are blank or invalid.
- `Input` : The raw string that the server returned for this object. Helps debug if the above properties have been correctly parsed.
- **GetNameListing**() - A simple command that only returns the list of file paths in the given directory, using the NLST command.
- **GetObjectInfo()** - Get information for a single file or directory as an `FtpListItem`. It includes the type, date created, date modified, file size, permissions/chmod and link target (if any).
### File Transfer
*High-level API:*
- **Upload**() - Uploads a Stream or byte[] to the server. Returns true if succeeded, false if failed or file does not exist. Exceptions are thrown for critical errors. Supports very large files since it uploads data in chunks.
- **Download**() - Downloads a file from the server to a Stream or 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 `FtpExists.Append` to append to a file. Returns true if succeeded, false if failed or file does not exist. Exceptions are thrown for critical errors. Supports very large files since it uploads data in chunks. Optionally [verifies the hash](#faq_verifyhash) of a file & retries transfer if hash mismatches.
- **DownloadFile**() - Downloads a file from the server to the local file system. 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. Local directories are created if they do not exist. Optionally [verifies the hash](#faq_verifyhash) of a file & retries transfer if hash mismatches.
- **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](#faq_verifyhash) of a file & retries transfer if hash mismatches. Faster than calling `UploadFile()` multiple times.
- **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](#faq_verifyhash) of a file & retries transfer if hash mismatches.
*Low-level API:*
- **OpenRead**() - *(Prefer using `Download()` for downloading to a `Stream` or `byte[]`)* Open a stream to the specified file for reading. Returns a [standard `Stream`](#stream-handling). Please call `GetReply()` after you have successfully transfered the file to read the "OK" command sent by the server and prevent stale data on the socket.
- **OpenWrite**() - *(Prefer using `Upload()` for uploading a `Stream` or `byte[]`)* Opens a stream to the specified file for writing. Returns a [standard `Stream`](#stream-handling), any data written will overwrite the file, or create the file if it does not exist. Please call `GetReply()` after you have successfully transfered the file to read the "OK" command sent by the server and prevent stale data on the socket.
- **OpenAppend**() - *(Prefer using `Upload()` with `FtpExists.Append` for uploading a `Stream` or `byte[]`)* Opens a stream to the specified file for appending. Returns a [standard `Stream`](#stream-handling), any data written wil be appended to the end of the file. Please call `GetReply()` after you have successfully transfered the file to read the "OK" command sent by the server and prevent stale data on the socket.
### File Management
*Working directory (relative paths are relative to this directory):*
- **GetWorkingDirectory**() - Gets the full path of the current working directory.
- **SetWorkingDirectory**() - Sets the full path of the current working directory. All relative paths are relative to the working directory.
*Directories:*
- **DirectoryExists**() - Check if a directory exists on the server.
- **CreateDirectory**() - Creates a directory on the server. If the parent directories do not exist they are also created.
- **DeleteDirectory**() - Deletes the specified directory on the server. If it is not empty then all subdirectories and files are recursively deleted.
- **MoveDirectory**() - Moves a directory from one place to another on the server. The destination directory is deleted before moving if `FtpExists.Overwrite` is used. Only throws exceptions for critical errors.
*Files:*
- **FileExists**() - Check if a file exists on the server.
- **DeleteFile**() - Deletes the specified file on the server.
- **MoveFile**() - Moves a file from one directory to another on the server. The destination file is deleted before moving if `FtpExists.Overwrite` is used. Only throws exceptions for critical errors.
- **Rename**() - Renames the file/directory on the server. Low level method that should NOT be used in most cases. Prefer `MoveFile()` and `MoveDirectory()`. Throws exceptions if the source does not exist, or if the destination already exists.
- **GetModifiedTime**() - Gets the last modified date/time of the file or folder. Result may be in server timezone, local timezone or UTC, depending on `type` argument.
- **SetModifiedTime**() - Modifies the last modified date/time of the file or folder. Input may be in server timezone, local timezone or UTC, depending on `type` argument.
- **GetFileSize**() - Gets the size of the file in bytes, or -1 if not found.
- **DereferenceLink**() - Recursively dereferences a symbolic link and returns the full path if found. The `MaximumDereferenceCount` property controls how deep we recurse before giving up.
### File Permissions
*Standard commands supported by most servers*
- **GetChmod**() - Gets the CHMOD permissions of the file/folder, or 0 if not found.
- **GetFilePermissions**() - Gets the permissions of the given file/folder as an FtpListItem object with all "Permission" properties set, or null if not found.
*Only supported by UNIX FTP servers which have the CHMOD extension installed and enabled.*
- **Chmod**() - Modifies the permissions of the given file/folder, given the CHMOD value.
- ** ... ...