FileSystem.CopyFile IOException timing and data integrity

Direct Answer

Microsoft.VisualBasic.FileIO.FileSystem.CopyFile(source, destination, overwrite: false) throws IOException when a file already exists at the destination path. The documentation does not specify whether that exception is raised during a pre-existence check before any destination access or only after an attempt to open or create the destination file. Treat the timing as an unspecified implementation detail; do not infer from it whether the destination was touched or left unchanged.

Confirmed facts

• Overwrite=false produces IOException if the destination file already exists.
• FileSystem.CopyFile provides no built-in checksum, byte-count comparison, or post-copy validation.
• A successful copy transfers bytes only; integrity verification is the developer's responsibility.

Likely explanation

The method must enforce the overwrite rule, so it either checks for the destination's existence first or attempts to open the destination and fails when replacement is disallowed. Which path occurs depends on the .NET implementation and underlying filesystem, so exception timing is not a guaranteed contract across runtimes.

Restore steps for this case

1. Hash the source file immediately before restore and record its length.
2. Call CopyFile with overwrite:false inside a try block and catch IOException.
3. If IOException occurs, report a conflict and leave the existing destination untouched.
4. If replacement is allowed, copy to a temporary file in the same directory, verify the temporary file's length and hash against the source, then replace the original using a platform-appropriate atomic move or replace operation.
5. After replacement, hash the destination and compare it to the recorded source hash and length.

Hashing after copy does not prove the source was not already corrupt; hash the source at backup time or immediately before restore for meaningful integrity evidence.

Missing diagnostic detail

Which target framework and destination filesystem are you using? On .NET Framework on Windows, File.Replace is the usual verify-then-swap primitive; cross-platform .NET may require a different move strategy, so this detail changes the recommended replacement code.

Verification

byte[] sourceHash = SHA256.HashData(File.ReadAllBytes(sourcePath));
string tempPath = Path.Combine(Path.GetDirectoryName(destinationPath), Path.GetRandomFileName());
File.Copy(sourcePath, tempPath, overwrite: true);
byte[] tempHash = SHA256.HashData(File.ReadAllBytes(tempPath));
// Compare sourceHash and tempHash, then atomically replace destinationPath with tempPath

Reproduce locally by creating source and destination files with different content, recording destination length and hash, calling CopyFile with overwrite:false, catching IOException, and confirming the destination length and hash remain unchanged.

Assumption: Microsoft.VisualBasic.FileIO is available on the target .NET implementation. Behavior may differ between .NET Framework and modern .NET; do not rely on undocumented exception ordering.