From 32c3a6d59b22646537902fb485a6f51e32b83082 Mon Sep 17 00:00:00 2001
From: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
Date: Wed, 13 Oct 2021 17:47:09 -0700
Subject: [PATCH] file.replace exceptions

---
 docs/core/compatibility/6.0.md                |  1 +
 .../6.0/file-replace-exceptions-on-unix.md    | 43 +++++++++++++++++++
 docs/core/compatibility/toc.yml               |  4 ++
 3 files changed, 48 insertions(+)
 create mode 100644 docs/core/compatibility/core-libraries/6.0/file-replace-exceptions-on-unix.md

diff --git a/docs/core/compatibility/6.0.md b/docs/core/compatibility/6.0.md
index 81a12583ffceb..fbc8ed35d82e3 100644
--- a/docs/core/compatibility/6.0.md
+++ b/docs/core/compatibility/6.0.md
@@ -45,6 +45,7 @@ If you're migrating an app to .NET 6, the breaking changes listed here might aff
 | [API obsoletions with non-default diagnostic IDs](core-libraries/6.0/obsolete-apis-with-custom-diagnostics.md) | ✔️ | ❌ | Preview 1 |
 | [Changes to nullable reference type annotations](core-libraries/6.0/nullable-ref-type-annotation-changes.md) | ✔️ | ❌ | Preview 1-2 |
 | [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 |
diff --git a/docs/core/compatibility/core-libraries/6.0/file-replace-exceptions-on-unix.md b/docs/core/compatibility/core-libraries/6.0/file-replace-exceptions-on-unix.md
new file mode 100644
index 0000000000000..602ea518096e6
--- /dev/null
+++ b/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>
diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml
index c0569f3aea668..839535d3e239d 100644
--- a/docs/core/compatibility/toc.yml
+++ b/docs/core/compatibility/toc.yml
@@ -73,6 +73,8 @@ items:
           href: core-libraries/6.0/obsolete-apis-with-custom-diagnostics.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
@@ -599,6 +601,8 @@ items:
           href: core-libraries/6.0/obsolete-apis-with-custom-diagnostics.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