Class SftpClient

Namespace

Tmds.Ssh

Assembly

Tmds.Ssh.dll

Provides a client for performing filesystem operations on SSH servers using SFTP (SSH File Transfer Protocol).

public sealed class SftpClient : ISftpDirectory, IDisposable

Inheritance

object

SftpClient

Implements

ISftpDirectory

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

SftpDirectoryExtensions.CreateDirectoryAsync(ISftpDirectory, string, CancellationToken)

SftpDirectoryExtensions.CreateNewDirectoryAsync(ISftpDirectory, string, CancellationToken)

SftpDirectoryExtensions.CreateNewFileAsync(ISftpDirectory, string, FileAccess, CancellationToken)

SftpDirectoryExtensions.DeleteDirectoryAsync(ISftpDirectory, string, CancellationToken)

SftpDirectoryExtensions.DownloadDirectoryEntriesAsync(ISftpDirectory, string, string, CancellationToken)

SftpDirectoryExtensions.DownloadFileAsync(ISftpDirectory, string, string, CancellationToken)

SftpDirectoryExtensions.GetAttributesAsync(ISftpDirectory, string, bool, CancellationToken)

SftpDirectoryExtensions.GetAttributesAsync(ISftpDirectory, string, CancellationToken)

SftpDirectoryExtensions.GetDirectoryEntriesAsync(ISftpDirectory, string, EnumerationOptions?)

SftpDirectoryExtensions.OpenFileAsync(ISftpDirectory, string, FileAccess, CancellationToken)

SftpDirectoryExtensions.OpenOrCreateFileAsync(ISftpDirectory, string, FileAccess, CancellationToken)

SftpDirectoryExtensions.UploadDirectoryEntriesAsync(ISftpDirectory, string, string, CancellationToken)

SftpDirectoryExtensions.UploadFileAsync(ISftpDirectory, Stream, string, CancellationToken)

SftpDirectoryExtensions.UploadFileAsync(ISftpDirectory, string, string, CancellationToken)

Examples

The following example uploads and downloads files. It uses default credentials for the current user and authenticates the server against the known_hosts files:

using Tmds.Ssh;

using var sftpClient = new SftpClient("user@example.com");
await sftpClient.UploadFileAsync("/local/path/file.txt", "/remote/path/file.txt");
await sftpClient.DownloadFileAsync("/remote/path/file.txt", "/local/path/downloaded.txt");

Remarks

When the application already has an SSH connection for an Tmds.Ssh.SftpClient.SshClient, that connection can also be used for the SftpClient:

• Call OpenSftpClientAsync(CancellationToken) to create an SftpClient from an existing Tmds.Ssh.SftpClient.SshClient.
• Or, use the constructor that accepts an existing Tmds.Ssh.SftpClient.SshClient.

For SFTP-only scenarios, the SftpClient can be created so it owns and manages the SSH connection:

• Use the constructor that accepts a destination string that uses SSH credentials for the current user for authentication and OpenSSH known_hosts for host key validation.
• Use the constructor that accepts SshClientSettings to change the default settings.
• Use the constructor that accepts SshConfigSettings to use configuration from OpenSSH config files.

By default, the SFTP connection is established automatically when the first operation is performed. When the SftpClient owns the SSH connection, you can explicitly call ConnectAsync(CancellationToken) to establish the connection before performing operations.

Once the connection is established, the SftpClient methods can be used to perform various filesystem operations.

Constructors

SftpClient(string, ILoggerFactory?, SftpClientOptions?)

Creates an SftpClient for the specified destination.

public SftpClient(string destination, ILoggerFactory? loggerFactory = null, SftpClientOptions? options = null)

Parameters

destination string

The destination in format [user@]host[:port].

loggerFactory ILoggerFactory

Optional logger factory.

options SftpClientOptions

SftpClientOptions for the SftpClient.

SftpClient(string, SshConfigSettings, ILoggerFactory?, SftpClientOptions?)

Creates an SftpClient for the specified destination with SSH config settings.

public SftpClient(string destination, SshConfigSettings configSettings, ILoggerFactory? loggerFactory = null, SftpClientOptions? options = null)

Parameters

destination string

The destination in format [user@]host[:port].

configSettings SshConfigSettings

SSH configuration settings.

loggerFactory ILoggerFactory

Optional logger factory.

options SftpClientOptions

SftpClientOptions for the SftpClient.

SftpClient(SshClient, SftpClientOptions?)

Creates an SftpClient from an existing Tmds.Ssh.SftpClient.SshClient.

public SftpClient(SshClient client, SftpClientOptions? options = null)

Parameters

client SshClient

The Tmds.Ssh.SftpClient.SshClient to use for connections.

options SftpClientOptions

SftpClientOptions for the SftpClient.

SftpClient(SshClientSettings, ILoggerFactory?, SftpClientOptions?)

Creates an SftpClient with the specified settings.

public SftpClient(SshClientSettings settings, ILoggerFactory? loggerFactory = null, SftpClientOptions? options = null)

Parameters

settings SshClientSettings

The SshClientSettings.

loggerFactory ILoggerFactory

Optional logger factory.

options SftpClientOptions

SftpClientOptions for the SftpClient.

Fields

DefaultCreateDirectoryPermissions

Default permissions for creating directories (rwxrwxrwx).

public const UnixFilePermissions DefaultCreateDirectoryPermissions = OtherExecute | OtherWrite | OtherRead | GroupExecute | GroupWrite | GroupRead | UserExecute | UserWrite | UserRead

Field Value

UnixFilePermissions

Remarks

The server will apply a umask which filters these permissions further.

DefaultCreateFilePermissions

Default permissions for creating files (rw-rw-rw-).

public const UnixFilePermissions DefaultCreateFilePermissions = OtherWrite | OtherRead | GroupWrite | GroupRead | UserWrite | UserRead

Field Value

UnixFilePermissions

Remarks

The server will apply a umask which filters these permissions further.

Properties

WorkingDirectory

Gets the working directory for the SftpClient.

public SftpDirectory WorkingDirectory { get; }

Property Value

SftpDirectory

Remarks

This property can only be used once the client is connected.

Methods

ConnectAsync(CancellationToken)

Connect to the server.

public Task ConnectAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Token to cancel the operation.

Returns

Task

Remarks

This method can only be used when the SftpClient was constructed using a constructor that accepts a destination or SshClientSettings.

CopyFileAsync(string, string, bool, CancellationToken)

Copies a file.

public ValueTask CopyFileAsync(string sourcePath, string destinationPath, bool overwrite = false, CancellationToken cancellationToken = default)

Parameters

sourcePath string

The source file path.

destinationPath string

The destination file path.

overwrite bool

Whether to overwrite an existing file.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask

CreateDirectoryAsync(string, bool, UnixFilePermissions, CancellationToken)

Creates a directory. This does not fail when the directory exists (or is a link to a directory).

public ValueTask CreateDirectoryAsync(string path, bool createParents = false, UnixFilePermissions permissions = UnixFilePermissions.OtherExecute | UnixFilePermissions.OtherWrite | UnixFilePermissions.OtherRead | UnixFilePermissions.GroupExecute | UnixFilePermissions.GroupWrite | UnixFilePermissions.GroupRead | UnixFilePermissions.UserExecute | UnixFilePermissions.UserWrite | UnixFilePermissions.UserRead, CancellationToken cancellationToken = default)

Parameters

path string

The directory path.

createParents bool

Whether to create parent directories.

permissions UnixFilePermissions

UnixFilePermissions used when a new directory is created.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask

CreateNewDirectoryAsync(string, bool, UnixFilePermissions, CancellationToken)

Creates a new directory. This fails when the directory already exists.

public ValueTask CreateNewDirectoryAsync(string path, bool createParents = false, UnixFilePermissions permissions = UnixFilePermissions.OtherExecute | UnixFilePermissions.OtherWrite | UnixFilePermissions.OtherRead | UnixFilePermissions.GroupExecute | UnixFilePermissions.GroupWrite | UnixFilePermissions.GroupRead | UnixFilePermissions.UserExecute | UnixFilePermissions.UserWrite | UnixFilePermissions.UserRead, CancellationToken cancellationToken = default)

Parameters

path string

The directory path.

createParents bool

Whether to create parent directories.

permissions UnixFilePermissions

UnixFilePermissions for the new directory.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask

CreateNewFileAsync(string, FileAccess, FileOpenOptions?, CancellationToken)

Creates a new file. Fails if it already exists.

public ValueTask<SftpFile> CreateNewFileAsync(string path, FileAccess access, FileOpenOptions? options, CancellationToken cancellationToken = default)

Parameters

path string

The file path.

access FileAccess

The FileAccess mode.

options FileOpenOptions

FileOpenOptions for creating the file.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask<SftpFile>

SftpFile instance for the opened file.

CreateSymbolicLinkAsync(string, string, CancellationToken)

Creates a symbolic link.

public ValueTask CreateSymbolicLinkAsync(string linkPath, string targetPath, CancellationToken cancellationToken = default)

Parameters

linkPath string

The symbolic link path to create.

targetPath string

The target path the link points to.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask

DeleteDirectoryAsync(string, bool, CancellationToken)

Deletes a directory. This does not fail when the directory does not exist.

public ValueTask DeleteDirectoryAsync(string path, bool recursive = false, CancellationToken cancellationToken = default)

Parameters

path string

The directory path.

recursive bool

Whether to delete directories recursively.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask

DeleteFileAsync(string, CancellationToken)

Deletes a file. This does not fail when the file does not exist.

public ValueTask DeleteFileAsync(string path, CancellationToken cancellationToken = default)

Parameters

path string

The file path.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask

Dispose()

Closes the connection and releases resources.

public void Dispose()

DownloadDirectoryEntriesAsync(string, string, DownloadEntriesOptions?, CancellationToken)

Downloads directory entries.

public ValueTask DownloadDirectoryEntriesAsync(string remoteDirPath, string localDirPath, DownloadEntriesOptions? options, CancellationToken cancellationToken = default)

Parameters

remoteDirPath string

The remote directory path.

localDirPath string

The local directory path.

options DownloadEntriesOptions

DownloadEntriesOptions for the download operation.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask

DownloadFileAsync(string, Stream, CancellationToken)

Downloads a file to a Stream.

public ValueTask DownloadFileAsync(string remoteFilePath, Stream destination, CancellationToken cancellationToken = default)

Parameters

remoteFilePath string

The remote file path.

destination Stream

The destination Stream.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask

DownloadFileAsync(string, string, bool, CancellationToken)

Downloads a file.

public ValueTask DownloadFileAsync(string remoteFilePath, string localFilePath, bool overwrite = false, CancellationToken cancellationToken = default)

Parameters

remoteFilePath string

The remote file path.

localFilePath string

The local file path.

overwrite bool

Whether to overwrite an existing file.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask

GetAttributesAsync(string, bool, string[]?, CancellationToken)

Gets file or directory attributes.

public ValueTask<FileEntryAttributes?> GetAttributesAsync(string path, bool followLinks, string[]? filter, CancellationToken cancellationToken = default)

Parameters

path string

The file or directory path.

followLinks bool

Whether to follow symbolic links.

filter string[]

Extended attributes to include. Set to null to include all.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask<FileEntryAttributes>

The FileEntryAttributes, or null if not found.

GetDirectory(string)

public SftpDirectory GetDirectory(string path)

Parameters

path string

Returns

SftpDirectory

GetDirectoryEntriesAsync<T>(string, SftpFileEntryTransform<T>, EnumerationOptions?)

Enumerates directory entries asynchronously.

public IAsyncEnumerable<T> GetDirectoryEntriesAsync<T>(string path, SftpFileEntryTransform<T> transform, EnumerationOptions? options = null)

Parameters

path string

The directory path to enumerate.

transform SftpFileEntryTransform<T>

SftpFileEntryTransform<T> function for each entry.

options EnumerationOptions

EnumerationOptions for enumeration.

Returns

IAsyncEnumerable<T>

An async enumerable of transformed entries.

Type Parameters

T

Result type to transform entries to.

GetLinkTargetAsync(string, CancellationToken)

Gets the target of a symbolic link.

public ValueTask<string> GetLinkTargetAsync(string linkPath, CancellationToken cancellationToken = default)

Parameters

linkPath string

The symbolic link path.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask<string>

The target path.

GetRealPathAsync(string, CancellationToken)

Resolves a path to its canonical absolute path.

public ValueTask<string> GetRealPathAsync(string path, CancellationToken cancellationToken = default)

Parameters

path string

The path to resolve.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask<string>

The canonical absolute path.

OpenFileAsync(string, FileAccess, FileOpenOptions?, CancellationToken)

Opens an existing file.

public ValueTask<SftpFile?> OpenFileAsync(string path, FileAccess access, FileOpenOptions? options, CancellationToken cancellationToken = default)

Parameters

path string

The file path.

access FileAccess

The FileAccess mode.

options FileOpenOptions

FileOpenOptions for opening the file.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask<SftpFile>

SftpFile instance for the opened file, or null if it doesn't exist.

OpenOrCreateFileAsync(string, FileAccess, FileOpenOptions?, CancellationToken)

Opens an existing file or creates it when it does not yet exist.

public ValueTask<SftpFile> OpenOrCreateFileAsync(string path, FileAccess access, FileOpenOptions? options, CancellationToken cancellationToken = default)

Parameters

path string

The file path.

access FileAccess

The FileAccess mode.

options FileOpenOptions

FileOpenOptions for opening the file.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask<SftpFile>

SftpFile instance for the opened file.

RenameAsync(string, string, CancellationToken)

Renames or moves a file or directory.

public ValueTask RenameAsync(string oldPath, string newPath, CancellationToken cancellationToken = default)

Parameters

oldPath string

The current path.

newPath string

The new path.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask

SetAttributesAsync(string, UnixFilePermissions?, (DateTimeOffset LastAccess, DateTimeOffset LastWrite)?, long?, (int Uid, int Gid)?, IEnumerable<KeyValuePair<string, Memory<byte>>>?, CancellationToken)

Sets file or directory attributes.

public ValueTask SetAttributesAsync(string path, UnixFilePermissions? permissions = null, (DateTimeOffset LastAccess, DateTimeOffset LastWrite)? times = null, long? length = null, (int Uid, int Gid)? ids = null, IEnumerable<KeyValuePair<string, Memory<byte>>>? extendedAttributes = null, CancellationToken cancellationToken = default)

Parameters

path string

The file or directory path.

permissions UnixFilePermissions?

UnixFilePermissions to set.

times (DateTimeOffset LastAccess, DateTimeOffset LastWrite)?

Access and modification times to set.

length long?

File length to set (truncates or extends).

ids (int Uid, int Gid)?

User and group IDs to set.

extendedAttributes IEnumerable<KeyValuePair<string, Memory<byte>>>

Extended attributes to set.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask

UploadDirectoryEntriesAsync(string, string, UploadEntriesOptions?, CancellationToken)

Uploads directory entries.

public ValueTask UploadDirectoryEntriesAsync(string localDirPath, string remoteDirPath, UploadEntriesOptions? options, CancellationToken cancellationToken = default)

Parameters

localDirPath string

The local directory path.

remoteDirPath string

The remote directory path.

options UploadEntriesOptions

UploadEntriesOptions for the upload operation.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask

UploadFileAsync(Stream, string, bool, UnixFilePermissions, CancellationToken)

Uploads a file from a Stream.

public ValueTask UploadFileAsync(Stream source, string remoteFilePath, bool overwrite = false, UnixFilePermissions createPermissions = UnixFilePermissions.OtherWrite | UnixFilePermissions.OtherRead | UnixFilePermissions.GroupWrite | UnixFilePermissions.GroupRead | UnixFilePermissions.UserWrite | UnixFilePermissions.UserRead, CancellationToken cancellationToken = default)

Parameters

source Stream

The source Stream.

remoteFilePath string

The remote file path.

overwrite bool

Whether to overwrite an existing file.

createPermissions UnixFilePermissions

UnixFilePermissions when a new file is created.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask

UploadFileAsync(string, string, bool, UnixFilePermissions?, CancellationToken)

Uploads a file.

public ValueTask UploadFileAsync(string localFilePath, string remoteFilePath, bool overwrite = false, UnixFilePermissions? createPermissions = null, CancellationToken cancellationToken = default)

Parameters

localFilePath string

The local file path.

remoteFilePath string

The remote file path.

overwrite bool

Whether to overwrite an existing file.

createPermissions UnixFilePermissions?

UnixFilePermissions when a new file is created.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

ValueTask