[Breaking change]: Environment.GetFolderPath returns incorrect path on Unix #31423

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

macOS Behavior

Android Behavior

New behavior

Linux Behavior

macOS Behavior

Android Behavior

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

Associated WorkItem - 60641