Rebex FTP

FTP and FTPS client .NET library

Download 30-day free trial Buy from $349
More .NET libraries

Back to feature list...

Single file operations

On this page:

Single-file upload and download 

Use PutFile method to upload a single file, and GetFile method to download it. Both methods require a target name, which means it's possible to use a different target file name if needed. 

// upload a local file to server
ftp.PutFile(@"C:\MyData\file.txt", "/MyData/file.txt");

// download from server to a local file using a different name
ftp.GetFile("/MyData/file.txt", @"C:\MyData\copy-file.txt");

' upload a local file to server
ftp.PutFile("C:\MyData\file.txt", "/MyData/file.txt")

' download from server to a local file using a different name
ftp.GetFile("/MyData/file.txt", "C:\MyData\copy-file.txt")

These methods overwrite any existing files. To check whether a remote file exists, use FileExists method.

Tip: For uploading or downloading multiple files, use Upload and Download methods. They accept single-file input as well and support both single-file and multi-file transfers.

Stream-based upload and download 

Both PutFile and GetFile methods accept a System.IO.Stream object, making it possible to transfer data from/to any kind of stream.

For example, use MemoryStream when processing data in memory, without having to create temporary disk files:

Upload from memory:

// prepare data
byte[] data = System.Text.Encoding.UTF8.GetBytes("test data");

// convert data to a memory stream
var stream = new MemoryStream(data);

// upload data from memory
ftp.PutFile(stream, "/MyData/file.txt");

' prepare data
Dim data() As Byte = System.Text.Encoding.UTF8.GetBytes("test data")

' convert data to a memory stream
Dim stream As New MemoryStream(data)

' upload data from memory
ftp.PutFile(stream, "/MyData/file.txt")

Download to memory:

// download a remote file into a memory stream
var stream = new MemoryStream();
ftp.GetFile("/MyData/file.txt", stream);

// convert memory stream to data
byte[] data = stream.ToArray();

' download a remote file into a memory stream
Dim stream As New MemoryStream()
ftp.GetFile("/MyData/file.txt", stream)

' convert memory stream to data
Dim data() As Byte = stream.ToArray()

Deleting a file 

To delete a remote file, use DeleteFile method.

For example, to delete a remote file that doesn't exist locally, use the following code: 

// if local file is deleted
if (!File.Exists(@"C:\MyData\file.txt"))
{
    // delete remote file as well
    ftp.DeleteFile("/MyData/file.txt");
}

' if local file is deleted
If Not File.Exists("C:\MyData\file.txt") Then
    ' delete remote file as well
    ftp.DeleteFile("/MyData/file.txt")
End If

Tip: For deleting multiple files or non-empty directories, use Delete method.

Rename/move a file 

To rename a remote file or directory, use Rename method. It can also be used for moving a remote file or directory to another location on the file system of the remote host. 

// rename a remote file
ftp.Rename("/MyData/a.txt", "/MyData/b.txt");

// move a remote file
ftp.Rename("/MyData/file.txt", "/Backups/file.txt");

' rename a remote file
ftp.Rename("/MyData/a.txt", "/MyData/b.txt")

' move a remote file
ftp.Rename("/MyData/file.txt", "/Backups/file.txt")

Tip: For moving files between client and server, use Upload or Download methods with the TransferMethod.Move argument specified.

Checking file existence 

To check whether a remote file already exists, use FileExists method.

This is useful, for example, when you are about to upload a file, but would like to ask the user whether to overwrite an existing target file first: 

// check whether a remote file exists
bool exists = ftp.FileExists("/MyData/file.txt");

if (exists)
{
    // prompt the user
    // ...
}

' check whether a remote file exists
Dim exists = ftp.FileExists("/MyData/file.txt")

If exists Then
    ' prompt the user
    ' ...
End If
Tip: Upload or Download methods have built-in overwrite mode support.

Please be aware that this operation is not a part of the original FTP protocol. Although FileExists tries several ways to check whether the file exists and works well with almost all FTP servers, it may fail on some legacy FTP servers with a "not supported" exception.

Getting file length 

To retrieve the length of a remote file, use GetFileLength method:.

This can be used to determine the current remote file length when resuming a broken transfer or in order to ask the user for permission before downloading a large file over a slow network: 

// get the length of a remote file
long length = ftp.GetFileLength("/MyData/file.txt");

// large downloads need user permission
if (length > 1024 * 1024)
{
    // prompt the user what to do with file > 1 MB
    // ...
}

' get the length of a remote file
Dim length = ftp.GetFileLength("/MyData/file.txt")

' large downloads need user permission
If length > 1024 * 1024 Then
    ' prompt the user what to do with file > 1 MB
    ' ...
End If

Getting and setting file date/time 

To retrieve the last modification date/time of a remote file, use GetFileDateTime method. To set it, use SetFileDateTime method.

Getting remote time

string localPath = @"C:\MyData\file.txt";
string remotePath = "/MyData/file.txt";
DateTime remoteTime = ftp.GetFileDateTime(remotePath);

// download file and set local time appropriately
ftp.GetFile(remotePath, localPath);
File.SetLastWriteTime(localPath, remoteTime);

Dim localPath = "C:\MyData\file.txt"
Dim remotePath = "/MyData/file.txt"
Dim remoteTime = ftp.GetFileDateTime(remotePath)

' download file and set local time appropriately
ftp.GetFile(remotePath, localPath)
File.SetLastWriteTime(localPath, remoteTime)

Setting remote time

string localPath = @"C:\MyData\file.txt";
string remotePath = "/MyData/file.txt";
DateTime localTime = new FileInfo(localPath).LastWriteTime;

// upload file and set remote time appropriately
ftp.PutFile(localPath, remotePath);
ftp.SetFileDateTime(remotePath, localTime);

Dim localPath = "C:\MyData\file.txt"
Dim remotePath = "/MyData/file.txt"
Dim localTime = New FileInfo(localPath).LastWriteTime

' upload file and set remote time appropriately
ftp.PutFile(localPath, remotePath)
ftp.SetFileDateTime(remotePath, localTime)

Depending on the remote FTP server software, the returned time would be in local or universal time zone. See an article about treating time zones in FTP GetFileDateTime method.

Getting file checksums 

To make it possible to verify the file has been transferred correctly, some FTP servers support checksum calculation, making it possible to compare checksums of local and remote files. 

string localPath = @"C:\MyData\file.txt";
string remotePath = "/MyData/file.txt";

// upload the file
ftp.PutFile(localPath, remotePath);

// get checksum algorithms supported by the server
ChecksumAlgorithm[] checksumAlgorithms = ftp.GetSupportedChecksumAlgorithms();

if (checksumAlgorithms.Length > 0)
{
    // compute checksums

    // choose the first checksum type
    ChecksumAlgorithm checksumAlgorithm = checksumAlgorithms[0];

    // retrieve checksum from the server
    string remoteChecksum = ftp.GetChecksum(remotePath, checksumAlgorithm);

    // calculate local checksum
    string localChecksum = LocalItem.GetChecksum(localPath, checksumAlgorithm);

    // compare checksums
    if (remoteChecksum == localChecksum)
        Console.WriteLine("File uploaded and verified.");
    else
        Console.WriteLine("File uploaded with errors.");
}
else
{
    Console.WriteLine("Server does not support checksums.");
}

Dim localPath = "C:\MyData\file.txt"
Dim remotePath = "/MyData/file.txt"

' upload the file
ftp.PutFile(localPath, remotePath)

' get checksum types supported by the server
Dim checksumAlgorithms() As ChecksumAlgorithm = ftp.GetSupportedChecksumAlgorithms()

If checksumAlgorithms.Length > 0 Then
    ' compute checksums

    ' choose the first checksum type
    Dim checksumAlgorithm = checksumAlgorithms(0)

    ' retrieve checksum from the server
    Dim remoteChecksum As String = ftp.GetChecksum(remotePath, checksumAlgorithm)

    ' calculate local checksum
    Dim localChecksum As String = LocalItem.GetChecksum(localPath, checksumAlgorithm)

    ' compare checksums
    If remoteChecksum = localChecksum Then
        Console.WriteLine("File uploaded and verified.")
    Else
        Console.WriteLine("File uploaded with errors.")
    End If
Else
    Console.WriteLine("Server does not support checksums.")
End If
TLS/SSL has reliable integrity checking built-in, which mostly makes it unnecessary to verify transferred files using checksums for SSL-enabled FTP sessions.

Partial file transfer (appending) 

GetFile and PutFile methods make it possible to download or upload a part of a file. This is used for appending data to an existing file or to resume broken transfers.

To upload a file part, use three additional parameters: local offset, remote offset and number of bytes you want to transfer. To download a file part, only two parameters are available: local offset and remote offset. Local offset is not required for stream-based methods - data is read/written from/to the current stream position. 

string localPath = @"C:\MyData\part7.txt";
string remotePath = "/MyData/summary.txt";
string header = string.Format("<FILE>: {0}\n", localPath);
long localFileLength = new FileInfo(localPath).Length;
long remoteFileLength = ftp.GetFileLength(remotePath);

// append header for part7.txt to summary.txt from memory
MemoryStream ms = new MemoryStream(Encoding.UTF8.GetBytes(header));
ftp.PutFile(ms, remotePath,
    remoteFileLength,  // remote offset
    ms.Length);  // number of bytes to upload

// update remote length
remoteFileLength += ms.Length;

// append data from part7.txt to summary.txt
ftp.PutFile(localPath, remotePath,
    0,  // local offset
    remoteFileLength,  // remote offset
    localFileLength);  // number of bytes to upload

Dim localPath = "C:\MyData\part7.txt"
Dim remotePath = "/MyData/summary.txt"
Dim header = String.Format("<FILE>: {0}" & vbLf, localPath)
Dim localFileLength = New FileInfo(localPath).Length
Dim remoteFileLength = ftp.GetFileLength(remotePath)

' append header for part7.txt to summary.txt from memory
Dim ms = New MemoryStream(Encoding.UTF8.GetBytes(header))
ftp.PutFile(ms, remotePath,
    remoteFileLength, ms.Length)
'   remote offset, number of bytes to upload

' update remote length
remoteFileLength += ms.Length

' append data from part7.txt to summary.txt
ftp.PutFile(localPath, remotePath,
    0, remoteFileLength, localFileLength)
'   local offset, remote offset, number of bytes to upload
Although there is a dedicated AppendFile method to append data to a file at the server, it uses FTP 'APPE' command that is only supported by some servers. Using PutFile method might be a better choice.

Partial file transfer (resuming) 

Tip: If you need to simply resume a failed file transfer, use Upload and Download methods.

But if you prefer to have more control over the process, partial file transfer support in GetFile and PutFile methods might be useful. To resume a file transfer, determine the length of the local file and the length of the remote file. Then transfer the missing part.

Resuming upload:

string localPath = @"C:\MyData\file.txt";
string remotePath = "/MyData/file.txt";
long localFileLength = new FileInfo(localPath).Length;
long remoteFileLength = ftp.GetFileLength(remotePath);
long remains;

// resume failed upload
remains = localFileLength - remoteFileLength;
if (remains > 0)
{
    ftp.PutFile(localPath, remotePath,
        remoteFileLength,  // local offset
        remoteFileLength,  // remote offset
        remains);  // number of bytes to upload
}

Dim localPath = "C:\MyData\file.txt"
Dim remotePath = "/MyData/file.txt"
Dim localFileLength = New FileInfo(localPath).Length
Dim remoteFileLength = ftp.GetFileLength(remotePath)
Dim remains As Long

' resume failed upload
remains = localFileLength - remoteFileLength
If remains > 0 Then
    ftp.PutFile(localPath, remotePath,
        remoteFileLength, remoteFileLength, remains)
    '   local offset, remote offset, number of bytes to upload
End If

Resuming download:

string localPath = @"C:\MyData\file.txt";
string remotePath = "/MyData/file.txt";
long localFileLength = new FileInfo(localPath).Length;
long remoteFileLength = ftp.GetFileLength(remotePath);

// resume failed download
if (remoteFileLength > localFileLength)
{
    ftp.GetFile(remotePath, localPath,
        localFileLength,  // remote offset
        localFileLength); // local offset
}

Dim localPath = "C:\MyData\file.txt"
Dim remotePath = "/MyData/file.txt"
Dim localFileLength = New FileInfo(localPath).Length
Dim remoteFileLength = ftp.GetFileLength(remotePath)

' resume failed download
If remoteFileLength > localFileLength Then
    ftp.GetFile(remotePath, localPath,
        localFileLength, localFileLength)
    '   remote offset, local offset
End If

Back to feature list...