Edit

GetFolderPath behavior on Unix

  • Article

Starting in .NET 8, the behavior of Environment.GetFolderPath on Unix operating systems has changed.

Change description

The following tables show how the returned path value changes for each Unix operating system for various special folders.

Linux

SpecialFolder value Path (.NET 7 and earlier) Path (.NET 8 and later)
MyDocuments $HOME Uses XDG_DOCUMENTS_DIR if available; otherwise $HOME/Documents
Personal $HOME Uses XDG_DOCUMENTS_DIR if available; otherwise $HOME/Documents

macOS

SpecialFolder value Path (.NET 7 and earlier) Path (.NET 8 and later)
MyDocuments $HOME NSDocumentDirectory ($HOME/Documents)
Personal $HOME NSDocumentDirectory ($HOME/Documents)
ApplicationData $HOME/.config NSApplicationSupportDirectory (Library/Application Support)
LocalApplicationData $HOME/.local/share NSApplicationSupportDirectory (Library/Application Support)
MyVideos $HOME/Videos NSMoviesDirectory ($HOME/Movies)

Android

SpecialFolder value Path (.NET 7 and earlier) Path (.NET 8 and later)
MyDocuments $HOME $HOME/Documents
Personal $HOME $HOME/Documents

Version introduced

.NET 8 Preview 1

Type of breaking change

This change is a behavioral change.

Reason for change

The previous behavior was incorrect and didn't meet user expectations for Linux, macOS, and Android.

The most common break is if you're passing System.Environment.SpecialFolder.Personal to Environment.GetFolderPath(Environment+SpecialFolder) on Unix to get the $HOME directory (Environment.GetFolderPath(Environment.SpecialFolder.Personal)). Environment.SpecialFolder.Personal and Environment.SpecialFolder.MyDocuments are aliases for the same underlying enumeration value. If you're using Environment.SpecialFolder.Personal in this way, change your code to pass Environment.SpecialFolder.UserProfile instead (Environment.GetFolderPath(Environment.SpecialFolder.UserProfile)).

For other breaks, the recommended action is to do one of the following:

  • Migrate your application's files to the appropriate directory.
  • Add a fallback check for the previous location to your code.

Affected APIs