Why is there the message ‘!Do not use this registry key’ in the registry?


Under Software\Microsoft\Windows\Current­Version\Explorer\Shell Folders, there is a message to registry snoopers: The first value is called “!Do not use this registry key” and the associated data is the message “Use the SH­Get­Folder­Path or SH­Get­Known­Folder­Path function instead.”

I added that message.

The long and sad story of the Shell Folders key explains that the registry key exists only to retain backward compatibility with four programs written in 1994. There’s also a TechNet version of the article which is just as sad but not as long.

One customer saw this message and complained, “That registry key and that TechNet article explain how to obtain the current locations of those special folders, but they don’t explain how to change them. This type of woefully inadequate documentation only makes the problem worse.”

Hey, wow, a little message in a registry key and a magazine article are now “documentation”! The TechNet article is historical background. And the registry key is just a gentle nudge. Neither is documentation. It’s not like I’m going to put a complete copy of the documentation into a registry key. Documentation lives in places like MSDN.

But it seems that some people need more than a nudge; they need a shove. Let’s see, we’re told that the functions for obtaining the locations of known folders are SH­Get­Folder­Path and its more modern counterpart SH­Get­Known­Folder­Path. I wonder what the names of the functions for modifying those locations might be?

Man that’s a tough one. I’ll let you puzzle that out for a while.

Okay, here, I’ll tell you: The corresponding functions go by the completely unobvious names SH­Set­Folder­Path and SH­Set­Known­Folder­Path.

Sorry you had to use your brain. I’ll let you get back to programming now.

Comments (40)
  1. Jim Lyon says:

    "One customer saw this message and complained…"

    Some people just like to complain, as if it shows how smart they are (or something). I'd wager that the customer knew the answer before writing the complaint.

  2. MarcBernard says:

    Now a blog post is documentation!  :)

  3. Larry Hosken says:

    As a professional editor, I think you need a function whose purpose is to not-change the locations of the known folders, SH­StetKnown­Folder­Path.

  4. Adam Rosenfield says:

    And the hive that that key can be found under is HKEY_CURRENT_USER (and HKEY_USERS/<SID> for each user).

  5. laonianren says:

    When was it publicly documented?  ShSetFolderPath isn't in the 2003 SDK and the 2007 Vista SDK post-dates your technet article by more than a year.  It wasn't always so obvious.

  6. Danny Moules says:

    "Sorry you had to use your brain. I'll let you get back to programming now."

    I just scrolled down and read the answer, completely ignoring your instructions in the hope of finding an easier approach. No apology needed!

  7. Joshua Ganes says:

    Some people use their brains in all kinds of unnecessary situations. I save my brain for when real deciding power is required.

  8. Joshua says:

    The reason for this continuing madness is some things that cannot officially be moved need to be moved, such as C:Users.

    Users home directories do not belong on the system volume on servers. Why is this so hard to grasp?

  9. Simon Farnsworth says:

    @Joshua Why can't you use a Windows Mount Point (support.microsoft.com/…/307889) to have C:Users be somewhere else?

  10. jader3rd says:

    Is it time to get rid of/update those four programs and then remove the registry key?

    [As I noted in the base article, those programs almost certainly don't exist any more. But in the time it took those four programs to die out, tens of thousands of new programs took their place. -Raymond]
  11. jader3rd says:

    "those programs almost certainly don't exist any more. But in the time it took those four programs to die out, tens of thousands of new programs took their place. -Raymond"

    If tens of thousands of programs are relying on a reg key, that has a value of "Do Not Use", I wouldn't feel sorry for them at all, should the registry key dissapear in a subsequent version of Windows.

    [But would you feel sorry for their customers? -Raymond]
  12. AndyC says:

    @Joshua – Roaming Profiles and Folder Redirection have been in Windows for decades now, and yet some people still seem to think they need to achieve this by moving the Users (or equivalent) folders. I fear I may have accidentally engaged my brain for a moment, sorry about that!

  13. Joshua says:

    @Simon: It turns out the Local System, Local Service, and Network Service users must be present on the system drive or updates fail to apply.

    @AndyC: Roaming profiles does not work in the very situation where this is most necessary.

  14. Antonio Rodríguez says:

    Do SH­Get­Folder­Path and SH­Set­Folder­Path work together? Don't you tell me! I always thought the counterpart of SH­Get­Folder­Path was SetWindowPos or something! And you are asking us to actually think to guess the answer? It's easier to fire RegEdit and do a search, or simply hardcode "C:WindowsMy documents" (which woks in the English version of Windows 98, so it should work in every other version until the end of time).

    The sad part is that sometimes other programmers try to make me a fool for playing fair and using things like SH­Get­Folder­Path instead of doing it the easy way… It's no wonder every new release of Windows breaks thousands of applications, no matter how hard you try to maintain compatibility… :-(

  15. Kyle S. says:

    [But would you feel sorry for their customers? -Raymond]

    Nope.

    [Their customers are your customers. Oh, and you're probably a customer and don't even realize it. -Raymond]
  16. Maurits says:

    ++ reasons for a "strict mode" switch that developers can write applications against (chk, app verifier, driver verifier, compat hacks disabled)

    [That world already exists: chk, app verifier, driver verifier, disable compatibility shims with the ACT. Has that stopped people from relying on undocumented behavior? -Raymond]
  17. Gabe says:

    Unfortunately, the use of the initial exlamation point will be interpreted by some as a unary not operator, thus inverting the sense of it to mean "Use this registry key".

    Larry Hosken: Subtle, very subtle!

  18. Ifeanyi Echeruo says:

    @Kyle S. Good luck with that whole "staying in business by getting customers to buy the next version of your product" thing

  19. David Brooks says:

    Does the absence of the warning in the HKLM branch of that key mean that I can… just kidding.

  20. Ben says:

    @Joshua: You mean the pseudo-users that Windows uses as the contexts for all the important system processes need to be present on the machine even if the network or a non system drive fails? Shock! Horror!

  21. Maurits says:

    Has that stopped people from relying on undocumented behavior?

    Some people.

  22. TheASMan says:

    for internet zie pane (cnat comment on it even tho I just read it.

    [Everything is a compatibility constraint. There may be an app that queries the file sizes from Explorer and relies on the current algorithm. (E.g., it does "atoi" of the string and assumes it's in KB.) -Raymond]

    Why dont you with the api by default give in KB with a new API to get in whatever size you wish and in the display show it like details.

    [The API returns a byte count. But that's not the API they're using to get the value. They're using the "scrape it from the screen" API. -Raymond]
  23. JonPotter says:

    "Hey, wow, a little message in a registry key and a magazine article are now "documentation"!"

    Given the state/level of Microsoft's documentation these days, you're doing pretty well if you can get a registry key and a magazine article about something.

  24. John Muller says:

    Just yesterday I found a bit of (test automation) source code that goes to those keys to get paths, and was tempted to change it… but decided against it as it works now and the test code (and the product it tests) run only on Windows Seven. Maybe in honor of your post I will change it, so that the test code will better port to the next version of Windows.

    I know this is 'Not actually a .net blog' but for the benefit of people who get here by search engine, the relevant .net API is the System.Environment.SpecialFolder Enumeration

  25. Cheong says:

    @Joshua: Beginning with Vista, they've introduced UI for moving user "Known Folders" to another location (Just right-click a folder there -> properties -> Location). Not even mount point is needed.

    Granted the main user profile is still on system drive, you need not concern about user files may somehow make your system drive clogged up with videos or musics… :P

  26. Cheong says:

    John: Speaking of that… I just found the subtitle of the blog is missing. It's strange because Michael Kaplan's blog still have that there.

  27. Joshua says:

    I know this is wildly diverging. I will use checked builds the day automatic updates work for them. Yes, this means Microsoft has to host a second copy of all the updates. It can't be that hard; its just build options.

  28. Troll says:

    "Beginning with Vista, they've introduced UI for moving user "Known Folders" to another location (Just right-click a folder there -> properties -> Location). Not even mount point is needed"

    @Cheong, actually this UI was present in XP as well. It's the "Target" tab if you go to the Properties of the My Documents namespace in Explorer or the desktop. In XP, all the other folders like Downloads, My Music, My Videos, My Pictures, Saved Games being contained inside the "My Documents" folder, it was enough and simple to just move "My Documents". The rest of the special folders like Desktop, Favorites could be moved using TweakUI. With Vista, you have to do it separately for each folder but it does give the flexibility of moving only certain folders to other locations. Hope Microsoft does not take away the location tab just because Windows 7 now has libraries.

  29. Good idea, bad psychology. The warning is correct, but it is too easy to miss. In the next Windows version, please make it say

    !!!!DO NOT USE THIS REGISTRY KEY!!!!!!!!!!!!!!111111111111111111

    Now THAT will show them. For specific values of 'them'. Namely, excluding 90% of 'them' who just copy the routine from some old project.

    Oh, and this also solves Gabe's inversion problem.

  30. Vilx- says:

    A cookie for you if you just opened regedit just to see if that key is really there!

  31. Louis Pace says:

    I'm just curious – what were the four programs?

    [Read the linked article. -Raymond]
  32. AsmGuru62 says:

    Let's see: what programs PC cannot be sold with? My guess – one of these programs was X – no doubt.

    [Hey, AsmGuru62, you should know better than to violate the ground rules: No guessing. (And only programs designed for Windows 95 could have this dependency, so your old program clearly is a wrong guess anyway.) -Raymond]
  33. hmm says:

    So I should just delete this key if it isn't used to save disk space?

  34. JustSomeGuy says:

    Actually, I *had* to use my brain. I was unsure whether it would be SH­Set­Folder­Path or SH­PutFolder­Path.

  35. jader3rd says:

    @hmm

    Deleting registry keys doesn't save disk space, because the registry never compresses itself. You get more bang for your buck by having the registry take up less memory (since it's loaded into memory) than you would by having it take up less disk space. So deleting it will probably not add any value to your system (unless you then run a registry cleaner and a bunch of them do compress the registry).

    So the best way for all of us to have to deal with these undesirable bytes being loaded into memory everytime we turn on our computers, is to have Windows not create the registry key when installing the OS.

  36. mh says:

    I think hmm might have been pulling your leg a little.

    SH­Set­Folder­Path or SH­PutFolder­Path – "SHLetFolderPath", anybody?  Brrrrrr.

  37. RCIX says:

    Is it just me or is Raymond getting a bit snarkier lately?

  38. @RCIX says:

    No, he isn't. Although because of idiots like Norman Diamond and some other regular trolls hes stopped being as free with his opinion as he used to ~5 years ago.

  39. ErikF says:

    I have a question about stuff like this: do the localized versions of Windows translate these weird, out of the way resources?  My guess is "no," but I don't have a localized copy of Windows to look at right now.  If the answer is "yes," then I don't want to imagine the amount of work needed to get everything translated!

  40. Richard Gadsden says:

    The HKLM version of the same registry key doesn't have the warning.  Does that mean it's OK to use it?

Comments are closed.