Application Settings

After you've assembled your application from the required forms, controls, and components, you build it and deploy it. To run, however, applications need certain information, and that often differs between installations, users, and application sessions. Consequently, you can't compile this information directly into the application assemblies. Instead, the information must reside in a location independent from those assemblies, from which it is read and to which it is written as needed during execution. To solve this problem, .NET provides a complete infrastructure whose fundamental element is the setting.

.NET considers there to be two types of settings: those for users and those for applications. User settings, such as information you might find in a Tools | Options dialog for an application like VS05, change from one application session to the next. Application settings, such as database connection strings, change from one installation to the next. You can add one or more of each type of setting to your application by using the Settings Editor. To open this editor, right-click your project and select Properties | Settings, as shown in Figure 1.15.

Figure 1.15. Configuring Settings

Each setting has a name, a type, a scope, and a value. The name is the way you refer to the setting; type specifies the type of value it stores; scope determines whether a setting is a user setting or an application setting; and value is the setting's initial value. All the settings you create are stored in your project's app.config file, in which they are grouped by scope:

<?xml version="1.0" encoding="utf-8" ?> <configuration>   <configSections>     ...   </configSections>   <userSettings>     <MySecondApp.Properties.Settings>       <setting name="WindowLocation" serializeAs="String">         <value>100, 100</value>       </setting>     </MySecondApp.Properties.Settings>   </userSettings>   <applicationSettings>     <MySecondApp.Properties.Settings>       <setting name="Pi" serializeAs="String">         <value>3.1415927</value>       </setting>     </MySecondApp.Properties.Settings>    </applicationSettings> </configuration>

When you build your application, the content and settings stored in app.config are copied into your application's configuration file, which is named ApplicationName.exe.config.

When your app executes, it needs a way to retrieve these values and, if necessary, save new values. To provide a simple way to do this, VS05 generates a special class, Settings, in your project:

namespace MySecondApp.Properties {   internal sealed class Settings : ApplicationSettingsBase {     public static Settings Default {       get {...}     }     public Point Location {       get {...}       set {...}     }     public decimal Pi {       get {...}     }   } }

This class, generated in the ApplicationName.Properties namespace, exposes each setting as a property that holds a value of the type specified when the setting was added. Although you could create an instance of this class manually, you can use the static Default method to take on that burden for you. The Settings class derives from ApplicationSettingsBase, a .NET class located in the System.Configuration namespace that implements all the support to read and write settings. This support is encapsulated by the generated properties, so all you need to worry about is the Settings class itself. Additionally, because the properties are strongly typed, you'll receive compile-time errors if you use them incorrectly.

You may have noticed that the user setting is read-write, whereas the application setting is read-only. User settings are read-write to allow users to change values between application sessions. In contrast, application settings are likely to store configuration information; so to prevent developers from writing code that could change thempotentially breaking the applicationapplication settings are generated as read-only properties. The following code shows how you might use both user and application settings at run-time:

// Read an application setting decimal pi = Properties.Settings.Default.Pi; // Write to an application setting // NOTE: This won't compile Properties.Settings.Default.Pi = 3.142; // Write a user setting Properties.Settings.Default.WindowLocation = this.Location;

When you use the Settings class like this, the settings values are initially retrieved from the application's configuration file and subsequently are operated on in memory. But because user settings need to be persisted across application sessions, all user-scoped property values held by the Settings object should be persisted back to the configuration file if changed. To do this, you call the Save method on the Settings class:

void saveSettingsButton_Click(object sender, EventArgs e) {    // Save all user settings    Properties.Settings.Default.Save(); }

Changed user settings are not stored back to an application's configuration file, as you might expect; the only settings stored in an application's configuration file are application settings and default user settings. Altered user settings are persisted to a file named user.config, which is placed in one of several Windows logo-compliant locations within the file system, depending on where the application is installed and whether the user is roaming. The path to user.config for a locally installed application executed by a nonroaming user conforms to the following:

%SystemDrive%\Documents and Settings\UserName\   Local Settings\Application Data\ProductName\   ApplicationName.exe_Url_UrlHash\AssemblyVersionNumber

Sometimes, users change settings to values they are not happy with and then can't remember what the previous defaults were. Fortunately, the settings infrastructure offers two simple backup options to rollback to the previous settings values. First, you can provide a mechanism for users to revert to the last saved settings by calling the Settings object's Reload method:

void reloadSettingsButton_Click(object sender, EventArgs e) {    // Revert to last saved user settings    Properties.Settings.Default.Reload(); }

Second, if user settings are damaged beyond recovery, you can allow users to revert to the application's default installed user settingsthe default values stored in the application's configuration file. Retrieving them is a matter of calling the Settings object's Reset method:

void resetSettingsButton_Click(object sender, EventArgs e) {    // Revert to default installed user settings    Properties.Settings.Default.Reset(); }

User settings are managed so that if the user.config file is deleted, the default values for those settings are loaded into the next application session. This is the same as calling the Reset method.

The settings subsystem comes with more exotic capabilities, including versioning support, settings profiles, and even the ability to create custom settings providers, a feature that lets you save user settings to, for example, a web service. Additionally, you can bind form and control properties directly to settings from the Properties window, a practice that can save a lot of coding effort. To explore these in detail, look at Chapter 15: Settings.