.NET 2.0+

Application Settings

by Richard Carr, published at http://www.blackwasp.co.uk/ApplicationSettings.aspx

There are various ways to hold application-wide and user-specific settings externally to a program. One is to set up application settings in a Visual Studio project. These permit strongly typed configuration that can be changed without recompiling.

What are Application Settings?

It is common for an application to require some level of configurability without the requirement to recompile the software. Sometimes you will want to be able to change application-wide settings that affect all of a program's users. For example, a connection string for a database may be configurable to allow the database's location to be changed after the software is installed. You may also wish to include user-specific settings than can be changed within the software either explicitly or implicitly. For example, a web browser may include a "home page" that is different for each user and can be changed by clicking a button.

Both application-wide and user-specific configuration can be created easily using application settings. These are named value that can be created using Visual Studio. The settings are added to the assembly's configuration file and classes are generated that allow you to settings within your code as strongly typed properties.

Using Application Settings

In this article we will create a simple console application that reads its configuration from application settings. We will firstly configure the program with a read-only, application-wide setting. We will then modify this setting to be user-specific and allow it to be changed at run-time and persisted to disk. To begin, create a new console application named "AppSettings".

Creating Application Settings

Application settings can be set up manually in the app.config file. However, it is much easier to perform this configuration using Visual Studio's project properties. To view the application settings, right-click the project name in the Solution Explorer and choose Properties from the context-sensitive menu that appears. From the section names at the left of the properties window, choose Settings.

The first time that you view the application settings for a project, you may see the message, "This project does not contain a default settings file. Click here to create one." Click this message to create a settings file and view the application settings grid, pictured below.

The grid allows you to create one application setting per line. Each setting requires four values to be specified:

• Name. The Name column is used to give the setting a unique name. This name will become the name of the property that will be used to access the setting's value.
• Type. All application settings are strongly typed. This column is used to specify the type of the setting property.
• Scope. Two scope options are available to allow you to specify whether you wish to create an application-wide or user-specific setting.
• Value. The final column is used to specify the default value for the setting.

For the sample program, add a single setting to the grid. The name of the setting should be "TestSetting". Set the Type to string, the Scope to Application and the value to "Test". Once the setting is created, close the properties window. You should see that an app.config file has been added to the project. If you review the contents of this file you will find the details that you created in the application settings grid.

NB: After compiling the application, the app.config will be renamed to match the name of the assembly; in this case AppSettings.exe.config. You will be able to edit this text file to modify settings without recompiling.

Reading Application Settings

Creating the default application settings file adds a new namespace, named "Properties", within the project's default namespace. Inside the new namespace is a class that provides access to the new properties. To demonstrate, return to the code editor for the class containing the program's Main method. To simplify access to the new namespace, add the following using directive to the top of the code:

using AppSettings.Properties;

We can now output the contents of the application setting by accessing a property of a class that has been generated by Visual Studio. To output the text to the console, add the following code within the Main method:

Console.WriteLine(Settings.Default.TestSetting);
Console.ReadLine();

Execute the program to see the value from the application setting outputted to the console. You can also try executing the compiled executable and modifying the value within the AppSettings.exe.config file. This will show that the value can be changed without recompiling.

Creating User Settings

If you try to assign a new value to an application-wide setting, the code fails to compile. To see this, modify the code within the Main method as follows. When you try to compile, an error is displayed indicating that the property is read-only.

Console.WriteLine(Settings.Default.TestSetting);
Settings.Default.TestSetting = Console.ReadLine();

Application-wide values may not be changed at run-time. However, user-specific settings can be modified at run-time for an individual user. To change the TestSetting to be user-specific, return to the project's properties and change the Scope value for the setting to "User". The code will now compile but changes to the settings will exist only until the application stops executing. To persist user settings between sessions, you must use the Save method. To try this, add the following line to the end of the Main method:

Settings.Default.Save();

Try executing the compiled executable version of the program several times, each time entering a new string for the setting. You should see that the entered value is persisted between executions of the software. However, if you review the AppSettings.exe.config file in the executable's folder, you will see that the settings are not being changed. This file continues to hold the default values for each configurable item, ensuring that new users of the program will not inherit changes made by other users. The user-specific values are stored within a new file within the user's folder. The exact path to the folder is determined by the operating system.

Resetting User Settings

In some applications, particularly those with a large number of configurable settings, it is useful to give the user the option to reset all user-specific settings to their default values. You can achieve this using the Reset method. After resetting, the user's configuration file is emptied so that the main configuration file's values are used instead.

Settings.Default.Reset();