File::Replace Method (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.
Assembly: mscorlib (in mscorlib.dll)
public: static void Replace( String^ sourceFileName, String^ destinationFileName, String^ destinationBackupFileName )
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.
| Exception | Condition |
|---|---|
| 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 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); } };
for permission to read and write to the file described by the sourceFileName parameter. Security action: Demand. Associated enumeration: FileIOPermissionAccess::Read
for permission to read and write to the file described by the destinationFileName parameter. Security action: Demand. Associated enumerations: FileIOPermissionAccess::Read, FileIOPermissionAccess::Write
for permission to write to file described by the destinationBackupFileName parameter if one is specified. Security action: Demand. Associated enumeration: FileIOPermissionAccess::Write
Available since 2.0