v40 Migration Guide

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+.

• FTP client classes split (FtpClient and AsyncFtpClient)
• Async API renamed
• Constructors refactored
• Interfaces refactored
• Configuration system modernized
• Logging modernized
• Dropped support for .NET Standard 1.2, 1.4 and .NET 2.0, 3.5, 4.0 and 4.5
• Added support for .NET 4.6.2 and 4.7.2
• Added a Nuget dependency on Microsoft.Extensions.Logging.Abstractions v2.1.0

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)
client.LogToConsole	client.Config.LogToConsole
client.InternetProtocolVersions	client.Config.InternetProtocolVersions
client.SocketPollInterval	client.Config.SocketPollInterval
client.StaleDataCheck	client.Config.StaleDataCheck
client.NoopInterval	client.Config.NoopInterval
client.DataConnectionType	client.Config.DataConnectionType
client.DisconnectWithQuit	client.Config.DisconnectWithQuit
client.DisconnectWithShutdown	client.Config.DisconnectWithShutdown
client.ConnectTimeout	client.Config.ConnectTimeout
client.ReadTimeout	client.Config.ReadTimeout
client.DataConnectionConnectTimeout	client.Config.DataConnectionConnectTimeout
client.DataConnectionReadTimeout	client.Config.DataConnectionReadTimeout
client.SocketKeepAlive	client.Config.SocketKeepAlive
client.EncryptionMode	client.Config.EncryptionMode
client.DataConnectionEncryption	client.Config.DataConnectionEncryption
client.SslProtocols	client.Config.SslProtocols
client.SslBuffering	client.Config.SslBuffering
client.ClientCertificates	client.Config.ClientCertificates
client.TransferChunkSize	client.Config.TransferChunkSize
client.LocalFileBufferSize	client.Config.LocalFileBufferSize
client.ListingDataType	client.Config.ListingDataType
client.ListingParser	client.Config.ListingParser
client.ListingCulture	client.Config.ListingCulture
client.ListingCustomParser	client.Config.ListingCustomParser
client.TimeZone	client.Config.TimeZone
client.TimeConversion	client.Config.TimeConversion
client.RetryAttempts	client.Config.RetryAttempts
client.UploadRateLimit	client.Config.UploadRateLimit
client.DownloadZeroByteFiles	client.Config.DownloadZeroByteFiles
client.DownloadRateLimit	client.Config.DownloadRateLimit
client.DownloadDataType	client.Config.DownloadDataType
client.UploadDataType	client.Config.UploadDataType
client.ActivePorts	client.Config.ActivePorts
client.PassiveBlockedPorts	client.Config.PassiveBlockedPorts
client.PassiveMaxAttempts	client.Config.PassiveMaxAttempts
client.SendHost	client.Config.SendHost
client.SendHostDomain	client.Config.SendHostDomain
client.FXPDataType	client.Config.FXPDataType
client.FXPProgressInterval	client.Config.FXPProgressInterval
client.UploadDirectoryDeleteExcluded	client.Config.UploadDirectoryDeleteExcluded
client.DownloadDirectoryDeleteExcluded	client.Config.DownloadDirectoryDeleteExcluded
client.SocketLocalIp	client.Config.SocketLocalIp
client.LocalTimeZone	client.Config.LocalTimeZone
client.PlainTextEncryption	client.Config.PlainTextEncryption
client.OnLogEvent	client.LegacyLogger

6. Use the new Logging system

New

A new property client.Config.LogToConsole now 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.

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 the industry-standard ILogger interface.

• client.Logger allows you to specify any ILogger using 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

Renamed

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.

• Old name: client.OnLogEvent
• New name: client.LegacyLogger

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
• FtpTrace.LogIP because sensitive data is always masked
• FtpTrace.LogUserName because sensitive data is always masked
• FtpTrace.LogPassword because sensitive data is always masked