FileInfo::Replace Method (String^, String^, Boolean)

.NET Framework (current version)

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)

Syntax

C++

public:
[ComVisibleAttribute(false)]
FileInfo^ Replace(
	String^ destinationFileName,
	String^ destinationBackupFileName,
	bool ignoreMetadataErrors
)

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.

Exceptions

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.

Remarks

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.

Examples

The following example uses the Replace method to replace a file with another file and create a backup of the replaced file.

C++


using namespace System;
using namespace System::IO;


// Move a file into another file, delete the original,
// and create a backup of the replaced file.
void ReplaceFile(String^ fileToMoveAndDelete,
                 String^ fileToReplace, String^ backupOfFileToReplace)
{
    // Create a new FileInfo object.
    FileInfo^ fInfo = gcnew FileInfo(fileToMoveAndDelete);

    // replace the file.
    fInfo->Replace(fileToReplace, backupOfFileToReplace, false);
}


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

        String^ originalFile = "test.xml";
        String^ fileToReplace = "test2.xml";
        String^ backUpOfFileToReplace = "test2.xml.bak";

        if (File::Exists(originalFile) && (File::Exists(fileToReplace)))
        {
            Console::WriteLine("Move the contents of {0} into {1}, " +
                "delete {0}, and create a backup of {1}",
                originalFile, 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);
        }
    }
    catch (IOException^ ex)
    {
        Console::WriteLine(ex->Message);
    }
}


//This code produces output similar to the following; 
//results may vary based on the computer/file structure/etc.:
//
//Move the contents of c:\test1.xml into c:\test2.xml, delete c:\test1.xml, 
//and create a backup of c:\test2.xml
//Done