FileInfo.Replace Method (String, String, Boolean)
Replaces the contents of a specified file with the file described by the current FileInfo object, deleting the original file, and creating a backup of the replaced file. Also specifies whether to ignore merge errors.
Assembly: mscorlib (in mscorlib.dll)
<ComVisibleAttribute(False)> Public Function Replace ( destinationFileName As String, destinationBackupFileName As String, ignoreMetadataErrors As Boolean ) As FileInfo
Parameters
- destinationFileName
-
Type:
System.String
The name of a file to replace with the current file.
- destinationBackupFileName
-
Type:
System.String
The name of a file with which to create a backup of the file described by the destFileName parameter.
- ignoreMetadataErrors
-
Type:
System.Boolean
true to ignore merge errors (such as attributes and ACLs) from the replaced file to the replacement file; otherwise false.
Return Value
Type: System.IO.FileInfoA FileInfo object that encapsulates information about the file described by the destFileName parameter.
| Exception | Condition |
|---|---|
| ArgumentException | The path described by the destFileName parameter was not of a legal form. -or- The path described by the destBackupFileName parameter was not of a legal form. |
| ArgumentNullException | The destFileName parameter is null. |
| FileNotFoundException | The file described by the current FileInfo object could not be found. -or- The file described by the destinationFileName parameter could not be found. |
| PlatformNotSupportedException | The current operating system is not Microsoft Windows NT or later. |
The Replace method replaces the contents of a specified file with the contents of the file described by the current FileInfo object. It also creates a backup of the file that was replaced. Finally, it returns a new FileInfo object that describes the overwritten file.
Caution |
|---|
This method will succeed in Windows 2000 environments if the destFileName is read-only and will not raise an exception. Use the IsReadOnly property to check if the destination file is read-only before attempting to replace it. |
Pass null to the destBackupFileName parameter if you do not want to create a backup of the file being replaced.
The following example uses the Replace method to replace a file with another file and create a backup of the replaced file.
Imports System Imports System.IO Module FileExample Sub Main() Try ' originalFile and fileToReplace must contain the path to files that already exist in the ' file system. backUpOfFileToReplace is created during the execution of the Replace method. Dim originalFile As String = "test.xml" Dim fileToReplace As String = "test2.xml" Dim backUpOfFileToReplace As String = "test2.xml.bak" If (File.Exists(originalFile) And (File.Exists(fileToReplace))) Then Console.WriteLine("Move the contents of " + originalFile + " into " + fileToReplace + ", delete " + originalFile + ", and create a backup of " + fileToReplace + ".") ' Replace the file. ReplaceFile(originalFile, fileToReplace, backUpOfFileToReplace) Console.WriteLine("Done") Else Console.WriteLine("Either the file {0} or {1} doesn't " + "exist.", originalFile, fileToReplace) End If Catch e As Exception Console.WriteLine(e.Message) End Try Console.ReadLine() End Sub ' Move a file into another file, delete the original, and create a backup of the replaced file. Sub ReplaceFile(ByVal fileToMoveAndDelete As String, ByVal fileToReplace As String, ByVal backupOfFileToReplace As String) ' Create a new FileInfo object. Dim fInfo As New FileInfo(fileToMoveAndDelete) ' Replace the file. fInfo.Replace(fileToReplace, backupOfFileToReplace, False) End Sub End Module ' Move the contents of test.txt into test2.txt, delete test.txt, and ' create a backup of test2.txt. ' Done
Associated enumerations: Read , Write
Security Action: Demand.
For permission to read and write to the current file and the file described by the destFileName parameter.
Associated enumeration: Write
Security Action: Demand.
For permission to write to file described by the destBackupFileName parameter if one is specified.
Available since 2.0
