Copy 任务Copy task

将文件复制到文件系统的一个新位置。Copies files to a new location in the file system.

参数Parameters

下表描述了 Copy 任务的参数。The following table describes the parameters of the Copy task.

参数Parameter 说明Description
CopiedFiles 可选的 ITaskItem[] 输出参数。Optional ITaskItem[] output parameter.

包含已成功复制的项,包括尚未进行实际复制但由于其已为最新且 SkipUnchangedFilestrue 因此被跳过的项。Contains the items that were successfully copied, including those that were not actually copied, but were skipped because they were already up-to-date and SkipUnchangedFiles was true.
DestinationFiles 可选 ITaskItem[] 参数。Optional ITaskItem[] parameter.

指定要对其复制源文件的文件的列表。Specifies the list of files to copy the source files to. 此列表应与 SourceFiles 参数中指定的列表具有一对一的映射关系。This list is expected to be a one-to-one mapping with the list specified in the SourceFiles parameter. 也就是说,SourceFiles 中指定的第一个文件将复制到 DestinationFiles 中指定的第一个位置,依次类推。That is, the first file specified in SourceFiles will be copied to the first location specified in DestinationFiles, and so forth.
DestinationFolder 可选 ITaskItem 参数。Optional ITaskItem parameter.

指定要将文件复制到其中的目录。Specifies the directory to which you want to copy the files. 这必须是目录,而不能是文件。This must be a directory, not a file. 如果该目录不存在,将自动创建它。If the directory does not exist, it is created automatically.
OverwriteReadOnlyFiles 可选 Boolean 参数。Optional Boolean parameter.

覆盖文件,即使它们标记为只读文件Overwrite files even if they are marked as read only files
Retries 可选 Int32 参数。Optional Int32 parameter.

指定之前的所有尝试都失败后,尝试复制的次数。Specifies how many times to attempt to copy, if all previous attempts have failed. 默认为零。Defaults to zero.

注意:重试的使用可以屏蔽生成过程中的同步问题。Caution: The use of retries can mask a synchronization problem in your build process.

注意: 尽管任务默认为零次重试,但任务的使用通常会传递 $(CopyRetryCount),这在默认情况下为非零值。Note: While the task default is zero retries, uses of the task often pass $(CopyRetryCount) which is nonzero by default.
RetryDelayMilliseconds 可选 Int32 参数。Optional Int32 parameter.

指定任何必需的重试之间的延迟。Specifies the delay between any necessary retries. 默认值为传递给 CopyTask 构造函数的 RetryDelayMillisecondsDefault 参数。Defaults to the RetryDelayMillisecondsDefault argument, which is passed to the CopyTask constructor.
SkipUnchangedFiles 可选 Boolean 参数。Optional Boolean parameter.

如果为true ,则跳过复制在源和目标之间保持不变的文件。If true, skips the copying of files that are unchanged between the source and destination. 如果文件的大小和上次修改时间相同,则 Copy 任务认为文件保持不变。The Copy task considers files to be unchanged if they have the same size and the same last modified time.

注意: 如果此参数设置为 true,则不应对包含目标使用依赖关系分析,因为如果源文件的上次修改时间比目标文件的上次修改时间更新,则只运行该任务。Note: If you set this parameter to true, you should not use dependency analysis on the containing target, because that only runs the task if the last-modified times of the source files are newer than the last-modified times of the destination files.
SourceFiles 必选 ITaskItem[] 参数。Required ITaskItem[] parameter.

指定要复制的文件。Specifies the files to copy.
UseHardlinksIfPossible 可选 Boolean 参数。Optional Boolean parameter.

如果为 true,则创建已复制文件的硬链接,而不是复制该文件。If true, creates Hard Links for the copied files instead of copying the files.

警告Warnings

警告将被记录,其中包括:Warnings are logged, including:

  • Copy.DestinationIsDirectory

  • Copy.SourceIsDirectory

  • Copy.SourceFileNotFound

  • Copy.CreatesDirectory

  • Copy.HardLinkComment

  • Copy.RetryingAsFileCopy

  • Copy.FileComment

  • Copy.RemovingReadOnlyAttribute

备注Remarks

必须指定 DestinationFolderDestinationFiles 参数,但不能对两者都进行指定。Either the DestinationFolder or the DestinationFiles parameter must be specified, but not both. 如果指定了两者,则任务失败并记录一条错误。If both are specified, the task fails and an error is logged.

除上面列出的参数外,此任务还从 TaskExtension 类继承参数,后者自身继承自 Task 类。In addition to the parameters listed above, this task inherits parameters from the TaskExtension class, which itself inherits from the Task class. 有关这些其他参数的列表及其说明的信息,请参阅 TaskExtension 基类For a list of these additional parameters and their descriptions, see TaskExtension base class.

示例 1Example 1

以下示例将 MySourceFiles 项集合中的项复制到文件夹 c:\MyProject\Destination。The following example copies the items in the MySourceFiles item collection into the folder c:\MyProject\Destination .

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

    <ItemGroup>
        <MySourceFiles Include="a.cs;b.cs;c.cs"/>
    </ItemGroup>

    <Target Name="CopyFiles">
        <Copy
            SourceFiles="@(MySourceFiles)"
            DestinationFolder="c:\MyProject\Destination"
        />
    </Target>

</Project>

示例 2Example 2

以下示例演示如何执行递归复制。The following example demonstrates how to do a recursive copy. 此项目以递归方式将所有文件从 c:\MySourceTree 复制到 c:\MyDestinationTree,同时保留目录结构 。This project copies all of the files recursively from c:\MySourceTree into c:\MyDestinationTree , while maintaining the directory structure.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

    <ItemGroup>
        <MySourceFiles Include="c:\MySourceTree\**\*.*"/>
    </ItemGroup>

    <Target Name="CopyFiles">
        <Copy
            SourceFiles="@(MySourceFiles)"
            DestinationFiles="@(MySourceFiles->'c:\MyDestinationTree\%(RecursiveDir)%(Filename)%(Extension)')"
        />
    </Target>

</Project>

另请参阅See also