about_IOInfoExtensions.PowerShell_CopyFrom.help.txt
|
TOPIC
about_IOInfoExtensions.PowerShell_CopyFrom SHORT DESCRIPTION Copies the designated file to the calling [FileInfo]'s location. SYNTAX CopyFrom(System.IO.FileInfo source, [bool overwrite = False]) LONG DESCRIPTION Copies the source file to the calling destination. If the destination exists and 'overwrite' is "false", an exception will be thrown. [System.IO.FileInfo] has a 'CopyTo' method, but it changes the source [FileInfo] object information to match the destination [FileInfo] properties. 'CopyFrom' will allow you to call the copy from the destination, leaving the source object still referencing the source file. PARAMETERS source <System.IO.FileInfo> The source Required: True Default Value: Accepts Wildcard Characters: False overwrite <System.Boolean> Indicates if the destination file should be overwritten if it exists. Required: False Default Value: False Accepts Wildcard Characters: False OUTPUTS N/A EXCEPTIONS System.IO.FileNotFoundException If the source file does not exist. System.IO.IOException If the destination file exists but EXAMPLES --------------------- Example 1 --------------------- Copies and renames a file. $sourceFile = New-Object System.IO.FileInfo 'C:\Demo\ChildFile1.txt' $destinationFile = New-Object System.IO.FileInfo 'C:\DemoCopy\ChildDir3\ChildFile3.txt' Write-Host "File Information:" Write-Host (Get-FileTable -Files $sourceFile, $destinationFile -IncludeDirectory) Write-Host "Copying file..." $destinationFile.CopyFrom($sourceFile) Write-Host "File Information after copy:" Write-Host (Get-FileTable -Files $sourceFile, $destinationFile -IncludeDirectory) <# Output: File Information: Directory Name DirectoryExists Exists --------- ---- --------------- ------ C:\Demo ChildFile1.txt True True C:\DemoCopy\ChildDir3 ChildFile3.txt False False Copying file... File Information after copy: Directory Name DirectoryExists Exists --------- ---- --------------- ------ C:\Demo ChildFile1.txt True True C:\DemoCopy\ChildDir3 ChildFile3.txt True True #> The directory structure is created and the file is copied from the source file without changing the properties of the source [FileInfo] object. Notice: - The directory structure was created. - The source file "ChildFile1.txt" is copied to the destination directory "ChildDir3" and renamed to "ChildFile3.txt". - The source [FileInfo] object is still referencing "ChildFile1.txt". --------------------- Example 2 --------------------- Copies and overwrites a file. $sourceFile = New-Object System.IO.FileInfo 'C:\Demo\ChildFile1.txt' $destinationFile = New-Object System.IO.FileInfo 'C:\DemoCopy\ChildDir3\ChildFile3.txt' Write-Host "File Information:" Write-Host (Get-FileTable -Files $sourceFile, $destinationFile -IncludeDirectory -IncludeHash) Write-Host "Copying file..." $destinationFile.CopyFrom($sourceFile, $true) Write-Host "File Information after copy:" Write-Host (Get-FileTable -Files $sourceFile, $destinationFile -IncludeDirectory -IncludeHash) <# Output: File Information: Directory Name DirectoryExists Exists Hash --------- ---- --------------- ------ ---- C:\Demo ChildFile1.txt True True 373FEB01CBFDCB5121502AFFD3DB5504DABACC8F C:\DemoCopy\ChildDir3 ChildFile3.txt True True 456012073991C95AF2F3628D2C28595A85E80653 Copying file... File Information after copy: Directory Name DirectoryExists Exists Hash --------- ---- --------------- ------ ---- C:\Demo ChildFile1.txt True True 373FEB01CBFDCB5121502AFFD3DB5504DABACC8F C:\DemoCopy\ChildDir3 ChildFile3.txt True True 373FEB01CBFDCB5121502AFFD3DB5504DABACC8F #> The pre-existing destination file is overwritten by the source file. Notice: - The source file "ChildFile1.txt" is copied to the destination directory "ChildDir3" and renamed to "ChildFile3.txt". - The source [FileInfo] object is still referencing "ChildFile1.txt". - The destination file "ChildFile3.txt" is overwritten with the source file "ChildFile1.txt". --------------------- Example 3 --------------------- Throws an error because the destination already exists. $sourceFile = New-Object System.IO.FileInfo 'C:\Demo\ChildFile1.txt' $destinationFile = New-Object System.IO.FileInfo 'C:\DemoCopy\ChildDir3\ChildFile3.txt' Write-Host "File Information:" Write-Host (Get-FileTable -Files $sourceFile, $destinationFile -IncludeDirectory -IncludeHash) Write-Host "Copying file..." try { $destinationFile.CopyFrom($sourceFile) } catch { $stringArgs = @( $_.Exception.GetType().ToString(), $_.Exception.Message, $_.Exception.StackTrace.Substring(0, $_.Exception.StackTrace.IndexOf([Environment]::NewLine)) ) Write-Host ("`nError: {0}: {1}`n{2}`n" -f $stringArgs) $error.Clear() } Write-Host "File Information after copy:" Write-Host (Get-FileTable -Files $sourceFile, $destinationFile -IncludeDirectory -IncludeHash) <# Output: File Information: Directory Name DirectoryExists Exists Hash --------- ---- --------------- ------ ---- C:\Demo ChildFile1.txt True True 373FEB01CBFDCB5121502AFFD3DB5504DABACC8F C:\DemoCopy\ChildDir3 ChildFile3.txt True True 456012073991C95AF2F3628D2C28595A85E80653 Copying file... Error: System.IO.IOException: The file 'C:\DemoCopy\ChildDir3\ChildFile3.txt' already exists. at System.IO.FileSystem.CopyFile(String sourceFullPath, String destFullPath, Boolean overwrite) File Information after copy: Directory Name DirectoryExists Exists Hash --------- ---- --------------- ------ ---- C:\Demo ChildFile1.txt True True 373FEB01CBFDCB5121502AFFD3DB5504DABACC8F C:\DemoCopy\ChildDir3 ChildFile3.txt True True 456012073991C95AF2F3628D2C28595A85E80653 #> The pre-existing destination file is not overwritten by the source file and an error is thrown. Notice: - The destination file "ChildFile3.txt" still has original hash value. KEYWORDS IOInfoExtensions, IOInfoExtensions.PowerShell, System.IO.FileInfo, FileInfo, CopyFrom SEE ALSO about_IOInfoExtensions.PowerShell about_IOInfoExtensions.PowerShell_GetDirectory about_IOInfoExtensions.PowerShell_GetFile about_IOInfoExtensions.PowerShell_DeleteContent about_IOInfoExtensions.PowerShell_CopyContentTo about_IOInfoExtensions.PowerShell_MoveFrom about_IOInfoExtensions.PowerShell_CopyFrom about_IOInfoExtensions.PowerShell_TryDelete |