search

dotnet / runtime

.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.
https://docs.microsoft.com/dotnet/core/
MIT License
15.39k stars 4.75k forks source link

[API Proposal]: Deprecate / Hide Environment.SpecialFolder.Personal #75563

Open eerhardt opened 2 years ago

eerhardt commented 2 years ago

Background and motivation

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

https://github.com/dotnet/runtime/blob/62140229d9e222eb326e18207d166209330b2194/src/libraries/System.Private.CoreLib/src/System/Environment.SpecialFolder.cs#L30-L31

This is rather confusing, and also leads to bugs because consumers wrongly believe that Environment.SpecialFolder.Personal really means Environment.SpecialFolder.UserProfile. Further, with https://github.com/dotnet/runtime/pull/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:

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

ghost commented 2 years ago

Tagging subscribers to this area: @dotnet/area-system-runtime See info in area-owners.md if you want to be subscribed.

Issue Details
### Background and motivation `Environment.SpecialFolder` has two enum names that map to the same underlying enum value `MyDocuments` and `Personal`. https://github.com/dotnet/runtime/blob/62140229d9e222eb326e18207d166209330b2194/src/libraries/System.Private.CoreLib/src/System/Environment.SpecialFolder.cs#L30-L31 This is rather confusing, and also leads to bugs because consumers wrongly believe that `Environment.SpecialFolder.Personal` really means `Environment.SpecialFolder.UserProfile`. Further, with https://github.com/dotnet/runtime/pull/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: * https://github.com/dotnet/maui/pull/10098 and https://github.com/dotnet/Microsoft.Maui.Graphics.Controls/pull/124 * https://github.com/xamarin/xamarin-android-tools/pull/194 * https://github.com/RicoSuter/Namotion.Reflection/pull/121 ### API Proposal ```diff 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_
Author: eerhardt
Assignees: -
Labels: `api-suggestion`, `area-System.Runtime`
Milestone: -