File.Replace Method (String, String, String, Boolean)

Replaces the contents of a specified file with the contents of another file, deleting the original file, and creating a backup of the replaced file and optionally ignores merge errors.

Namespace:  System.IO
Assembly:  mscorlib (in mscorlib.dll)

public static void Replace(
	string sourceFileName,
	string destinationFileName,
	string destinationBackupFileName,
	bool ignoreMetadataErrors
)

Parameters

sourceFileName
Type: System.String

The name of a file that replaces the file specified by destinationFileName.

destinationFileName
Type: System.String

The name of the file being replaced.

destinationBackupFileName
Type: System.String

The name of the backup file.

ignoreMetadataErrors
Type: System.Boolean

true to ignore merge errors (such as attributes and access control lists (ACLs)) from the replaced file to the replacement file; otherwise, false.

ExceptionCondition
ArgumentException

The path described by the destinationFileName parameter was not of a legal form.

-or-

The path described by the destinationBackupFileName parameter was not of a legal form.

ArgumentNullException

The destinationFileName parameter is null.

DriveNotFoundException

An invalid drive was specified.

FileNotFoundException

The file described by the current FileInfo object could not be found.

-or-

The file described by the destinationBackupFileName parameter could not be found.

IOException

An I/O error occurred while opening the file.

- or -

The sourceFileName and destinationFileName parameters specify the same file.

PathTooLongException

The specified path, file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.

PlatformNotSupportedException

The operating system is Windows 98 Second Edition or earlier and the files system is not NTFS.

UnauthorizedAccessException

The sourceFileName or destinationFileName parameter specifies a file that is read-only.

-or-

This operation is not supported on the current platform.

-or-

Source or destination parameters specify a directory instead of a file.

-or-

The caller does not have the required permission.

The Replace method replaces the contents of a specified file with the contents of another file. It also creates a backup of the file that was replaced.

If the sourceFileName and destinationFileName are on different volumes, this method will raise an exception. If the destinationBackupFileName is on a different volume from the source file, the backup file will be deleted.

Pass null to the destinationBackupFileName parameter if you do not want to create a backup of the file being replaced.

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

using System;
using System.IO;

namespace FileSystemExample
{
    class FileExample
    {
        public static void Main()
        {
            try
            {
                string OriginalFile = "test.xml";
                string FileToReplace = "test2.xml";
                string BackUpOfFileToReplace = "test2.xml.bac";

                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");
            }
            catch (Exception e)
            {
                Console.WriteLine(e);
            }

            Console.ReadLine();
        }

        // Move a file into another file, delete the original, and create a backup of the replaced file. 
        public static void ReplaceFile(string FileToMoveAndDelete, string FileToReplace, string BackupOfFileToReplace)
        {
            File.Replace(FileToMoveAndDelete, FileToReplace, BackupOfFileToReplace, false);

        }
    }
}

.NET Framework

Supported in: 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft