Skip to content

v40 Migration Guide

Jump to bottom
Robin Rodricks edited this page Dec 25, 2022 · 50 revisions

This guide helps you migrate from v39 and older releases to v40+ and newer releases.

Rationale

FluentFTP has had a long and colorful history of development. While we have always strived to rapidly add features and release them often, we have not really had the time to design our API surface according to well-defined principles.

In this release our goals were to:

  1. Cleanup the API surface
  2. Improve the configuration methodology
  3. Improve the logging methodology
  4. Fix technical debt by dropping old frameworks
  5. Modernize the codebase
  6. Improve code organization

Instead of making multiple releases with constant breaking API changes, I decided to roll this into a single large release. v40 is the culmination of all of the above goals.

The full discussion can be found here.

Overview

The following is a brief overview on the major changes in v40+.

The full release notes can be found here.

1. Select a client

The FTP client has now been split into 2 main classes, FtpClient and AsyncFtpClient. You will have to select one client based on the type of API you need, and stick with that type of API for the lifetime of that class. It is no longer possible to mix sync and async API calls.

This table lists out all the clients available, including proxy clients:

Synchronous Clients Asynchronous Clients
FtpClient AsyncFtpClient
FtpClientHttp11Proxy AsyncFtpClientHttp11Proxy
FtpClientProxy AsyncFtpClientProxy
FtpClientSocks4aProxy AsyncFtpClientSocks4aProxy
FtpClientSocks4Proxy AsyncFtpClientSocks4Proxy
FtpClientSocks5Proxy AsyncFtpClientSocks5Proxy
FtpClientUserAtHostProxy AsyncFtpClientUserAtHostProxy
FtpClientBlueCoatProxy AsyncFtpClientBlueCoatProxy

2. Migrate your constructors

New

The following constructors have been introduced:

  • Synchronous version:

    • FtpClient()
    • FtpClient(string host, int port = 0, FtpConfig config = null, ILogger logger = null)
    • FtpClient(string host, string user, string pass, int port = 0, FtpConfig config = null, ILogger logger = null)
    • FtpClient(string host, NetworkCredential credentials, int port = 0, FtpConfig config = null, ILogger logger = null)

  • Async version:

    • AsyncFtpClient()
    • AsyncFtpClient(string host, int port = 0, FtpConfig config = null, ILogger logger = null)
    • AsyncFtpClient(string host, string user, string pass, int port = 0, FtpConfig config = null, ILogger logger = null)
    • AsyncFtpClient(string host, NetworkCredential credentials, int port = 0, FtpConfig config = null, ILogger logger = null)

  • You can always construct the client and then later set these properties:

    • client.Host
    • client.Port
    • client.Credentials
    • client.Config
    • client.Logger

Removed

The following constructors have been deleted:

  • FtpClient()
  • FtpClient(string host)
  • FtpClient(string host, NetworkCredential credentials)
  • FtpClient(string host, int port, NetworkCredential credentials)
  • FtpClient(string host, string user, string pass)
  • FtpClient(string host, string user, string pass, string account)
  • FtpClient(string host, int port, string user, string pass)
  • FtpClient(string host, int port, string user, string pass, string account)
  • FtpClient(Uri host)
  • FtpClient(Uri host, NetworkCredential credentials)
  • FtpClient(Uri host, string user, string pass)
  • FtpClient(Uri host, string user, string pass, string account)
  • FtpClient(Uri host, int port, string user, string pass)
  • FtpClient(Uri host, int port, string user, string pass, string account)

3. Migrate your interfaces

The interface IFtpClient has now been split into 2 interfaces: IFtpClient and IAsyncFtpClient.

If you have programmed against interfaces, you will have to select one interface based on the type of API you are using.

4. Migrate your Async methods

All async methods are now available inside AsyncFtpClient and they have the Async suffix removed.

The full list of changes are given below:

Old method names New method names
ConnectAsync() Connect()
AutoDetectAsync() AutoDetect()
AutoConnectAsync() AutoConnect()
DisconnectAsync() Disconnect()
ExecuteAsync() Execute()
GetReplyAsync() GetReply()
DeleteFileAsync() DeleteFile()
DeleteDirectoryAsync() DeleteDirectory()
DirectoryExistsAsync() DirectoryExists()
FileExistsAsync() FileExists()
CreateDirectoryAsync() CreateDirectory()
RenameAsync() Rename()
MoveFileAsync() MoveFile()
MoveDirectoryAsync() MoveDirectory()
SetFilePermissionsAsync() SetFilePermissions()
ChmodAsync() Chmod()
GetFilePermissionsAsync() GetFilePermissions()
GetChmodAsync() GetChmod()
SetWorkingDirectoryAsync() SetWorkingDirectory()
GetWorkingDirectoryAsync() GetWorkingDirectory()
GetFileSizeAsync() GetFileSize()
GetModifiedTimeAsync() GetModifiedTime()
SetModifiedTimeAsync() SetModifiedTime()
GetObjectInfoAsync() GetObjectInfo()
GetListingAsync() GetListing()
GetNameListingAsync() GetNameListing()
OpenReadAsync() OpenRead()
OpenWriteAsync() OpenWrite()
OpenAppendAsync() OpenAppend()
UploadFilesAsync() UploadFiles()
DownloadFilesAsync() DownloadFiles()
UploadFileAsync() UploadFile()
UploadStreamAsync() UploadStream()
UploadBytesAsync() UploadBytes()
DownloadFileAsync() DownloadFile()
DownloadStreamAsync() DownloadStream()
DownloadBytesAsync() DownloadBytes()
DownloadDirectoryAsync() DownloadDirectory()
UploadDirectoryAsync() UploadDirectory()
GetChecksumAsync() GetChecksum()
CompareFileAsync() CompareFile()

5. Change your configuration

All of the configuration settings have now been moved into the Config property within the FtpClient objects. You can specify the config in the constructor (optional) and/or you can change individual properties at any time. You can also reassign the Config property on the fly at any time.

The full list of changes are given below:

Old property names New property names
client.QuickTransferLimit (removed)
client.MaximumDereferenceCount (removed)
client.EnableThreadSafeDataConnections (removed)
client.PlainTextEncryption (removed)
FtpTrace.LogFunctions (removed)
FtpTrace.LogIP client.Config.LogHost
FtpTrace.LogUserName client.Config.LogUserName
FtpTrace.LogPassword client.Config.LogPassword
FtpTrace.LogToConsole client.Config.LogToConsole
client.OnLogEvent client.LegacyLogger
client.BulkListing client.Config.BulkListing
client.BulkListingLength client.Config.BulkListingLength
client.ActivePorts client.Config.ActivePorts
client.ClientCertificates client.Config.ClientCertificates
client.ConnectTimeout client.Config.ConnectTimeout
client.DataConnectionConnectTimeout client.Config.DataConnectionConnectTimeout
client.DataConnectionEncryption client.Config.DataConnectionEncryption
client.DataConnectionReadTimeout client.Config.DataConnectionReadTimeout
client.DataConnectionType client.Config.DataConnectionType
client.DisconnectWithQuit client.Config.DisconnectWithQuit
client.DisconnectWithShutdown (removed)
client.DownloadDataType client.Config.DownloadDataType
client.DownloadDirectoryDeleteExcluded client.Config.DownloadDirectoryDeleteExcluded
client.DownloadRateLimit client.Config.DownloadRateLimit
client.DownloadZeroByteFiles client.Config.DownloadZeroByteFiles
client.EncryptionMode client.Config.EncryptionMode
client.FXPDataType client.Config.FXPDataType
client.FXPProgressInterval client.Config.FXPProgressInterval
client.InternetProtocolVersions client.Config.InternetProtocolVersions
client.ListingCulture client.Config.ListingCulture
client.ListingCustomParser client.Config.ListingCustomParser
client.ListingDataType client.Config.ListingDataType
client.ListingParser client.Config.ListingParser
client.LocalFileBufferSize client.Config.LocalFileBufferSize
client.LocalTimeZone client.Config.LocalTimeZone
client.NoopInterval client.Config.NoopInterval
client.PassiveBlockedPorts client.Config.PassiveBlockedPorts
client.PassiveMaxAttempts client.Config.PassiveMaxAttempts
client.PlainTextEncryption client.Config.PlainTextEncryption
client.ReadTimeout client.Config.ReadTimeout
client.RetryAttempts client.Config.RetryAttempts
client.SendHost client.Config.SendHost
client.SendHostDomain client.Config.SendHostDomain
client.SocketKeepAlive client.Config.SocketKeepAlive
client.SocketLocalIp client.Config.SocketLocalIp
client.SocketPollInterval client.Config.SocketPollInterval
client.SslBuffering client.Config.SslBuffering
client.SslProtocols client.Config.SslProtocols
client.StaleDataCheck client.Config.StaleDataCheck
client.TimeConversion client.Config.TimeConversion
client.TimeZone client.Config.TimeZone
client.TransferChunkSize client.Config.TransferChunkSize
client.UploadDataType client.Config.UploadDataType
client.UploadDirectoryDeleteExcluded client.Config.UploadDirectoryDeleteExcluded
client.UploadRateLimit client.Config.UploadRateLimit

6. Use the new Logging system

New

A new logging system has been introduced, wherein each FtpClient can now have its own logger assigned which can directly utilize any logger that implements a custom IFtpLogger interface. A sister package called FluentFTP.Logging helps you integrate this with the industry-standard MELA ILogger interface.

  • client.Logger allows you to specify any IFtpLogger, which can be linked to the industry-standard MELA logging system.
  • You can also pass an ILogger instance in any client constructor
  • You can reassign the client.Logger at any time
  • You can set client.Logger to null to disable logging

Example code

using FluentFTP;          // from NuGet package FluentFTP
using FluentFTP.Logging;  // from NuGet package FluentFTP.Logging

var client = new FtpClient();
client.Logger = new FtpLogAdapter(new Log4NetLogger())

Renamed

The older console logger has been preserved but renamed. It provides the in-built ability to log to console. If you run FluentFTP in debug mode by building from source, it will also log to the debug console.

  • FtpTrace.LogToConsole renamed to client.Config.LogToConsole

An older logging callback system has been preserved but renamed. It provides an easy way to consume FTP logging events if you don't want to use the new ILogger system.

  • client.OnLogEvent renamed to client.LegacyLogger

The older logging settings have been preserved:

  • FtpTrace.LogIP renamed to client.Config.LogHost
  • FtpTrace.LogUserName renamed to client.Config.LogUserName
  • FtpTrace.LogPassword renamed to client.Config.LogPassword

Removed

The older logging system has been removed, wherein you had a static class FtpTrace responsible for logging.

  • FtpTrace class
  • FtpTrace.LogFunctions because logging function names is always enabled

Examples

Connection

Features

Troubleshooting

Testing

Contributing

API

Clone this wiki locally