[Breaking change]: Environment.GetFolderPath returns incorrect path on Unix #31423
Description
Description
What version of .NET introduced the breaking change?: .NET 8 Preview 1
Starting with .NET 8, the behavior of Environment.GetFolderPath on Unix operating systems has changed according to the following previous and new behavior tables below.
See dotnet/runtime#68610 and dotnet/runtime#76250
Version
Other (please put exact version in description textbox)
Previous behavior
Linux Behavior
| SpecialFolder value | Path |
|---|---|
MyDocuments / Personal (different name, same value) |
$HOME |
macOS Behavior
| SpecialFolder value | Path |
|---|---|
MyDocuments / Personal (different name, same value) |
$HOME |
ApplicationData |
$HOME/.config |
LocalApplicationData |
$HOME/.local/share |
MyVideos |
$HOME/Videos |
Android Behavior
| SpecialFolder value | Path |
|---|---|
MyDocuments / Personal (different name, same value) |
$HOME |
New behavior
Linux Behavior
| SpecialFolder value | Path |
|---|---|
MyDocuments / Personal (different name, same value) |
Uses XDG_DOCUMENTS_DIR, if available. $HOME/Documents otherwise |
macOS Behavior
| SpecialFolder value | Path |
|---|---|
MyDocuments / Personal (different name, same value) |
NSDocumentDirectory ($HOME/Documents) |
ApplicationData |
NSApplicationSupportDirectory (Library/Application Support) |
LocalApplicationData |
NSApplicationSupportDirectory (Library/Application Support) |
MyVideos |
NSMoviesDirectory ($HOME/Movies) |
Android Behavior
| SpecialFolder value | Path |
|---|---|
MyDocuments / Personal (different name, same value) |
$HOME/Documents |
Type of breaking change
- 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
The previous behavior was incorrect and not consistent with Linux / macOS / Android users' expectations.
Recommended action
The most common break is using Environment.GetFolderPath(Environment.SpecialFolder.Personal) on Unix to get the $HOME directory. Environment.SpecialFolder.Personal and Environment.SpecialFolder.Documents are aliases for the same underlying enum value. If you are using SpecialFolder.Personal in this way, it is recommended to change your code to Environment.GetFolderPath(Environment.SpecialFolder.UserProfile).
For other breaks, the recommended action is to either
- Migrate your application's files to the appropriate directory
- or -- Add a fallback check for the previous location to your code
Feature area
Core .NET libraries
Affected APIs
namespace System;
class Environment:
public static string GetFolderPath (Environment.SpecialFolder folder); - Doc link
public static string GetFolderPath (Environment.SpecialFolder folder, Environment.SpecialFolderOption option); - Doc link