Client Settings FAQ
One of the cool new features in .NET 2.0/VS 2005 is an easy to use, extensible API to manage application/user settings, i.e., data that needs to be persisted across runs of a client application. You can find more information about this feature on MSDN or in my earlier blog posts on this topic.
While the feature is easy to use in general, we often get questions from users trying more advanced scenarios about why a certain aspect of the feature works in a particular way or how to customize some behavior. The answers to these questions are generally in the MSDN docs, but can sometimes be hard to find. I thought it would be useful to cover this information in a FAQ for easy future reference. I will be updating the FAQ as and when there are more questions to add.
Q: I notice there are two kinds of settings - application scoped and user scoped. Application scoped settings seem to be read-only and I cannot change them at runtime. Why is that?
A: There are two main types of settings that applications generally want to store: (1) certain data like connection strings and web references that don't change often, but should be possiblep for an admin to change and therefore cannot be hardcoded into the application and (2) user preferences and customization that can change any time. Application scoped settings are useful in scenario (1) and user scoped settings, in the latter. They are essentially read only from tche application's point of view and aren't meant to be changed by the user, but admins could go and edit the file if they want to. An additional reason for this has to do with how the default SettingsProvider stores settings - application scoped settings go in the exe configuration file and user scoped settings in user.config files located in the user data path. Generally, exe config files shouldn't be written to at runtime by the application, since the user may not have access to them (if the application is installed in c:\Program Files\..., only privileged users have access, for example). Even if they do, it is not usually a good idea for a user to control changing a file that affects every other user of the application.
Q: You said user.config files go in the user data path. How can I locate the file? Are there multiple files for an application or just one?
A: As mentioned before, the default SettingsProvider for client applications (called the LocalFileSettingsProvider) stores settings in the application configuration files. In .NET v1 and v1.1, there were two levels of config files - machine.config and app.exe.config (where 'app.exe' is the name of the application). In v2.0, we have added two more levels of configuration to store user specific data - one that goes in the roaming user profile path and another in the local user profile path. On XP, the profile directories would be something like 'c:\Documents and Settings\<username>\Application Data' and 'c:\Documents and Settings\<username>\Local Settings\Application Data' respectively. These directories are the recommended location (per Windows Logo requirements) for storing user specific information and most applications (like Outlook and Visual Studio) put user data somewhere under here.
The exact path of the user.config files looks something like this:
<Profile Directory>\<Company Name>\<App Name>_<Evidence Type>_<Evidence Hash>\<Version>\user.config
where
<Profile Directory> - is either the roaming profile directory or the local one. Settings are stored by default in the local user.config file. To store a setting in the roaming user.config file, you need to mark the setting with the SettingsManageabilityAttribute with SettingsManageability set to Roaming.
<Company Name> - is typically the string specified by the AssemblyCompanyAttribute (with the caveat that the string is escaped and truncated as necessary, and if not specified on the assembly, we have a fallback procedure).
<App Name> - is typically the string specified by the AssemblyProductAttribute (same caveats as for company name).
<Evidence Type> and <Evidence Hash> - information derived from the app domain evidence to provide proper app domain and assembly isolation.
<Version> - typically the version specified in the AssemblyVersionAttribute. This is required to isolate different versions of the app deployed side by side.
The file name is always simply 'user.config'.
If you want to get to the path programmatically, you can do it using the Configuration Management API (you need to add a reference to System.Configuration.dll). For example, here is how you can get the local user.config file path:
Configuration config = ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.PerUserRoamingAndLocal);
Console.WriteLine("Local user config path: {0}", config.FilePath);
Q: Why is the path so obscure? Is there any way to change/customize it?
A: The path construction algorithm has to meet certain rigorous requirements in terms of security, isolation and robustness. While we tried to make the path as easily discoverable as possible by making use of friendly, application supplied strings, it is not possible to keep the path totally simple without running into issues like collisions with other apps, spoofing etc.
The LocalFileSettingsProvider does not provide a way to change the files in which settings are stored. Note that the provider itself doesn't determine the config file locations in the first place - it is the configuration system. If you need to store the settings in a different location for some reason, the recommended way is to write your own SettingsProvider. This is fairly simple to implement and you can find samples in the .NET 2.0 SDK that show how to do this. Keep in mind however that you may run into the same isolation issues mentioned above .
Q: I deployed my application using Clickonce and saved some settings, but can't find the user.config file.
A: The path algorithm mentioned above is not used in the Clickonce case. Instead, the local user.config file goes in the Clickonce Data directory (the <Version> part of the path will still be included). There is no roaming user.config file for Clickonce applications.
Q: How are my strongly typed properties serialized as settings? I couldn't get the <insert type here> class to serialize correctly.
A: There are two primary mechanisms that ApplicationSettingsBase uses to serialize settings - (1) If a TypeConverter exists that can convert to and from string, we use it. (2) If not, we fallback to the XmlSerializer. While most common types can be serialized in one of these ways, there are some types that may not. In such cases, you have a few different options:
- Implement a TypeConverter for the type that can convert to and from string. The implementation can use a suitable serialization mechanism like one of the formatters/serializers that ship in the Framework or any custom mechanism you wish. You can then specify this converter on the type itself or on the property in your settings class.
- Specify a particular SettingsSerializeAs enum value using a SettingsSerializeAsAttribute. For example, if you wish to serialize a setting in binary format, simply specify SettingsSerializeAs.Binary.
Q: My application has a few user scoped settings, but I notice Visual Studio puts them in app.config. I thought they go in user.config files?
A: The configuration system is hierarchical and has this ordering: machine -> application -> roaming user -> local user. When you query a configuration section at any level, you get a merged view of the sections declared in that level and those below it (with machine being the lowest level and local user the highest). The section handler defines how the merge happens and for settings, a setting value specified in, say, local user config trumps the one specified in application config.
So for user scoped settings, you can think of the values specified in app.config to be install time defaults. When the settings are saved into user.config, those values will override these defaults. This way admins have the option of changing the defaults. Note that the defaults can also be specified by means of a DefaultSettingValueAttribute. The provider will use this value if no value is specified for a setting in any level of config.
Q: Why is there a version number in the user.config path? If I deploy a new version of my application, won't the user lose all the settings saved by the previous version?
A: There are couple of reasons why the user.config path is version sensitive. (1) To support side-by-side deployment of different versions of an application (you can do this with Clickonce, for example). It is possible for different version of the application to have different settings saved out. (2) When you upgrade an application, the settings class may have been altered and may not be compatible with what's saved out, which can lead to problems.
However, we have made it easy to upgrade settings from a previous version of the application to the latest. Simply call ApplicationSettingsBase.Upgrade() and it will retrieve settings from the previous version that match the current version of the class and store them out in the current version's user.config file. You also have the option of overriding this behavior either in your settings class or in your provider implementation.
Q: Okay, but how do I know when to call Upgrade?
A: Good question. In Clickonce, when you install a new version of your application, ApplicationSettingsBase will detect it and automatically upgrade settings for you at the point settings are loaded. In non-Clickonce cases, there is no automatic upgrade - you have to call Upgrade yourself. Here is one idea for determining when to call Upgrade:
Have a boolean setting called CallUpgrade and give it a default value of true. When your app starts up, you can do something like:
if (Properties.Settings.Value.CallUpgrade) {
Properties.Settings.Value.Upgrade();
Properties.Settings.Value.CallUpgrade = false;
}
This will ensure that Upgrade() is called only the first time the application runs after a new version is deployed.
Update: 12/10/2005
Q: Is there a way to access settings from the configuration files if I don't have a reference to the settings class that owns them?
A: Yes, you might sometimes require to access certain settings, but you don't have access to the settings class itself. For example, the default settings class generated by the settings designer in VS 2005 is internal to the assembly it is defined in. What if you need to access some settings from a different assembly, let's say, a dll that is loaded by your application? The settings API provides a useful mechanism for this through the SettingsGroupNameAttribute. Usually, the settings provider uses the fully qualified name of your settings class as the key to isolate your settings from those belonging to other classes. This attribute allows you to access settings with a different key or 'group name'. So to access settings from the application's settings class, all the dll needs to do is define its own settings class with properties that match the other class, and apply a SettingsGroupNameAttribute, giving it the other class' name as the group name. A small caveat: if you want to do this in VS, make sure you apply the attribute to the user partial class you get to by clicking 'View Code', and not the designer owned partial class, since any changes to the latter can get overwritten by the settings designer.
Q: Wait, you might ask, this is a rather powerful capability. Is it a security hole? Someone might access my settings without my knowledge or permission!
A: Well, this isn't really a security hole for two reasons:
-
From a security point of view, isolation is provided at the app domain level. The CLR recommended way of hosting untrusted code is to load it in a separate app domain. When you create an app domain, you can specify a unique friendly name for it and point it to an application configuration file of your choice. The unique friendly name ensures that the app domain gets separate user configuration files as well. Thus, the code cannot access your settings, since it doesn't have access to your configuration files. Conversely, any code that has access to your configuration files can access the settings without using the SettingsGroupNameAttribute anyway, since it can use the low level configuration APIs to do so (this requires
ConfigurationPermission for read though, and much higher permissions for write).
-
If you are really paranoid and don't want users of the application or anyone else, including code running in the same app domain as your settings class, to be able to read your settings outside of your class, you can choose to encrypt the settings before pushing them to the provider, and decrypt when you read them out. The settings API does not provide any specific way to do this, but you can use the
crypto API in the .NET Framework. The configuration API also has the ability to encrypt configuration sections - see
this article for more information.
Q: Does all this mean I cannot access settings in partial trust?
A: Not at all. We have done the work to ensure you can safely access your settings in partial trust. In fact, this should 'just work' for you in terms of reading and writing user scoped settings from your application. The only difference is that you cannot write out an unlimited amount of data, for obvious reasons. The number of bytes you can write through the settings API (specifically, the LocalFileSettingsProvider) in partial trust is restricted by an admin controlled quota, which is specified by the IsolatedStoragePermission class. This is just like how Isolated Storage itself works.
Q: You mentioned the configuration API a couple of times. What is this and how is it different from the settings API? I am a little confused.
A: There is a fundamental distinction between the settings API and the configuration API. The former provides an object model to manage application settings. This model uses a provider based storage scheme, so the storage aspect is abstracted away. Where the settings are stored is a provider specific detail - it could store them in raw files, in SQL server, in the registry or call a remote web service to retrieve them. The default settings provider we ship happens to use configuration to store settings, since that’s the most obvious store for settings in client applications. The configuration API is a little more low level and lets you create and update configuration sections in config files. So in some sense, the settings API sits on top of configuration.
So if what you want to do is store application settings and user preferences, then the settings API is the way to go. If you really need to implement configuration sections and/or access certain sections in config directly, use the configuration API.
Q: Is the settings functionality available only to Windows Forms applications?
A: The settings API itself has no restrictions at all - you can use it in any kind of application - client, web, VSTO, console, WPF etc. The default settings provider, LocalFileSettingsProvider, uses configuration to store settings, so it has certain limitations. For example, ASP.NET applications do not have user.config files, so you cannot write user scoped settings in web applications using this provider. Ofcourse, you can use the Profiles feature in ASP.NET 2.0 to very conveniently store user scoped settings. User.config files are also not supported for VSTO apps (in general, where the host application is native, like Outlook, Word or even IE). In these cases, you will need to write your own settings provider (which is quite easy to do, by the way, and there are good samples and docs in MSDN that describe how to do this) to be able to read/write user scoped settings. For the basic kinds of managed client applications like console, Windows Forms and WPF however, the LocalFileSettingsProvider is fully supported.
