Where Should I Store my Data and Configuration Files if I Target Multiple OS Versions?

  • [アーティクル]

Over the past few releases of Windows, you may have noticed common folder locations have moved around a bit.  What should you do if you want your code to target multiple OS’s? Perhaps you are updating an application from XP to Windows 7 and wondering where those old directories went. Hopefully, this post will answer those questions and help you design your application to continue to work with future OS releases.

Where to store application files depends on how that data is used by the application and the user. Here is a table to outline the recommended locations for user documents and configuration data.  I’ve mapped the locations across OS’s in this giant table for comparison. UPDATE: The table was a little too giant for the new MSDN template. I’ve reformatted the information into sections:

Per user configuration files synchronized across domain joined machines via Active Directory Roaming

Configuration data files that the application uses and are unique per user. This per user data is synchronized across the domain via Active Directory.

Example: MyAppSettings.xml
Windows 7: %USERPROFILE%\AppData\Roaming\<MyCompany>\<MyApp>
Vista: %USERPROFILE%\AppData\Roaming\<MyCompany>\<MyApp>
XP: %USERPROFILE%\Application Data\<MyCompany>\<MyApp>
Environment Variable: %APPDATA%
Known Folder ID: FOLDERID_RoamingAppData
System.Environment.SpecialFolder: System.Environment.SpecialFolder.ApplicationData
CSIDL: CSIDL_APPDATA

 

Local per user configuration files

Configuration data files that the application uses and is unique per user.  It stays local to the individual machine and is not synchronized via Active Directory.

Example: MyMachineSpecificData.xml
Windows 7: %USERPROFILE%\AppData\Local\<MyCompany>\<MyApp>
Vista: %USERPROFILE%\AppData\Local\<MyCompany>\<MyApp>
XP: %USERPROFILE%\Local Settings\Application Data\<MyCompany>\<MyApp>
Environment Variable: %LOCALAPPDATA%  Note: Does not exist on XP
Known Folder ID: FOLDERID_LocalAppData
System.Environment.SpecialFolder: System.Environment.SpecialFolder.LocalApplicationData
CSIDL: CSIDL_LOCAL_APPDATA

 

Per machine configuration data

Configuration data files the application uses and is per machine. It is used across all users of the application.

Example: AppConfigDatabase.xml
Windows 7: %SystemDrive%\ProgramData\MyCompany\MyApp
Vista: %SystemDrive%\ProgramData\MyCompany\MyApp
XP: %SystemDrive%\Documents and Settings\All Users\Application Data
Environment Variable: Vista/Win7: %PROGRAMDATA%  XP: %ALLUSERSPROFILE%
Known Folder ID: FOLDERID_ProgramData
System.Environment.SpecialFolder: System.Environment.SpecialFolder.CommonApplicationData
CSIDL: CSIDL_COMMON_APPDATA

 

Per user “Documents”

“Document” type files that users create/open/close/save in the application that are per user.

Example: MyDoc.doc
Windows 7: Libraries
Vista: %USERPROFILE%\Document
XP: %USERPROFILE%\My Documents
Environment Variable: Not applicable
Known Folder ID: FOLDERID_Documents
System.Environment.SpecialFolder: System.Environment.SpecialFolder.MyDocuments
CSIDL: CSIDL_MYDOCUMENTS, CSIDL_PERSONAL

 

Per Machine “Documents”

“Document” type files that users create/open/close/save in the application that are used across users.  These are usually template or public documents.

Example: MyTemplate.dot
Windows 7: C:\Users\Public
Vista: %SystemDrive%\Users\Public
XP: %ALLUSERSPROFILE%\Documents
Environment Variable: Vista/Win7: %PUBLIC%  Note: Does not exist on XP
Known Folder ID: FOLDERID_PublicDocuments
System.Environment.SpecialFolder: System.Environment.SpecialFolder.CommonDocuments
CSIDL: CSIDL_COMMON_DOCUMENTS

It’s obvious after looking at all these locations that where you store your files can be challenging if you are targeting multiple OS versions.  The best guidance is to use API’s to find the special folder path.  API’s will return the appropriate location for the target OS.

Targeting Vista and Higher

Native Code

The best API to use if you are targeting Vista and beyond is the new SHGetKnownFolderPath. This function replaces SHGetFolderPath and has the following advantages.

Example:

// Roaming AppData - Vista and greater

if(SUCCEEDED(SHGetKnownFolderPath ( FOLDERID_RoamingAppData, KF_FLAG_CREATE,

                                    NULL, &wszPath )))

{

    printf("\nSHGetKnownFolderPath FOLDERID_RoamingAppData =%S\n", wszPath);

}

// Per user Documents - Vista and greater    

if(SUCCEEDED(

SHGetKnownFolderPath ( FOLDERID_Documents, KF_FLAG_CREATE, NULL, &wszPath )))

 

{ printf("SHGetKnownFolderPath FOLDERID_Documents =%S\n", wszPath);

}

 

The output on Windows 7 is:

SHGetKnownFolderPath FOLDERID_RoamingAppData =C:\Users\patricka\AppData\Roaming

SHGetKnownFolderPath FOLDERID_Documents =\\zaw\Mydocs\patricka\My Documents

Managed Code

You can use System.Environment.SpecialFolder along with the System.Environment.GetFolderPath function to get the path.

Example:

// Roaming Application Data – C#

SpecialFolderPath = System.Environment.GetFolderPath(

                              System.Environment.SpecialFolder.ApplicationData);

Console.WriteLine("SpecialFolder.ApplicationData path ={0}", SpecialFolderPath);

// Per user Documents

SpecialFolderPath = System.Environment.GetFolderPath(

                              System.Environment.SpecialFolder.MyDocuments);

Console.WriteLine("SpecialFolder.MyDocuments path ={0}", SpecialFolderPath);

The output on Windows 7 is:

SpecialFolder.ApplicationData path =C:\Users\patricka\AppData\Roaming

SpecialFolder.MyDocuments path =\\zaw\Mydocs\patricka\My Documents

 

Note that the path for Documents returns my redirected IntelliMirror server path because I ran it on a domain joined machine and my domain account is IntelliMirror enabled.

Targeting XP and Higher

Native Code

If you are still targeting XP, you’ll need to use the legacy API SHGetFolderPath that uses CSIDL’s.  This API is still supported in Vista and Windows 7 and will map to the correct locations on all three versions of the OS.

Example:

// Roaming AppData – Legacy

if(SUCCEEDED(SHGetFolderPath(NULL, CSIDL_APPDATA|CSIDL_FLAG_CREATE, NULL, 0, szPath))) { printf("\nSHGetFolderPath CSIDL_APPDATA =%S\n", szPath); }

 

// Per user documents (My Documents) - Legacy

if(SUCCEEDED(SHGetFolderPath(NULL, CSIDL_MYDOCUMENTS|CSIDL_FLAG_CREATE, NULL, 0, szPath))) { printf("\nSHGetFolderPath CSIDL_MYDOCUMENTS =%S\n", szPath); }

 

The output on Windows 7 is:

SHGetFolderPath CSIDL_APPDATA =C:\Users\patricka\AppData\Roaming

SHGetFolderPath CSIDL_MYDOCUMENTS =\\zaw\Mydocs\patricka\My Documents

The output on XP is:

SHGetFolderPath CSIDL_APPDATA =C:\Documents and Settings\XPMUser\Application Data

SHGetFolderPath CSIDL_MYDOCUMENTS =C:\Documents and Settings\XPMUser\My Documents

The API returns the appropriate path for the given OS version. Please note: I ran this in XP Mode on Windows 7. My XP Mode machine was not domain joined; therefore, I did not get IntelliMirror redirection.

Managed Code

Since we are using the .NET framework, we can still use the same technique as described in the previous section. We saw the output for Windows 7. Here’s the output we get on XP:

SpecialFolder.ApplicationData path =C:\Documents and Settings\XPMUser\Application Data

SpecialFolder.MyDocuments path =C:\Documents and Settings\XPMUser\My Documents

Similar to the native API’s, we get the appropriate location for XP. Again, because my XP Mode virtual machine was not domain joined, there is no IntelliMirror redirection.

Final Thoughts

Think about the type of files your application is writing.  Are they configuration files, data files, or documents? Are they per machine or per user? Choose the appropriate location for the file type and then use the right API to get the path to that location. Chris has a great post on this topic. There is also a support article and a whitepaper that has good info on storing application data.

Comments

  • Anonymous
    September 08, 2010
    Per machine configuration data - The Folder "%SystemDrive%ProgramDataMyCompanyMyApp " for Windows 7 is READONLY for non admin users. If I am looking for a location for read / write access, what should I use?

  • Anonymous
    September 09, 2010
    Great question.  This is a common question and I'm glad you brought it up.  ProgramData is the recommended location for per machine configuration data.  As you point out, by default, BUILTINUsers will only have RX. If you have a requirement for standard users to be able to write to the file, you will need to grant that permission.  The best time to do this is during install time.  Installers normally run elevated and can set any folder permissions.  You could also grant Users write permission just after you create the file.  The user who created the file should be able to grant Users write permission as well. You can think of the subdirectory ProgramDataMyCompanyMyApp as "your directory" to do as you please for per machine data. Feel free to set the permissions as needed (obviously replacing MyCompany and MyApp with the appropriate values). One other note, I don't talk about registry in this post.  However, you can apply the same rules to the registry. HKCUSoftwareMyCompanyMyApp for per user settings and HKLMSoftwareMyCompanyMyApp for per machine settings. If you need standard users to write to HKLMSoftwareMyCompanyMyApp, you will need to grant that permission -- normally at install time. Thanks for reading :-) Pat

  • Anonymous
    June 19, 2011
    Are the examples for 'Per Machine “Documents”' correct? On Windows 7, I get "C:UsersPublicDocuments" (aka "C:UsersPublicPublic Documents") -dave

  • Anonymous
    November 15, 2013
    Thanks, this info is harder to find than it should be. Have things changed (again) with Windows 8?

  • Anonymous
    January 05, 2014
    I agree with you Dave Gardiner, I think it's a typo in the article.  The "Per Machine" Documents folder on Win7 I believe is "C:UsersPublicDocuments", and the article states that it's "C:UsersPublic"

  • Anonymous
    January 07, 2014
    I'm also getting a discrepancy on our old windows Xp machine. %ALLUSERSPROFILE% takes me to %SystemDrive%Documents and SettingsAll Users as opposed to %SystemDrive%Documents and SettingsAll UsersApplication Data mentioned in your post