Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Copy

Copy files.

Task version: 3.0.0

Required Frends version: 5.7+

Required .NET version: 8.0

Compatible Agents: Crossplatform

Task Parameters

Name
Description

Directory : String

Source directory.

Default: - Example: c:\temp

Pattern : String

Pattern to match relative to Directory. Matching is case-insensitive and separators are normalized to /. For regex mode, prefix the pattern with and the matcher checks the full relative path and filename. For wildcard mode, * and ** work as glob operators and regex special characters are treated literally.

Default: "\Folder*.xml" Example: /Folder/.xml, Folder/.txt, report-.csv, ^(?!prof)._test.txt

TargetDirectory : String

Target directory where the found files should be copied to

Default: "d:\backup" Example: d:\backup</code>

Name
Description

UseGivenUserCredentialsForRemoteConnections : Boolean

If set, allows you to give the user credentials to use to delete files on remote hosts.

If not set, the agent service user credentials will be used.

Note: This feature is only possible with Windows agents.

Default: False Example: true

UserName : String

This needs to be of format domain\username

Default: "domain\username" Example: domain\username

🗝Password : String

Password for the used credentials.

Default: - Example: testpwd

PreserveDirectoryStructure : Boolean

If set, will recreate the directory structure from the SourceDirectory under the TargetDirectory for copied files

Default: False Example: true

CreateTargetDirectories : Boolean

If set, will create the target directory if it does not exist,

as well as any sub directories when PreserveDirectoryStructure is set.

Default: True Example: true

IfTargetFileExists : FileExistsAction

What should happen if a file with the same name already exists in the target directory.

* Throw - Throw an error and roll back all transfers

* Overwrite - Overwrites the target file

* Rename - Renames the transferred file by appending a number to the end

Possible values:

  • Throw: Throw an error and roll back all transfers.

  • Overwrite: Overwrite the target file.

  • Rename: Rename the transferred file by appending a number to the end.

Default: - Example: FileExistsAction.Overwrite

ContinueOnFailure : Boolean

Whether to continue copying after an individual file fails.

When true, failed files are listed in the result and Success remains true.

When false, copying stops at the first failure. The failed and unprocessed files

are listed in FailedFiles when ThrowErrorOnFailure is false.

Default: False Example: false

ThrowErrorOnFailure : Boolean

Whether to throw the exception when the task fails, including when a file fails

and ContinueOnFailure is false. If false, returns a result with Success=false and Error details.

Default: True Example: true

ErrorMessageOnFailure : String

Overrides the error message for task-level failures.

Default: - Example: File copy failed due to insufficient permissions

Task Result

Name
Description

Success : Boolean

Indicates whether the operation completed successfully. Remains true if individual files fail while ContinueOnFailure is enabled. Example: true

Error : Error

Error details. Null when Success is true. Example: null

Error.Message : String

Summary of the error. Example: Access denied to the source file.

Error.AdditionalInfo : Exception

Additional information about the error. Example: object { Exception AdditionalInfo }

Files : List<FileItem>

List of FileItems including source directory and target directory. Example: [object {SourcePath: C:\test\testfolder\test1.txt, TargetPath: C:\test\moved\test1.txt}, object {SourcePath: C:\test\testfolder\test2.txt, TargetPath: C:\test\moved\test2.txt}]

FailedFiles : List<FailedFileItem>

List of FailedItems including path of the source file and failure exception. When ContinueOnFailure is false, unprocessed files have a null Exception. When ContinueOnFailure is true, this list can contain failures even if Success is true. Example: [object {SourcePath: C:\test\testfolder\test1.txt, Exception: object {Message: Unable to create 'C:\test\moved' directory}}, object {SourcePath: C:\test\testfolder\test2.txt, Exception: object {Message: File 'C:\test\moved\test2.txt' already exists}}]

Task Changelog

Changelog for Task Frends.Files.Copy.

[3.0.0] - 2026-10-05

Changed

  • Results include Success, Error, Files, and FailedFiles details.

  • [Breaking Change] Added options to control failure handling:

    • ContinueOnFailure (default false) determines whether copying continues after an individual file fails. When true, failed files are listed in FailedFiles and Success remains true; when false, copying stops at the first failure and remaining files are listed in FailedFiles without an exception.

    • ThrowErrorOnFailure (default true) determines whether a task-level failure is thrown or returned as Success = false with error details in Error. This applies when copying stops after a failure.

    • ErrorMessageOnFailure optionally supplies a custom message for task-level failures, either in the thrown exception or the returned Error.

[2.0.0] - 2026-09-10

Changed

  • Upgraded the task to .NET 8.

  • [Breaking Change] Standardize pattern matching logic between tasks.

  • Clarified relative input matching rules: patterns are evaluated relative to Directory, separators are normalized to /, matching is case-insensitive, glob mode supports * and **, and <regex> enables regex evaluation against the relative path and file name.

[1.3.0] - 2025-03-19

Changed

  • Update packages: Microsoft.Extensions.FileSystemGlobbing 7.0.0 -> 9.0.3 System.ComponentModel.Annotations 4.7.0 -> 5.0.0 System.DirectoryServices 7.0.0 -> 8.0.0 coverlet.collector 3.1.0 -> 6.0.4 Microsoft.NET.Test.Sdk 16.6.1 -> 17.13.0 MSTest.TestAdapter 2.2.7 -> 3.8.3 MSTest.TestFramework 2.2.8 -> 3.8.3 nunit 3.12.0 -> 4.3.2 NUnit3TestAdapter 3.17.0 -> 5.0.0

[1.2.0] - 2025-04-08

Added

  • New option ThrowErrorOnFail to allow task to continue despite some files failing to copy.

    • Files that failed to copy will be listed in the Result.FailedFiles property.

    • When set to false and IfTargetFileExists is set to Throw, the task will continue copying other files despite an error.

[1.1.0] - 2025-03-13

Fixed

  • Fixed bug where regex patterns were not handled correctly in file matching.

[1.0.2] - 2023-11-27

Changed

  • Documentational changes.

[1.0.1] - 2023-09-21

Fixed

  • Fixed bug with file access. Changed File.Open to use FileAccess.Read, because there's no reason to give more access to the Task.

[1.0.0] - 2023-02-14

Added

  • Initial implementation

Last updated

Was this helpful?