File.Replace File.Replace File.Replace File.Replace Method

Definition

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.

Overloads

Replace(String, String, String) Replace(String, String, String) Replace(String, String, String) Replace(String, String, String)

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.

Replace(String, String, String, Boolean) Replace(String, String, String, Boolean) Replace(String, String, String, Boolean) Replace(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.

Remarks

The Replace methods replace the contents of a specified file with the contents of another file. They also create a backup of the file that was replaced.

Replace(String, String, String) Replace(String, String, String) Replace(String, String, String) Replace(String, String, String)

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.

public:
 static void Replace(System::String ^ sourceFileName, System::String ^ destinationFileName, System::String ^ destinationBackupFileName);
public static void Replace (string sourceFileName, string destinationFileName, string destinationBackupFileName);
static member Replace : string * string * string -> unit
Public Shared Sub Replace (sourceFileName As String, destinationFileName As String, destinationBackupFileName As String)

Parameters

sourceFileName
String String String String

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

destinationFileName
String String String String

The name of the file being replaced.

destinationBackupFileName
String String String String

The name of the backup file.

Exceptions

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.

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

-or-

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

An I/O error occurred while opening the file.

-or-

The sourceFileName and destinationFileName parameters specify the same file.

The specified path, file name, or both exceed the system-defined maximum length.

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

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.

Examples

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

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)
{
    File::Replace(fileToMoveAndDelete, fileToReplace,
        backupOfFileToReplace, false);
}	


int 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 (IOException^ ex)
    {
        Console::WriteLine(ex->Message);
    } 
};
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);

        }
    }
}
Imports System
Imports System.IO

Module FileExample

    Sub Main()
        Try
            Dim OriginalFile As String = "test.xml"
            Dim FileToReplace As String = "test2.xml"
            Dim BackUpOfFileToReplace As String = "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 e As Exception
            Console.WriteLine(e)
        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)

        ' Replace the file.
        File.Replace(FileToMoveAndDelete, FileToReplace, BackupOfFileToReplace, False)

    End Sub
End Module

Remarks

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.

If the destinationBackupFileName already exists it will be overwritten with the contents of the destinationFileName file.

Security

FileIOPermission
for permission to write to file described by the destinationBackupFileName parameter if one is specified. Security action: Demand. Associated enumeration: Write

Replace(String, String, String, Boolean) Replace(String, String, String, Boolean) Replace(String, String, String, Boolean) Replace(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.

public:
 static void Replace(System::String ^ sourceFileName, System::String ^ destinationFileName, System::String ^ destinationBackupFileName, bool ignoreMetadataErrors);
public static void Replace (string sourceFileName, string destinationFileName, string destinationBackupFileName, bool ignoreMetadataErrors);
static member Replace : string * string * string * bool -> unit
Public Shared Sub Replace (sourceFileName As String, destinationFileName As String, destinationBackupFileName As String, ignoreMetadataErrors As Boolean)

Parameters

sourceFileName
String String String String

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

destinationFileName
String String String String

The name of the file being replaced.

destinationBackupFileName
String String String String

The name of the backup file.

ignoreMetadataErrors
Boolean Boolean Boolean Boolean

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

Exceptions

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.

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

-or-

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

An I/O error occurred while opening the file.

-or-

The sourceFileName and destinationFileName parameters specify the same file.

The specified path, file name, or both exceed the system-defined maximum length.

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

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.

Examples

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

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)
{
    File::Replace(fileToMoveAndDelete, fileToReplace,
        backupOfFileToReplace, false);
}	


int 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 (IOException^ ex)
    {
        Console::WriteLine(ex->Message);
    } 
};
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);

        }
    }
}
Imports System
Imports System.IO

Module FileExample

    Sub Main()
        Try
            Dim OriginalFile As String = "test.xml"
            Dim FileToReplace As String = "test2.xml"
            Dim BackUpOfFileToReplace As String = "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 e As Exception
            Console.WriteLine(e)
        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)

        ' Replace the file.
        File.Replace(FileToMoveAndDelete, FileToReplace, BackupOfFileToReplace, False)

    End Sub
End Module

Remarks

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.

If the destinationBackupFileName already exists it will be overwritten with the contents of the destinationFileName file.

Security

FileIOPermission
for permission to write to file described by the destinationBackupFileName parameter if one is specified. Security action: Demand. Associated enumeration: Write

Applies to