[API Proposal]: Extend System.Environment.SpecialFolder to include newer common folders

[RayKoopa]

Background and motivation

System.Environment.GetFolderPath is used to query paths to known folders like the user's file folders ("Documents", "Pictures", etc.). The paths to these folders can be redirected in system configuration, which is queried by this method. To use it, a value of the System.Environment.SpecialFolder enum is passed in to query the accompanying folder:

using System;

string videosPath = Environment.GetFolderPath(Environment.SpecialFolder.MyVideos);

However, this enum only provides folders that were available in Windows XP days, and does not contain entries for nowadays commonly available personal folders, leaving a "hole" in support for those introduced in Windows Vista or other platforms like Linux and macOS (for example, the user "Downloads" folder).

It is currently required to manually p/invoke the WinAPI or rewrite the existing Linux / macOS folder retrieval logic to ensure getting correct paths. Adding support for these folders via extending the enum will provide a natural and expected way to retrieve these paths from the system configuration without having to go through all that.

Judging from forum discussions, it will also prevent users from "solving" this issue incorrectly by hardcoding and concatenating parts of the folder paths (which would not reflect any redirected paths stored in system configuration) or incorrectly p/invoking system methods themselves:

• Stack Overflow - How to programmatically derive Windows Downloads folder "%USERPROFILE%/Downloads"? and many linked / duplicate questions
• MSDN Forum - How do I determine the Windows 'Download folder' path using the KnownFolders class?

There have also been several issues requesting the missing folders in the past, but most staled or haven't been tackled since long:

• 2015-10-12 Complete Environmment.SpecialFolder #15419 (Issue)
  • about extending SpecialFolder, first mention of new (but internal) GUID based API
• 2016-10-12 Fix SpecialFolder.MyDocuments to map to XDG properly in Unix corefx#12575
  • mentions deprecating the whole SpecialFolder API in favor of a new, public GUID based API:
    • extending the SpecialFolder enum in any way would break code assuming it maps to deprecated Windows' CSIDLs
    • updating it in the future may not be flexible enough
• 2016-10-21 Add a more flexible special folder API #19047 (API Proposal)
  • proposes said API, dropped by proposer due to missing interest
• 2018-03-22 Environment.SpecialFolder should expose FOLDERID_Downloads and FOLDERID_Public values #25577 (API Proposal)
  • about extending SpecialFolder again
• 2018-06-13 Support other known paths dotnet-api-docs#791 (Issue)
  • about extending SpecialFolder again
• 2019-05-12 Environment.GetFolderPath() doesn't support all KNOWNFOLDERID's #554 (Issue)
  • about extending SpecialFolder again

API Proposal

I propose extending the System.Environment.SpecialFolder enum with these values:

SpecialFolder	Windows	macOS	iOS	Linux (with XDG)	Linux
MyDownloads	FOLDERID_Downloads	~/Downloads	NSDocumentDirectory/Downloads	XDG_DOWNLOAD_DIR	~/Downloads
MySavedGames	FOLDERID_SavedGames	-	-	-	-
Public	FOLDERID_Public	~/Public	-	XDG_PUBLICSHARE_DIR	~/Public
PublicDesktop	FOLDERID_PublicDesktop	-	-	-	-
PublicDocuments	FOLDERID_PublicDocuments	-	-	-	-
PublicDownloads	FOLDERID_PublicDownloads	-	-	-	-
PublicMusic	FOLDERID_PublicMusic	-	-	-	-
PublicPictures	FOLDERID_PublicPictures	-	-	-	-
PublicVideos	FOLDERID_PublicVideos	-	-	-	-

• The underlying values are added starting with 0x10000 due to the undocumented fact that the existing values map to Windows' CSIDLs, and 0x10000 is the first invalid CSIDL combination that would not clash.

  • The CSIDL API is deprecated, not used by .NET anymore, and does not allow querying the folders above anyway.

• ~ is the home directory as it is already determined.

• XDG... variables are used on Linux if they exist, otherwise the non-XDG path is used as a fallback.

• The public (sub) folder is per-system on Windows, and per-user on Linux and macOS. iOS has no such folders.

  • Adding Public... sub folders is required for Windows as they may be redirected outside of the parent PublicDirectory. Otherwise it could lead to developers looking for them to incorrectly hardcode parts of their path again by assuming they are children (the same issue currently with the Downloads and Public folders themselves).

• User folders are prefixed with My as it is currently the case for other user folders like MyPictures or MyDocuments, so that related folders group together more clearly in the enum.

  • MySavedGames is included as it is the only remaining Windows user folder meaningful to developers. While there are other user folders available on Windows, I do not recommend adding as they have a very special meaning only to one Windows app / component:

    SpecialFolder	Windows only	Used by / meant for
    ❌ MyContacts	FOLDERID_Contacts	Windows Contacts contact files.
    ❌ MyLinks	FOLDERID_Links	File Explorer pinned location shortcut files (< Windows 10 only).
    ❌ MySearches	FOLDERID_Searches	Parameterized Windows Search query files.

• Folders that do not exist on specific platforms will return String.Empty as they already do for others.

• VB.NET's SpecialDirectories class will not be extended as it is understood to be a utility class for VB6-style backwards compatibility.

API Usage

The usage naturally extends the options made available through the existing enum:

using System;

string downloadsPath = Environment.GetFolderPath(Environment.SpecialFolder.MyDownloads);
string publicPath = Environment.GetFolderPath(Environment.SpecialFolder.Public);
string savedGamesPath = Environment.GetFolderPath(Environment.SpecialFolder.MySavedGames);

Alternative Designs

• A completely new API available additionally to the existing System.Environment.GetFolderPath (and possibly deprecating it) to make extending special folders more flexibly in the future was discussed at Add a more flexible special folder API #19047, but abandoned.
• Alternatively, a new enum KnownFolder could be introduced if the existing SpecialFolder should not be touched in any case (s. possible "Risks" below), and an overload could be provided for System.Environment.GetFolderPath accepting those.

Risks

I rate the risks as Low:

• Code that enumerated over all values of the SpecialFolder enum and depended on the undocumented fact that each underlying value is a Windows CSIDL value now has to check whether the value is < 0x10000 in case it wants to pass only valid values to the deprecated CSIDL Windows API.
• Code that relied on the undocumented fact that the enum values could be stored in just 2 bytes now has to use a larger data type or ignore the new values with the < 0x10000 check.

The additions here should be merged after fixes to existing paths are done in #68610 to not clash with the changes.

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

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

System.Environment.GetFolderPath is used to query paths to known folders like the user's file folders ("Documents", "Pictures", etc.). The paths to these folders can be redirected in system configuration, which is queried by this method. To use it, a value of the System.Environment.SpecialFolder enum is passed in to query the accompanying folder:

using System;

string videosPath = Environment.GetFolderPath(Environment.SpecialFolder.MyVideos);

However, this enum only provides folders that were available in Windows XP days, and does not contain entries for nowadays commonly available personal folders, leaving a "hole" in support for those introduced in Windows Vista or other platforms like Linux and macOS (for example, the user "Downloads" folder).

It is currently required to manually p/invoke the WinAPI or rewrite the existing Linux / macOS folder retrieval logic to ensure getting correct paths. Adding support for these folders via extending the enum will provide a natural and expected way to retrieve these paths from the system configuration without having to go through all that.

Judging from forum discussions, it will also prevent users from "solving" this issue incorrectly by hardcoding and concatenating parts of the folder paths (which would not reflect any redirected paths stored in system configuration) or incorrectly p/invoking system methods themselves:

• Stack Overflow - How to programmatically derive Windows Downloads folder "%USERPROFILE%/Downloads"? and many linked / duplicate questions
• MSDN Forum - How do I determine the Windows 'Download folder' path using the KnownFolders class?

There have also been several issues requesting the missing folders in the past, but most staled or haven't been tackled since long:

• 2015-10-12 Complete Environmment.SpecialFolder #15419 (Issue)
  • about extending SpecialFolder, first mention of new (but internal) GUID based API
• 2016-10-12 Fix SpecialFolder.MyDocuments to map to XDG properly in Unix corefx#12575
  • mentions deprecating the whole SpecialFolder API in favor of a new, public GUID based API:
    • extending the SpecialFolder enum in any way would break code assuming it maps to deprecated Windows' CSIDLs
    • updating it in the future may not be flexible enough
• 2016-10-21 Add a more flexible special folder API #19047 (API Proposal)
  • proposes said API, dropped by proposer due to missing interest
• 2018-03-22 Environment.SpecialFolder should expose FOLDERID_Downloads and FOLDERID_Public values #25577 (API Proposal)
  • about extending SpecialFolder again
• 2018-06-13 Support other known paths dotnet-api-docs#791 (Issue)
  • about extending SpecialFolder again
• 2019-05-12 Environment.GetFolderPath() doesn't support all KNOWNFOLDERID's #554 (Issue)
  • about extending SpecialFolder again

API Proposal

I propose extending the System.Environment.SpecialFolder enum with these values:

SpecialFolder	Windows	macOS	iOS	Linux (with XDG)	Linux
Downloads	FOLDERID_Downloads	~/Downloads	NSDocumentDirectory/Downloads	XDG_DOWNLOAD_DIR	~/Downloads
PublicDirectory	FOLDERID_Public	~/Public	-	XDG_PUBLICSHARE_DIR	~/Public
PublicDesktop	FOLDERID_PublicDesktop	-	-	-	-
PublicDocuments	FOLDERID_PublicDocuments	-	-	-	-
PublicDownloads	FOLDERID_PublicDownloads	-	-	-	-
PublicMusic	FOLDERID_PublicMusic	-	-	-	-
PublicVideos	FOLDERID_PublicVideos	-	-	-	-
SavedGames	FOLDERID_SavedGames	-	-	-	-

• The underlying values are added starting with 0x10000 due to the undocumented fact that the existing values map to Windows' CSIDLs, and 0x10000 is the first invalid CSIDL combination that would not clash.

  • The CSIDL API is deprecated, not used by .NET anymore, and does not allow querying the folders above anyway.

• ~ is the home directory as it is already determined.

• XDG... variables are used on Linux if they exist, otherwise the non-XDG path is used as a fallback.

• The Public folder is named PublicDirectory to not clash with keywords (e.g. VB.NET).

  • The public (sub) folder is per-system on Windows, and per-user on Linux and macOS. iOS has no such folders.
  • Adding Public... sub folders is required for Windows as they may be redirected outside of the parent PublicDirectory. Otherwise it could lead to developers looking for them to incorrectly hardcode parts of their path again by assuming they are children (the same issue currently with the Downloads and Public folders themselves).

• SavedGames is included as it is the only remaining Windows user folder meaningful to developers. While there are other user folders available on Windows, I do not recommend adding as they have a very special meaning only to one Windows app / component:

  SpecialFolder	Windows only	Used by / meant for
  ❌ Contacts	FOLDERID_Contacts	Windows Contacts contact files.
  ❌ Links	FOLDERID_Links	File Explorer pinned location shortcut files (< Windows 10 only).
  ❌ Searches	FOLDERID_Searches	Parameterized Windows Search query files.

• Folders that do not exist on specific platforms will return String.Empty as they already do for others.

API Usage

The usage naturally extends the options made available through the existing enum:

using System;

string downloadsPath = Environment.GetFolderPath(Environment.SpecialFolder.Downloads);
string publicPath = Environment.GetFolderPath(Environment.SpecialFolder.PublicDirectory);
string savedGamesPath = Environment.GetFolderPath(Environment.SpecialFolder.SavedGames);

Alternative Designs

• A completely new API available additionally to the existing System.Environment.GetFolderPath (and possibly deprecating it) to make extending special folders more flexibly in the future was discussed at Add a more flexible special folder API #19047, but abandoned.
• Alternatively, a new enum KnownFolder could be introduced if the existing SpecialFolder should not be touched in any case (s. possible "Risks" below), and an overload could be provided for System.Environment.GetFolderPath accepting those.

Risks

I rate the risks as Low:

• Code that enumerated over all values of the SpecialFolder enum and depended on the undocumented fact that each underlying value is a Windows CSIDL value now has to check whether the value is < 0x10000 in case it wants to pass only valid values to the deprecated CSIDL Windows API.
• Code that relied on the undocumented fact that the enum values could be stored in just 2 bytes now has to use a larger data type or ignore the new values with the < 0x10000 check.

The additions here should be merged after fixes to existing paths are done in #68610 to not clash with the changes.

Author:	RayKoopa
Assignees:	-
Labels:	api-suggestion, area-System.Runtime, untriaged
Milestone:	-

[RayKoopa]

Question 1:
Should the enum entries Downloads and SavedGames be named MyDownloads and MySavedGames, to be in line with the already existing MyDocuments, MyMusic, MyVideos, and MyPictures entries, indicating they're about the current user's special folders - or should we bury this "My" prefix as a Win2k / XP twist on those folder names that was not actually used for these new folders? Keeping it will also make code grouping user folders near each other if alphabetically sorted.

Question 2:
I intended to name the entry for the "Public" shared folder PublicDirectory to not clash with language keywords. I mainly thought about VB.NET here, but just tested that the compiler is actually able to differentiate between the keyword and the usage as SpecialFolder.Public without any syntax errors. Should I scrap the Directory suffix to make the enum look a little cleaner or keep it for safety? IMHO scrap it, as we also decided to not extend the VB.NET specific Microsoft.VisualBasic.FileIO.SpecialDirectories class, but I don't know about other supported languages.

[Rubidium37]

Question 1: Should the enum entries Downloads and SavedGames be named MyDownloads and MySavedGames, to be in line with the already existing MyDocuments, MyMusic, MyVideos, and MyPictures entries, [...]

Consistency is a good thing.
I would either:

1. Prefix with "My" as it is the same prefix for other related elements (and it aids to distinguish/group related/unrelated elements).
2. Adopt "User" instead of "My", even in the existing related elements, in order to make their context explicit and distinguish them more clearly from "Public" elements.

[RayKoopa]

Consistency is a good thing. I would either:

1. Prefix with "My" as it is the same prefix for other related elements (and it aids to distinguish/group related/unrelated elements).
2. Adopt "User" instead of "My", even in the existing related elements, in order to make their context explicit and distinguish them more clearly from "Public" elements.

I agree with option 1, and it feels a lot cleaner having it added as MyDownloads and MySavedGames.
I would not go with option 2. Despite preferring a User prefix myself, introducing new values with same meaning / deprecating old ones / replacing old ones and breaking existing code doesn't seem worth it just for a rename and may cause more confusion than being helpful.

[AraHaan]

Also since Windows 10, people can move certain user folders (which are SpecialFolder's) to the onedrive folder located in their user profile.

[akoeplinger]

Given all the values starting from PublicDesktop and MySavedGames only work on Windows I'd suggest prefixing them with Windows so that it's clear it only works there. Or we need to come up with sensible folder paths for those.

[AraHaan]

I would come up with defaults for those when not on Windows, it would be simpler that way.