Windows Forms User Settings in C#

• Download source files - 40 Kb

Introduction

This morning, for the first time, I was jealous of VB.NET programmers. The My.Settings namespace makes loading and saving user settings pretty easy, and it�s pretty well documented. Unfortunately, C# programmers don�t have anything quite as slick as the My.Settings namespace, and the procedure for persisting user settings is not well-documented.

It turns out that it is pretty easy to persist user settings in C#, and this article will show you how to do it. We�re going to stick to the basics�nothing fancy. We will use as our example a Windows Forms �Hello World� program that does nothing but show a window with the canonical text:

We will create settings for the application window�s size and location properties, and we will persist them between runs of the program. The project code can be downloaded from the link at the top of this article.

Step One: Create the Settings

The easiest way to create settings is to use the Visual Studio Settings Designer. To get to the designer, open the project�s Properties pages, and select the Settings tab:

As you can see from the Settings grid, settings can have Application scope or User scope. Application settings are those that apply across all users, and that do not change from run to run of the program. Once an Application setting is set in the designer, it can�t be changed in code.

User settings are those that change from user to user, and from run to run of an application. They can be changed in code. User settings are commonly used to store user preferences, such as window size and location. That�s what we�re going to do here.

Fill out the Settings grid so that it looks like this:

The grid is self-explanatory. Note the default values in the Value column. I simply copied these from the Properties of the form. Note that you must include default values in the Values column! If you leave them out, the designer code will declare the settings, but it won�t instantiate them, and any code that calls them will throw a runtime exception.

Once you have entered the settings on the grid, save the project and close the Properties pages.

Step Two: Load the Settings at Runtime

The code to load the settings at runtime is very simple. The designer created a class for us that holds our settings. The class is located in a Properties namespace under our project name. Our first step is to add a using statement for this class:

using UserSettingsDemo.Properties;

Node that the Visual Studio code editor can add this statement for us automatically. If we haven�t added the statement, then the first time we type �Settings�, the code editor will present a smart tag that can enter the using statement automatically:

Once the using statement has been added, we simply need to add a few lines of code to the window�s event handlers.

Create a FormLoad event handler for the target window, and add the following code to the handler:

private void FormMain_Load(object sender, EventArgs e)
{
    // Set window location

    if (Settings.Default.WindowLocation != null)
    {
        this.Location = Settings.Default.WindowLocation;
    }

    // Set window size

    if (Settings.Default.WindowSize != null)
    {
        this.Size = Settings.Default.WindowSize;
    }
} 

The code is self-explanatory. Note that we find our settings in a Properties class that the designer created for us. This class can hold multiple sets of settings for a user; we want the Default set.

Step Three Save the Settings at Runtime

Saving settings is almost as easy. However, there is a minor complication when saving a window�s size. We will see that in the code sample that follows.

The persistence code for settings is generally placed in the FormClosing event handler for the target window. Create the handler, and add the following code to it:

private void FormMain_FormClosing(object sender, FormClosingEventArgs e)
{
    // Copy window location to app settings

    Settings.Default.WindowLocation = this.Location;

    // Copy window size to app settings

    if (this.WindowState == FormWindowState.Normal)
    {
        Settings.Default.WindowSize = this.Size;
    }
    else
    {
        Settings.Default.WindowSize = this.RestoreBounds.Size;
    }

    // Save settings

    Settings.Default.Save();
}

The WindowLocation setting is self-explanatory, but the WindowSize property has a wrinkle. If a window is normal size, we can read its size property in the usual manner. But if a window is minimized or maximized, the size property will return an inaccurate value. So, .NET provides a RestoreBounds property that will return the size of the window in its normal state. But�and here�s the wrinkle�the RestoreBounds property returns a valid value only when the window is minimized or maximized. As a result, we have to test the WindowState property, and call either the Size or RestoreBounds property based on the results.

Note that we have to call the Settings� Save() method to save the settings to the config file. And the config file is not the Application.exe.config file�only application settings go there. User settings are saved to different settings files for each user, which are stored in an arcane location. This FAQ explains how to find the settings file, in case you need to get to it.

Data Binding

Many settings can be data-bound from the Visual Studio Properties window. For example, we could have data bound our form�s location property (but not its size property) by setting a binding in the ApplicationSettings property:

The Size property can�t be data-bound because whether we use the Size or RestoreBounds property isn�t decided until runtime. But for many properties, data binding provides the simplest and easiest approach. Just remember that you will still need to save the Settings from code before your app closes:

// Save settings

Settings.Default.Save();

Conclusion

And that�s about all there is to creating, loading, and saving user settings in C# 2.0. It�s just about as easy as using the VB.NET My.Settings namespace, and it provides a simple procedure for persisting just about any user setting you might create. And it means I can now go back to pretending I�m not jealous of some of the convenience features built in to VB.NET!