Click here to Skip to main content
Click here to Skip to main content

Windows Forms User Settings in C#

, 1 Aug 2006
Rate this:
Please Sign up or sign in to vote.
# programmers don’t have anything quite as slick as the VB.NET My.Settings namespace. However, there is an alternative

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!

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here

About the Author

David Veeneman
Software Developer (Senior) Foresight Systems
United States United States
David Veeneman is a financial planner and software developer. He is the author of "The Fortune in Your Future" (McGraw-Hill 1998). His company, Foresight Systems, develops planning and financial software.

Comments and Discussions

 
GeneralThank you Pinmemberdannygoh26-Jun-09 11:48 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web03 | 2.8.140721.1 | Last Updated 1 Aug 2006
Article Copyright 2006 by David Veeneman
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid