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.

Namespace:   System.IO
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.FileInfo

A 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.

System_CAPS_cautionCaution

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

FileIOPermission

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.

FileIOPermission

Associated enumeration: Write

Security Action: Demand.

For permission to write to file described by the destBackupFileName parameter if one is specified.

.NET Framework
Available since 2.0
Return to top
Show: