File.Replace Method (System.IO) - Microsoft Learn

Table of contents Exit editor mode Ask Learn Ask Learn Focus mode Language

• csharp
• vb
• fsharp
• cpp

Table of contents Read in English Add Add to plan Edit

Share via

Facebook x.com LinkedIn Email Copy Markdown Print

Note

Access to this page requires authorization. You can try signing in or changing directories.

Access to this page requires authorization. You can try changing directories.

Summarize this article for me File.Replace Method

Definition

Namespace: System.IO Assemblies:netstandard.dll, System.Runtime.dll Assemblies:netstandard.dll, System.IO.FileSystem.dll Assemblies:netstandard.dll, System.IO.FileSystem.dll, System.Runtime.dll Assembly:System.IO.FileSystem.dll Assembly:mscorlib.dll Assembly:netstandard.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

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

Name	Description
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)	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)

Source:File.cs Source:File.cs Source:File.cs Source:File.cs

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); 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

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

destinationFileName String

The name of the file being replaced.

destinationBackupFileName String

The name of the backup file.

Exceptions

ArgumentException

The path described by the destinationFileName or destinationBackupFileName parameter is not of a legal form.

ArgumentNullException

The destinationFileName parameter is null.

DriveNotFoundException

An invalid drive was specified.

FileNotFoundException

The file described by sourceFileName or destinationFileName 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.

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.

-or

sourceFileName and destinationFileName specify the same existing directory.

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 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); } } } open System open System.IO // Move a file into another file, delete the original, and create a backup of the replaced file. let replaceFile fileToMoveAndDelete fileToReplace backupOfFileToReplace = File.Replace(fileToMoveAndDelete, fileToReplace, backupOfFileToReplace, false) let originalFile = "test.xml" let fileToReplace = "test2.xml" let backUpOfFileToReplace = "test2.xml.bac" printfn $"Move the contents of {originalFile} into {fileToReplace}, delete {originalFile}, and create a backup of {fileToReplace}." // Replace the file. replaceFile originalFile fileToReplace backUpOfFileToReplace printfn "Done" 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 raises 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 don't want to create a backup of the file being replaced.

If the destinationBackupFileName already exists, it's replaced with the contents of the destinationFileName file.

Applies to

Replace(String, String, String, Boolean)

Source:File.cs Source:File.cs Source:File.cs Source:File.cs

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); 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

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

destinationFileName String

The name of the file being replaced.

destinationBackupFileName String

The name of the backup file.

ignoreMetadataErrors 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

ArgumentException

The path described by the destinationFileName or destinationBackupFileName parameter is not of a legal form.

ArgumentNullException

The destinationFileName parameter is null.

DriveNotFoundException

An invalid drive was specified.

FileNotFoundException

The file described by sourceFileName or destinationFileName parameter could not be found.

IOException

An I/O error occurred while opening the file.

-or-

sourceFileName and destinationFileName specify the same file.

PathTooLongException

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

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.

-or

sourceFileName and destinationFileName specify the same existing directory.

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 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); } } } open System open System.IO // Move a file into another file, delete the original, and create a backup of the replaced file. let replaceFile fileToMoveAndDelete fileToReplace backupOfFileToReplace = File.Replace(fileToMoveAndDelete, fileToReplace, backupOfFileToReplace, false) let originalFile = "test.xml" let fileToReplace = "test2.xml" let backUpOfFileToReplace = "test2.xml.bac" printfn $"Move the contents of {originalFile} into {fileToReplace}, delete {originalFile}, and create a backup of {fileToReplace}." // Replace the file. replaceFile originalFile fileToReplace backUpOfFileToReplace printfn "Done" 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 raises 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 don't want to create a backup of the file being replaced.

If the destinationBackupFileName already exists, it's replaced with the contents of the destinationFileName file.

Applies to

Collaborate with us on GitHub The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.

.NET

Open a documentation issue Provide product feedback

Feedback

Was this page helpful?

Yes No No

Need help with this topic?

Want to try using Ask Learn to clarify or guide you through this topic?

Ask Learn Ask Learn Suggest a fix?

In this article

Was this page helpful?

Yes No No

Need help with this topic?

Want to try using Ask Learn to clarify or guide you through this topic?

Ask Learn Ask Learn Suggest a fix?