diff --git a/docs/core/compatibility/8.0.md b/docs/core/compatibility/8.0.md index d81449122cc6b..5c2e92d4bdda0 100644 --- a/docs/core/compatibility/8.0.md +++ b/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 | diff --git a/docs/core/compatibility/core-libraries/8.0/file-path-backslash.md b/docs/core/compatibility/core-libraries/8.0/file-path-backslash.md new file mode 100644 index 0000000000000..921c8c287783d --- /dev/null +++ b/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 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 +- +- +- +- +- +- +- +- +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 652d81c63e2ca..3052f41617496 100644 --- a/docs/core/compatibility/toc.yml +++ b/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