file.replace exceptions (#26505)

Author: gewarren

docs/core/compatibility/6.0.md

@@ -46,6 +46,7 @@ If you're migrating an app to .NET 6, the breaking changes listed here might aff
 | [Changes to nullable reference type annotations](core-libraries/6.0/nullable-ref-type-annotation-changes.md) | ✔️ | ❌ | Preview 1-2 |
 | [Conditional string evaluation in Debug methods](core-libraries/6.0/debug-assert-conditional-evaluation.md) | ✔️ | ❌ | RC 1 |
 | [Environment.ProcessorCount behavior on Windows](core-libraries/6.0/environment-processorcount-on-windows.md) | ✔️ | ❌ | Preview 2 |
+| [File.Replace on Unix throws exceptions to match Windows](core-libraries/6.0/file-replace-exceptions-on-unix.md) | ✔️ | ❌ | Preview 7 |
 | [FileStream no longer synchronizes file offset with OS](core-libraries/6.0/filestream-doesnt-sync-offset-with-os.md) | ❌ | ❌ | Preview 4 |
 | [FileStream.Position updates after ReadAsync or WriteAsync completes](core-libraries/6.0/filestream-position-updates-after-readasync-writeasync-completion.md) | ❌ | ❌ | Preview 4 |
 | [New diagnostic IDs for obsoleted APIs](core-libraries/6.0/diagnostic-id-change-for-obsoletions.md) | ✔️ | ❌ | Preview 5 |

docs/core/compatibility/core-libraries/6.0/file-replace-exceptions-on-unix.md

@@ -0,0 +1,43 @@
+---
+title: ".NET 6 breaking change: File.Replace exceptions on Unix"
+description: Learn about the .NET 6 breaking change in core .NET libraries where File.Replace throws exceptions in more cases on Unix-based operating systems.
+ms.date: 10/13/2021
+---
+# File.Replace on Unix throws exceptions to match Windows implementation
+
+The behavior of <xref:System.IO.File.Replace%2A?displayProperty=nameWithType> on Unix-based operating systems has changed. The exceptions it throws now match those that are thrown by the Windows implementation.
+
+## Previous Behavior
+
+On Unix, with .NET 5, the <xref:System.IO.File.Replace%2A?displayProperty=nameWithType> method:
+
+- Throws <xref:System.IO.IOException> with the message `Is a directory` when `sourceFileName` is a file and `destinationFileName` is a directory.
+- Throws <xref:System.IO.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 <xref:System.IO.File.Replace%2A?displayProperty=nameWithType> method:
+
+- Throws <xref:System.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 <xref:System.IO.IOException> with the message `The source <sourceFileName> and destination <destinationFileName> are the same file` when `sourceFileName` and `destinationFileName` point to the same existing file.
+
+## Version introduced
+
+6.0 Preview 7
+
+## Type of breaking change
+
+This change can affect [source compatibility](../../categories.md#source-compatibility).
+
+## Reason for change
+
+This change was made to ensure that <xref:System.IO.File.Replace%2A?displayProperty=nameWithType> throws the same exceptions for the same reasons across platforms.
+
+## Recommended action
+
+If you invoke <xref:System.IO.File.Replace%2A?displayProperty=nameWithType> on Unix inside a `try catch` block, make sure to now also catch <xref:System.UnauthorizedAccessException>. Also, be aware of the new behaviors that are caught.
+
+## Affected APIs
+
+- <xref:System.IO.File.Replace%2A?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -75,6 +75,8 @@ items:
           href: core-libraries/6.0/debug-assert-conditional-evaluation.md
         - name: Environment.ProcessorCount behavior on Windows
           href: core-libraries/6.0/environment-processorcount-on-windows.md
+        - name: File.Replace on Unix throws exceptions to match Windows
+          href: core-libraries/6.0/file-replace-exceptions-on-unix.md
         - name: FileStream no longer synchronizes offset with OS
           href: core-libraries/6.0/filestream-doesnt-sync-offset-with-os.md
         - name: FileStream.Position updated after completion
@@ -609,6 +611,8 @@ items:
           href: core-libraries/6.0/debug-assert-conditional-evaluation.md
         - name: Environment.ProcessorCount behavior on Windows
           href: core-libraries/6.0/environment-processorcount-on-windows.md
+        - name: File.Replace on Unix throws exceptions to match Windows
+          href: core-libraries/6.0/file-replace-exceptions-on-unix.md
         - name: FileStream no longer synchronizes offset with OS
           href: core-libraries/6.0/filestream-doesnt-sync-offset-with-os.md
         - name: FileStream.Position updated after completion