My.Settings

One of the most common requirements for applications is providing the ability of storing user preferences, such as the graphic theme, personal folders, options, and so on. Generally there are two kinds of settings that the .NET Framework allows saving within the application configuration file: application-level settings and user-level settings. Application-level settings are related to the general behavior of the application, and users will not have the ability of providing modifications. User-level settings are related to each user profile that runs the applications and allows storing and editing preferences. Starting from Visual Basic 2005, My namespace provides a class named My.Settings, which offers members that easily allow working with settings at both levels, but only user-level settings can be written. At a higher level My.Settings is the code representation of the Settings tab in My Project. Because of this we start discussing My.Settings by talking about the Settings designer and then explaining how you can work with settings in code. With that said, create a new Console project (if not yet) and open My Project; then click the Settings tab. Figure 20.2 shows the Settings Designer.

Figure 20.2 Settings designer.

Basically each setting is represented by a variable that can be of any .NET type (as long as it is marked as serializable) storing the desired value. This variable can be provided at both application level and user level, with the condition that only user-level variables can be also written. You now learn how to design settings and then how to use them in code. Imagine you want to provide a simple way for checking if the application is running for the first time. In the Name column replace the default Settings identifier with IsFirstTimeRun. In the Type column choose the Boolean type from the combo box, and in the Scope column ensure that User is selected. In the Value column choose True from the combo box. Notice that Visual Studio can provide appropriate values depending on the setting type; for Boolean values, it offers True and False. After this sequence, your Settings Designer looks like Figure 20.3.

Figure 20.3 Providing a Boolean user-level setting.

You can now write some code to check if the application is running for the first time and, if so, set the IsFirstTimeRun setting to False as follows:

When you first launch the application, you get the following result:

The application is running for the first time

The code also changed the IsFirstTimeRun setting from True to False; this is possible because it is a user-level setting. If it were an application-level setting, it would be offered as a read-only property.

Notice also that you have to invoke the Save method; otherwise changes will not be saved. To check that everything works, simply rerun the application; you should now get the following message:

The application is already familiar with your system!

With the same technique you can easily define other settings of different type. You are not limited to types shown in the default combo box. You can choose any other .NET type that supports serialization by clicking the Browse command at the bottom of the combo box. This displays the Select a Type window (see Figure 20.4) where you can make your choice.

Figure 20.4 Selecting a nondefault .NET type for designing settings.

Settings definitions and default values are stored within the application configuration (app.config) file as XML definition. If your project does not already contain a configuration file, Visual Studio 2010 adds one. User-level settings are defined within a section named userSettings. The following is an excerpt from the app.config file for the demo project showing the definition of the previously described IsFirstTimeRun setting:

Notice how each setting is defined by a setting node that also defines the setting’s name and way of serialization. (Although serialized as a string, based on its value, the .NET Framework can recognize the setting as Boolean.) Each setting node has a child node named value that stores the default value for the setting.

Similarly, application-level settings are stored within a section named applicationSettings. The following is the excerpt related to the test setting previously shown:

Settings also have a Visual Basic code counterpart. Each setting is mapped to a Visual Basic property. To understand this, click the Show All Files button in Solution Explorer and then expand the My Project folder; double-click the Settings.designer.vb file under Settings.Settings. Among the code that defines My.Settings, you can also find the definition for your custom settings. The IsFirstTimeRun setting defined in the previous example is mapped to a VB property as follows:

The System.Configuration.UserScopedSettingAttribute tells the compiler that the setting has user-level scope, whereas the System.Configuration.DefaultSettingValueAttribute tells the compiler that the default value for the property is True. Notice how an explicit conversion with CType is performed to avoid any problems when deserializing. Now you know how and where settings are defined, but you still probably do not know where they are actually stored when you run the application outside Visual Studio (for example in production environments). The .NET Framework creates a folder for the application within the AppDataLocal folder in Windows, which has user-level scope. If you consider the current example, named MyNamespace on my machine, the .NET Framework created the following folders structure (on Windows 7 but it is the same on Windows Vista): C:UsersAlessandroAppDataLocalMyNamespaceMyNamespace.vshost.exe_Url_wizb0y pr4ultyjhh1g1o352espg4ehdd1.0.0.0. This auto-generated folder contains a file named user.config that contains the simple, following markup:

As you can see it is the same piece of XML code that was originally defined within the application configuration file, but now it stays as a single file within a user-level folder. This file is the place where changes to an application’s settings are effectively saved. Visual Studio provides a convenient way for restoring such files to the default settings’ value by just clicking the Synchronize button in the Settings Designer.