[Breaking Change] `File.Replace` throws exceptions on more cases on Unix

[carlossanlop]

Description

In issue dotnet/runtime#49796 (PR dotnet/runtime#50234) we changed the behavior of File.Replace on Unix so that the exceptions it throws now match those that are thrown by the Windows implementation.

Version

.NET 6 Preview 7

Previous behavior

On Unix, with .NET 5, the File.Replace method:

• Throws IOException with the message Is a directory when sourceFileName is a file and destinationFileName is a directory.
• Throws IOException with the message Not a directory when sourceFileName is a directory and destinationFileName is a file.
• Silently succeeds when both sourceFileName and destinationFileName point to the same file or directory.

New behavior

On Unix, with .NET 6, the File.Replace method now:

• Throws UnauthorizedAccessException with the message The specified path <path> is not a path, when either sourceFileName or destinationFileName exists and is not a file, or when both sourceFileName and destinationFileName point to the same existing directory.
• Throws IOException with the message The source <sourceFileName> and destination <destinationFileName> are the same file when sourceFileName and destinationFileName point to the same existing file.

Type of breaking change

Question: I would classify this as a "different run-time behavior", but that case is mentioned in both options below. Which one do I choose for exception difference behaviors?:

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load/execute or different run-time behavior.
• Source incompatible: Source code may encounter a breaking change in behavior when targeting the new runtime/component/SDK, such as compile errors or different run-time behavior.

Reason for change

Ensuring we throw the same exceptions for the same reasons across platforms in File.Replace.

Recommended action

If your File.Replace invocation on Unix is inside a try catch, make sure to now also catch UnauthorizedAccessException, and be aware of the new behaviors that are caught.

Feature area

Core .NET Libraries

Affected APIs

File.Replace https://docs.microsoft.com/en-us/dotnet/api/system.io.file.replace?view=net-6.0