Background and motivation

Environment.SpecialFolder has two enum names that map to the same underlying enum value MyDocuments and Personal.

This is rather confusing, and also leads to bugs because consumers wrongly believe that Environment.SpecialFolder.Personal really means Environment.SpecialFolder.UserProfile. Further, with #68610, we are fixing the path returned from SpecialFolder.MyDocuments/Personal to actually be a "Documents" folder on both Linux and macOS. When doing the breaking change analysis, I found more places using Environment.SpecialFolder.Personal to mean Environment.SpecialFolder.UserProfile than I did for it to mean an actual "MyDocuments" folder.

We should deprecate and hide the Personal enum value because people are using it wrong and it means the exact same thing as "MyDocuments".

Examples of places that got it wrong:

• Fix SpecialFolder.Personal usages maui#10098 and Fix SpecialFolder.Personal usages Microsoft.Maui.Graphics.Controls#124
• Fix SpecialFolder.Personal usages android-tools#194
• Fix SpecialFolder.Personal usage RicoSuter/Namotion.Reflection#121

API Proposal

namespace System;

public static partial class Environment
{
    public enum SpecialFolder
    {
+       [EditorBrowsable(EditorBrowsableState.Never)]
+       [Obsolete("Use Environment.SpecialFolder.MyDocuments instead")]
        Personal = SpecialFolderValues.CSIDL_PERSONAL,

API Usage

Don't use Environment.SpecialFolder.Personal, instead either pick SpecialFolder.MyDocuments or SpecialFolder.UserProfile, as appropriate.

Alternative Designs

No response

Risks

No response