FileInfo::Replace Method (String^, String^, Boolean)
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.
Assembly: mscorlib (in mscorlib.dll)
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.
| 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. |
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.
The following 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) { // 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
Associated enumerations: Read , Write
Security Action: Demand.
For permission to read and write to the current file and the file described by the destFileName parameter.
Associated enumeration: Write
Security Action: Demand.
For permission to write to file described by the destBackupFileName parameter if one is specified.
Available since 2.0
