Backslash mapping breaking change (#33790)

Author: gewarren

docs/core/compatibility/8.0.md

@@ -19,6 +19,7 @@ If you're migrating an app to .NET 8, the breaking changes listed here might aff
 | Title                                                                                   | Type of change    | Introduced |
 | --------------------------------------------------------------------------------------- | ----------------- | ---------- |
 | [Activity operation name when null](core-libraries/8.0/activity-operation-name.md)      | Behavioral change | Preview 1  |
+| [Backslash mapping in Unix file paths](core-libraries/8.0/file-path-backslash.md)       | Behavioral change | Preview 1  |
 | [FileStream writes when pipe is closed](core-libraries/8.0/filestream-disposed-pipe.md) | Behavioral change | Preview 1  |
 | [GetFolderPath behavior on Unix](core-libraries/8.0/getfolderpath-unix.md)              | Behavioral change | Preview 1  |
 | [Legacy Console.ReadKey removed](core-libraries/8.0/console-readkey-legacy.md)          | Behavioral change | Preview 1  |

docs/core/compatibility/core-libraries/8.0/file-path-backslash.md

@@ -0,0 +1,47 @@
+---
+title: ".NET 8 breaking change: Backslash mapping in Unix file paths"
+description: Learn about the .NET 8 breaking change in core .NET libraries where the CoreCLR native runtime no longer maps backslashes to forward slashes in file paths on Unix.
+ms.date: 01/30/2023
+---
+# Backslash mapping in Unix file paths
+
+Backslash (`\`) characters are valid in directory and file names on Unix. Starting in .NET 8, the native CoreCLR runtime no longer converts `\` characters to directory separators—forward slashes (`/`)—on Unix. This change enables .NET applications to be located on paths with names that contain backslash characters. It also allows the native runtime, `dotnet` host, and the `ilasm` and `ildasm` tools to access files on paths that contain backslash characters.
+
+## Previous behavior
+
+The native CoreCLR runtime automatically converted backslash (`\`) characters in file paths to forward slashes (`/`) on Unix.
+
+## New behavior
+
+The native CoreCLR runtime doesn't convert any file path characters on Unix.
+
+## Version introduced
+
+.NET 8 Preview 1
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+Without this change, .NET apps located in directories that contain backslash characters fail to start.
+
+## Recommended action
+
+- Use <xref:System.IO.Path.DirectorySeparatorChar?displayProperty=nameWithType> as a directory separator in your app instead of hardcoding it to `\` or `/`.
+- Use `/` as a directory separator on Unix in file paths that you pass to the `dotnet` host, hosting APIs, and `ilasm` and `ildasm` tools.
+- Use `/` as a directory separator on Unix in file paths in various `DOTNET_xxx` [environment variables](../../../tools/dotnet-environment-variables.md).
+
+## Affected APIs
+
+- Hosting APIs
+- <xref:System.Runtime.InteropServices.DllImportAttribute.Value?displayProperty=fullName>
+- <xref:System.Runtime.InteropServices.NativeLibrary.Load%2A?displayProperty=fullName>
+- <xref:System.Runtime.InteropServices.NativeLibrary.TryLoad%2A?displayProperty=fullName>
+- <xref:System.Reflection.Assembly.LoadFrom%2A?displayProperty=fullName>
+- <xref:System.Reflection.Assembly.LoadFile%2A?displayProperty=fullName>
+- <xref:System.Reflection.Assembly.UnsafeLoadFrom(System.String)?displayProperty=fullName>
+- <xref:System.Runtime.Loader.AssemblyLoadContext.LoadFromAssemblyPath(System.String)?displayProperty=fullName>
+- <xref:System.Runtime.Loader.AssemblyLoadContext.LoadFromNativeImagePath(System.String,System.String)?displayProperty=fullName>
+- <xref:System.Runtime.Loader.AssemblyLoadContext.LoadUnmanagedDllFromPath(System.String)?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -12,6 +12,8 @@ items:
       items:
       - name: Activity operation name when null
         href: core-libraries/8.0/activity-operation-name.md
+      - name: Backslash mapping in Unix file paths
+        href: core-libraries/8.0/file-path-backslash.md
       - name: FileStream writes when pipe is closed
         href: core-libraries/8.0/filestream-disposed-pipe.md
       - name: GetFolderPath behavior on Unix
@@ -892,6 +894,8 @@ items:
       items:
       - name: Activity operation name when null
         href: core-libraries/8.0/activity-operation-name.md
+      - name: Backslash mapping in Unix file paths
+        href: core-libraries/8.0/file-path-backslash.md
       - name: FileStream writes when pipe is closed
         href: core-libraries/8.0/filestream-disposed-pipe.md
       - name: GetFolderPath behavior on Unix