Ctrlk
RoadmapFrends
For the complete documentation index, see llms.txt. This page is also available as Markdown.

DownloadFiles

Downloads file through SFTP connection.

Task version: 4.1.0

Required Frends version: 5.5+

Required .NET version: 6.0

Compatible Agents: Crossplatform

Source code: https://github.com/FrendsPlatform/Frends.SFTP/tree/main/Frends.SFTP.DownloadFiles

Task Parameters

Name
Description

Directory : String

Directory on the server.

Default: / Example: /upload/

FileName : String

File name or file mask of the files to be fetched.

Default: - Example: test.txt

IncludeSubdirectories : Boolean

Determines if subdirectories should be included when searching source files.

Depending on how many subdirectories there are, this operation can be extremely expensive.

Default: False Example: true

Action : SourceAction

What to do if source file is not found. Error = alarm and fail,

Info = alarm info and quit with success status, Ignore = quit

with success status.

Possible values:

  • Error: What to do if source file is not found. Error = alarm and fail,

Info = alarm info and quit with success status, Ignore = quit

with success status.

  • Info: What to do if source file is not found. Error = alarm and fail,

Info = alarm info and quit with success status, Ignore = quit

with success status.

  • Ignore: What to do if source file is not found. Error = alarm and fail,

Info = alarm info and quit with success status, Ignore = quit

with success status.

Default: 0 Example: SourceAction.Error

Operation : SourceOperation

What to do with the source file after transfer.

Possible values:

  • Delete: What to do with the source file after transfer.

  • Rename: What to do with the source file after transfer.

  • Move: What to do with the source file after transfer.

  • Nothing: What to do with the source file after transfer.

Default: 0 Example: SourceOperation.Delete

FileNameAfterTransfer : String

Parameter for Rename operation. You can use file macros and also specify a directory

where to move the files to, e.g. /subdir/%Date%file.txt. If you don't define a

directory path, the source directory is used. When using rename, this parameter

must always contain a file name.

Default: - Example: transferred.txt

DirectoryToMoveAfterTransfer : String

Parameter for Move operation. Set the full path to the directory without the file name. You can use some macros in the directory name, e.g. /subdir/%Year%_uploaded/.

Default: - Example: /upload/transferred/

FilePaths : Object

The paths to the files to transfer, mainly meant to be used with the file trigger with the syntax: #trigger.data.filePaths

Default: - Example: #trigger.data.filePaths

Name
Description

Directory : String

Local directory where files are to be transferred.

Default: / Example: C:\directory</code>

FileName : String

File name of the destination file with possible macros.

Default: - Example: test.txt

FileNameEncoding : FileEncoding

If set, this ecoding will be used to encode and decode command

parameters and server responses, such as file names.

By selecting 'Other' you can use any encoding.

Possible values:

  • UTF8: If set, this ecoding will be used to encode and decode command

parameters and server responses, such as file names.

By selecting 'Other' you can use any encoding.

  • ANSI: If set, this ecoding will be used to encode and decode command

parameters and server responses, such as file names.

By selecting 'Other' you can use any encoding.

  • ASCII: If set, this ecoding will be used to encode and decode command

parameters and server responses, such as file names.

By selecting 'Other' you can use any encoding.

  • WINDOWS1252: If set, this ecoding will be used to encode and decode command

parameters and server responses, such as file names.

By selecting 'Other' you can use any encoding.

  • Other: If set, this ecoding will be used to encode and decode command

parameters and server responses, such as file names.

By selecting 'Other' you can use any encoding.

Default: 1 Example: FileEncoding.ANSI

EnableBomForFileName : Boolean

Additional option for UTF-8 encoding to enable bom.

Default: - Example: true

FileNameEncodingInString : String

File encoding to be used. A partial list of possible encodings: https://en.wikipedia.org/wiki/Windows_code_page#List.

Default: - Example: utf-8

Action : DestinationAction

Operation to determine what to do if destination file exists.

Possible values:

  • Append: Operation to determine what to do if destination file exists.

  • Overwrite: Operation to determine what to do if destination file exists.

  • Error: Operation to determine what to do if destination file exists.

Default: 2 Example: DestinationAction.Error

AddNewLine : Boolean

If enabled new line is added to the existing file before appending the content.

Default: False Example: true

FileContentEncoding : FileEncoding

Encoding for the appending content. By selecting 'Other' you can use any encoding.

Possible values:

  • UTF8: Encoding for the appending content. By selecting 'Other' you can use any encoding.

  • ANSI: Encoding for the appending content. By selecting 'Other' you can use any encoding.

  • ASCII: Encoding for the appending content. By selecting 'Other' you can use any encoding.

  • WINDOWS1252: Encoding for the appending content. By selecting 'Other' you can use any encoding.

  • Other: Encoding for the appending content. By selecting 'Other' you can use any encoding.

Default: 1 Example: FileEncoding.ANSI

FileContentEncodingInString : String

File encoding to be used. A partial list of possible encodings: https://en.wikipedia.org/wiki/Windows_code_page#List.

Default: - Example: utf-8

EnableBomForContent : Boolean

Additional option for UTF-8 encoding to enable bom.

Default: - Example: true

Name
Description

ConnectionTimeout : Int32

The lenght of time, in seconds, until the connection times out.

You can use value -1 to indicate that the connection does not time out.

Default value is 60 seconds.

Default: 60 Example: 60

KeepAliveInterval : Int32

The keep-alive interval in milliseconds. Interval the client send keep-alive packages to the host.

You can use value -1 to disable the keep-alive.

Default: -1 Example: -1

Address : String

SFTP host address

Default: - Example: localhost

Port : Int32

Port number to use in the connection to the server.

Default: 22 Example: 22

Authentication : AuthenticationType

Selection for authentication type

Possible values:

  • UsernamePassword: Selection for authentication type

  • UsernamePrivateKeyFile: Selection for authentication type

  • UsernamePrivateKeyString: Selection for authentication type

  • UsernamePasswordPrivateKeyFile: Selection for authentication type

  • UsernamePasswordPrivateKeyString: Selection for authentication type

Default: - Example: AuthenticationType.UsernamePassword

UserName : String

Username to use for authentication to the server. Note that the file endpoint only supports

username for remote shares and the username must be in the format DOMAIN\Username.

Default: - Example: foo

🗝Password : String

Password to use in the authentication to the server.

Default: - Example: pass

PrivateKeyFile : String

Full path to private key file.

Default: - Example: C:\path\to\private\key

🗝PrivateKeyString : String

Private key as a string, supported private key formats: OpenSSH and ssh.com.

PuTTY keys can be converted with puttygen.exe application.

1. Load your key file into puttygen.exe

2. Conversion > Export OpenSSH key (not the "force new file format" option)

Default: - Example: -----BEGIN RSA PRIVATE KEY----- Fqxq2jbSKyb0a+oW96Tjoif3Kcb5zZ0FiQyiHgQozLXrecjdUwjWuedkDoZMxwG5 bxpOnxZ/88tDzYCtCPcYCPRF8BNueUsZO8/tztTra+4NgVd/omXHG5bqb7iMB4dc ... OX7Q/wO4lqOlFhLtRnSL0cfuhRmt59pM75Zd+euX5tv9jmCj+AQT/kiBoMhNrDGk N2gTujnH7HCr/afSBeL3xnYcEmeCQTxTPZofBjPC+TPd9g7MntSGBeU/Fstv0jbg -----END RSA PRIVATE KEY-----

🗝PrivateKeyPassphrase : String

Passphrase for the private key file.

Default: - Example: passphrase

ServerFingerPrint : String

Fingerprint of the SFTP server. When using "Username-Password"

authentication it is recommended to use server fingerprint in

order to be sure of the server you are connecting. Supported

formats for server fingerprints: MD5 and SHA256.

Default: - Example: MD5: '41:76:EA:65:62:6E:D3:68:DC:41:9A:F2:F2:20:69:9D' SHA256: 'FBQn5eyoxpAl33Ly0gyScCGAqZeMVsfY7qss3KOM/hY='

HostKeyAlgorithm : HostKeyAlgorithms

Host key algorithm to use when connecting to server.

Default value is Any which doesn't force the task to use

specific algorithm.

Possible values:

  • Any: Host key algorithm to use when connecting to server.

Default value is Any which doesn't force the task to use

specific algorithm.

  • RSA: Host key algorithm to use when connecting to server.

Default value is Any which doesn't force the task to use

specific algorithm.

  • Ed25519: Host key algorithm to use when connecting to server.

Default value is Any which doesn't force the task to use

specific algorithm.

  • Nistp256: Host key algorithm to use when connecting to server.

Default value is Any which doesn't force the task to use

specific algorithm.

  • Nistp384: Host key algorithm to use when connecting to server.

Default value is Any which doesn't force the task to use

specific algorithm.

  • Nistp521: Host key algorithm to use when connecting to server.

Default value is Any which doesn't force the task to use

specific algorithm.

Default: 0 Example: HostKeyAlgorithm.RSA

BufferSize : UInt32

Integer value of used buffer size as KB.

Default value is 32 KB.

Default: 32 Example: 32

UseKeyboardInteractiveAuthentication : Boolean

Enable if the server uses keyboard-interactive authentication method.

Default: False Example: false

PromptAndResponse : PromptResponse[]

Responses for the server prompts when using Keyboard Interactive authentication method.

Default: - Example: -

Name
Description

Timeout : Int32

Timeout in seconds when the Task is cancelled after.

Cancellation with the Timeout will stop the operation even if the transfer is occuring.

Task will try to restore the source file. Destination file will be deleted if the cancellation happens during the transfer.

Versus to the Connection.ConnectionTimeout which will only timeout the connection to the SFTP server if client is idle.

Number zero (0) or negative number will disable the timeout.

Default: 0 Example: 30

ThrowErrorOnFail : Boolean

Should an exception be thrown when file transfer fails.

Default: True Example: true

RenameSourceFileBeforeTransfer : Boolean

Should the source file be renamed with temporary file name during file transfer as a locking mechanism.

Default: True Example: true

SourceFileExtension : String

File extension for the temporary source file which is used during the transfer.

Default: .8CO Example: .8CO

RenameDestinationFileDuringTransfer : Boolean

Should the destination file be renamed with temporary file name during file transfer as a locking mechanism.

Default: True Example: true

DestinationFileExtension : String

File extension for the temporary destination file which is used during the transfer.

Default: .8CO Example: .8CO

CreateDestinationDirectories : Boolean

Should the destination directories be created if they do not exist. May not work on all servers.

Default: False Example: true

PreserveLastModified : Boolean

Should the Last Modified timestamp be preserved from the source.

Default: False Example: true

OperationLog : Boolean

While enabled all operations logs of executions will be returned with the result.

Default: True Example: true

Name
Description

TransferName : String

Optional descriptive name for the transfer.

Will be included in the file transfer log

entries and also in all error messages in the event log.

Default: "SFTPDownload" Example: SFTPDownload

WorkDir : String

Directory where temporary files are stored during transfer.

Default: - Example: C:\temp</code>

ProcessUri : String

The process URI, use #process.uri

Default: #process.uri Example: #process.uri

TaskExecutionID : String

Reference to the Task execution id, use #process.executionid

Default: #process.executionid Example: #process.executionid

Task Result

Name
Description

ActionSkipped : Boolean

Boolean value of the skipped Action. Example: false

Success : Boolean

Boolean value of the successful transfer. Example: true

UserResultMessage : String

Message of the transfer operations. Example: 1 files transferred: test.txt"

SuccessfulTransferCount : Int32

Count of files that has been successfully transferred. Example: 1

FailedTransferCount : Int32

Count of files that have not been transferred. Example: 0

TransferredFileNames : IEnumerable<String>

List of transferred file names. Example: [ "test.txt", "test2.txt" ]

TransferErrors : Dictionary<String, IList1>`

Dictionary of file names and errors messages of the failed transfers. Example: { test.txt : [ Failure in CheckIfDestinationFileExists: File 'test.txt' could not be transferred to '/upload/Upload'. Error: Unable to transfer file. Destination file already exists: test.txt [Source file restored.], ] text2.txt : [ Failure in CheckIfDestinationFileExists: File 'test2.txt' could not be transferred to '/upload/Upload'. Error: Unable to transfer file. Destination file already exists: test2.txt [Source file restored.], ] }

TransferredFilePaths : IEnumerable<String>

List of transferred file paths. Example: [ "/Upload/upload/test.txt", "/Upload/upload/test2.txt" ]

TransferredDestinationFilePaths : String[]

List of destination file paths of the transferred files. Example: [ "C:\test\test.txt", "C:\test\test2.txt" ]

OperationsLog : IDictionary<String, String>

Operations logs for the transfer. Example: { "2022-05-30 12:27:35.00Z": "FILE LIST C:\test\test.txt" "2022-06-01 11:01:50.40Z": "RenameSourceFileBeforeTransfer: Renaming source file test.txt to temporary file name frends_637896781104694806az33q4kf.8CO before transfer" }

Task Changelog

Changelog for Task Frends.SFTP.DownloadFiles.

[4.1.0] - 2026-05-22

Added

  • Added support for %SourceRelativeDirectory% macro in Destination.Directory. This macro preserves the source folder structure during download when used with Source.IncludeSubdirectories=true. For files in the root source directory, the macro expands to an empty string. Example: for source '/upload/' and file '/upload/sub1/sub2/file.txt', the macro expands to 'sub1\sub2'.

[4.0.0] - 2026-04-26

Changed

  • Drop support for .NET Framework 4.7.1 and .NET Standard 2.0.

[3.1.0] - 2026-02-17

Fixed

  • Fixed the issue with not deleting all temporary files.

[3.0.0] - 2026-01-27

Changed

Breaking changes!

  • Updated dependency SSH.NET to the newest version 2025.1.0.

  • Drop DSS support

[2.18.0] - 2026-01-23

Fixed

  • Improve error handling to secure against data loss within temporary files.

[2.17.0] - 2026-01-22

Fixed

  • Use safe GUID temp filename to handle source files with Windows-invalid characters

[2.16.0] - 2026-01-13

Fixed

  • Operation timeout is now using the Connection.ConnectionTimeout parameter.

[2.15.0] - 2025-10-17

Fixed

  • Fixed restoring destination file in any case.

[2.14.0] - 2024-09-30

Fixed

  • Fixed small memory leak with CancellationTokenSource by adding dispose to the end of the Task.

[2.13.0] - 2024-09-05

Fixed

  • Fixed issue with certain SFTP servers which did not use IsRegularFile property on files by modifying the logic to check that the file is not anything else than a regular file.

[2.12.0] - 2024-08-16

Updated

  • Updated Renci.SshNet library to version 2024.1.0.

[2.11.0] - 2024-04-30

Fixed

  • Fixed issue were Task threw exception when using macros in Source Directory.

[2.10.0] - 2024-03-06

Added

  • [Breaking] Added new parameter Source.IncludeSubdirectories which enables source file search from subdirectories.

[2.9.1] - 2024-02-22

Changed

  • Added StyleCop.Analyzers to analyze the Task code.

  • Made code changes suggested by the StyleCop.Analyzers.

  • Fixed Readme.

[2.9.0] - 2023-12-15

Added

  • [Breaking] Added new parameter Options.Timeout which will cause the Task to terminate at assigned period of time if enabled.

Fixed

  • Fixed FileOperations.MoveAsync to remove the moved file.

[2.8.0] - 2023-12-05

Changed

  • [Breaking] Changed TransferredDestinationFilePaths Result property type from List to string[].

  • Changed SftpClient operations to use async methods with CancellationToken.

Added

  • Added FileOperations class which handles file operations as async with CancellationToken e.g. Append, Copy, Move.

Fixed

  • Fixed issue where the Task gets stuck and can't be terminated.

[2.7.1] - 2023-09-08

Added

  • Added SFTPClient.OperationTimeout which should cause timeout during operations if the Task becomes stuck.

[2.7.0] - 2023-06-07

Added

  • [Breaking] Added new parameter for keyboard-interactive authentication where users can add prompts and responses.

  • Modified operations log to list current system and sftp server information.

Fixed

  • Modified private key passphrase to be visible when all private key authentication options were enabled.

  • Fixed operations log to show case exceptions more precisely.

[2.6.1] - 2023-05-17

Fixed

  • Fixed issue with TransferredFileNames was incorrect when FilePaths parameter was used.

[2.6.0] - 2023-05-16

Added

  • Added new result attribute TransferredDestinationFilePaths list consisting of the destination file paths.

[2.5.4] - 2023-02-14

Added

  • Re-enabled key exchange algorithms 'curve25519-sha256' and 'curve25519-sha256@libssh.org'.

[2.5.3] - 2023-02-08

Fixed

  • Fixed issue with file not found when downloading from server when server has automatic delete action enabled.

[2.5.2] - 2023-01-31

Added

  • Added cancellation token to the method listing the source files so Task won't freeze in that execution.

[2.5.1] - 2022-12-30

Fixed

  • Fixed issue with empty source dir throws an exception by setting empty source directory as '/'.

  • Fixed issue with when no source files userResultMessage still said no. files transferred and not no files transferred.

[2.5.0] - 2022-12-16

Fixed

  • [Breaking] Fixed issue where keepaliveinterval and operationtimeout is set as the connectiontimeout by creating them for the keepaliveinterval its own parameter and removed operationtimeout.

[2.4.2] - 2022-12-01

Updated

  • Updated dependencies System.Text.Encoding.CodePages and Microsoft.Extensions.DependencyInjection to the newest version.

  • Modified test to run against net471 instead of net6.

[2.4.1] - 2022-11-24

Fixed

  • Fixed issue with files not found when the name consist of special characters by adding a check for the files exact name.

[2.4.0] - 2022-11-03

Added

  • [Breaking] Added parameters for the file extension of temporary source and destination files when rename options are enabled.

  • Fixed task to enable transfers with file paths.

  • Fixed operations log to show correct state when source files are not found with filePaths.

  • Fixed operations log to use temp work path when getting source files to temp directory.

  • Added tests for the filePaths.

  • Modified tests to not use physical files but to create them during test run.

[2.3.0] - 2022-10-12

Added

  • Added boolean parameter for adding a new line when appending to an existing file.

  • Changed the appending to use AppendAllText instead of AppendAllLines.

[2.2.3] - 2022-10-12

Fixed

  • Fixed OperationTimeout and KeepAliveInterval attributes to use directly user input.

[2.2.2] - 2022-10-03

Added

  • Added OperationTimeout and KeepAliveInterval attributes to SftpClient and set them to same value as the ConnectionTimeout parameter.

[2.2.1] - 2022-09-30

Fixed

  • Added possibility to give different directory to the task when using SourceOperation.Rename.

  • Updated documentation.

[2.2.0] - 2022-09-26

Fixed

  • [Breaking] Added option to enable keyboard-interactive authentication method. This change will break the automatic updates of the task.

  • Fixed issue with connecting to server which uses keyboard-interactive authentication method. Fixed by adding UseKeyboardInteractiveAuthentication parameter and handled the method inside tha task.

[2.1.2] - 2022-09-23

Fixed

  • Fixed issue with the error message by changing how the error message is build. Error message had 'SFTP://' in both endpoints.

[2.1.1] - 2022-09-16

Fixed

  • Fixed error handler by adding connection check to FileTransporter and SingleFileTransfer classes. If the client is not connected the task tries to connect again before handling errors.

[2.1.0] - 2022-09-09

Fixed

  • [Beaking] Removed UTF-16 and Unicode FileEncoding because their implementation didn't work. These were used as a parameter so autoupdate won't work.

  • Fixed how the Encoding on windows-1252 is handled. Added NuGet System.Text.Encoding.CodePages which can handle that encoding.

  • Fixed error handling by adding catch to FileTransporter to catch SftpPathNotFoundException and general Exception.

  • Added tests to test the file name and content encoding.

  • Updated the document to state that Ssh.Net only supports private keys in OpenSSH and ssh.com formats.

  • Added documentation on the private key formatingm from putty.ppk to OpenSSH.

  • Fixed HostKeyAlgorithm by removing the forcing of the ssh-rsa.

  • Added HostKeyAlgorithm parameter which enables users to change the host key algorithm used in the task. Before task defaults to ED25519.

  • Added enum HostKeyAlgorithms with the supported algorithms.

  • Modified tests to create testfiles instead of using files from project directory.

[2.0.3] - 2022-08-19

Fixed

  • Fixed issue with server fingerprint given by user in SHA256 hex format was not accepted: Added conversion to the fingerprint given by user.

  • Fixed issue when using invalid server fingerprint in MD5 string format throws wrong error message: Added more specific error messages.

  • Changed how MD5 string is handled. MD5 can now be given without ':' or '-' characters.

  • Fixed issue that Sha256 was only accepted in Base64 format: Added support for Sha256 in hex format.

  • Changed the used HostKeyAlgorithm by forcing to use ssh-rsa default was ed25519.

  • Added more tests for using server fingerprints.

[2.0.2] - 2022-08-10

Fixed

  • Fixed issue where when using Rename options and appending / overwrite the task would throw an exception because the work directory given by user was used with renaming destination file.

  • Added error message if a file with the same name as source file exists in DirectoryToMoveAfterTransfer.

  • Fixed issue where when using SourceOperation.Move the source file cannot be restored when exception occurs.

  • Fixed issue that if SourceOperation is ignore and no source files were found no operations log is created.

  • Removed FileEncoding UTF-16 which was not implemented and threw exception if selected.

[2.0.1] - 2022-07-18

Fixed

  • Fixed issue with task throwing exception when no source files found and source action info or ignore selected.

[2.0.0] - 2022-07-15

Fixed

  • [Breaking] Changed the implementation to work similar to Cobalt by moving the source file to local Temp folder before transfering to destination.

  • Fixed issue where PreserveModified caused exceptions because the method used wrong file path.

  • Fixed bug where source files were deleted if RenameSourceFileBeforeTransfer was enabled and SourceOperation.Move had directory that didn't exist.'

  • Added logger usage in places where it was needed to make the operations log and error info more informative.

  • Modified the logger usage that the logger.NotifyInformation is done after the action so it's easier to see where errors has occurred.

[1.0.4] - 2022-06-30

Fixed

  • Fixed issue where '.' and '..' directories were also fetched when using '*' character as source file mask.

  • Added check for GetSourceFiles so that only files are fetched and not directories.

  • Updated Microsoft.Extension.DependencyInjection library.

[1.0.3] - 2022-06-29

Fixed

  • Fixed issue with forward slash being added to the source directory.

[1.0.2] - 2022-06-15

Fixed

  • Fixed issue with download failes when RenameDestinationFileDuringTransfer was enabled and destination file existed.

  • Added tests to test the issue.

[1.0.1] - 2022-06-13

Fixed

  • Fixed Source Operations removed source file when RenameSourceFileBeforeTransfer was enabled and transfer failed.

  • Fixed Destination file being removed when RenameDestinationFileDuringTransfer was enabled and transfer failed.

  • Removed permission changes to destination file.

  • Fixed documentation.

[1.0.0] - 2022-06-03

Added

  • Initial implementation

PreviousDeleteFilesNextListFiles

Last updated

Was this helpful?