Copy
Copy files.
Task version: 3.0.0
Required Frends version: 5.7+
Required .NET version: 8.0
Compatible Agents: Crossplatform
Task Parameters
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>
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
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, andFailedFilesdetails.[Breaking Change] Added options to control failure handling:
ContinueOnFailure(defaultfalse) determines whether copying continues after an individual file fails. Whentrue, failed files are listed inFailedFilesandSuccessremainstrue; whenfalse, copying stops at the first failure and remaining files are listed inFailedFileswithout an exception.ThrowErrorOnFailure(defaulttrue) determines whether a task-level failure is thrown or returned asSuccess = falsewith error details inError. This applies when copying stops after a failure.ErrorMessageOnFailureoptionally supplies a custom message for task-level failures, either in the thrown exception or the returnedError.
[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?

