Share via

Application Settings Architecture

  • Article

This topic describes how the Application Settings architecture works, and explores advanced features of the architecture, such as grouped settings and settings keys.

The application settings architecture supports defining strongly typed settings with either application or user scope, and persisting the settings between application sessions. The architecture provides a default persistence engine for saving settings to and loading them from the local file system. The architecture also defines interfaces for supplying a custom persistence engine.

Interfaces are provided that enable custom components to persist their own settings when they are hosted in an application. By using settings keys, components can keep settings for multiple instances of the component separate.

Defining Settings

The application settings architecture is used within both ASP.NET and Windows Forms, and it contains a number of base classes that are shared across both environments. The most important is SettingsBase, which provides access to settings through a collection, and provides low-level methods for loading and saving settings. Each environment implements its own class derived from SettingsBase to provide additional settings functionality for that environment. In a Windows Forms-based application, all application settings must be defined on a class derived from the ApplicationSettingsBase class, which adds the following functionality to the base class:

  • Higher-level loading and saving operations

  • Support for user-scoped settings

  • Reverting a user's settings to the predefined defaults

  • Upgrading settings from a previous application version

  • Validating settings, either before they are changed or before they are saved

The settings can be described using a number of attributes defined within the System.Configuration namespace; these are described in Application Settings Attributes. When you define a setting, you must apply it with either ApplicationScopedSettingAttribute or UserScopedSettingAttribute, which describes whether the setting applies to the entire application or just to the current user.

The following code example defines a custom settings class with a single setting, BackgroundColor.

Imports System.Configuration

Public Class MyUserSettings
    Inherits ApplicationSettingsBase
    <UserScopedSetting()> _
    <DefaultSettingValue("white")> _
    Public Property BackgroundColor() As Color
        Get
            BackgroundColor = Me("BackgroundColor")
        End Get 

        Set(ByVal value As Color)
            Me("BackgroundColor") = value
        End Set 
    End Property 
End Class

using System;
using System.Configuration;
using System.Drawing;

public class MyUserSettings : ApplicationSettingsBase
{
    [UserScopedSetting()]
    [DefaultSettingValue("white")]
    public Color BackgroundColor
    {
        get
        {
            return ((Color)this["BackgroundColor"]);
        }
        set
        {
            this["BackgroundColor"] = (Color)value;
        }
    }
}

Settings Persistence

The ApplicationSettingsBase class does not itself persist or load settings; this job falls to the settings provider, a class that derives from SettingsProvider. If a derived class of ApplicationSettingsBase does not specify a settings provider through the SettingsProviderAttribute, then the default provider, LocalFileSettingsProvider, is used.

The configuration system that was originally released with the .NET Framework supports providing static application configuration data through either the local computer's machine.config file or within an app.exe.config file that you deploy with your application. The LocalFileSettingsProvider class expands this native support in the following ways:

  • Application-scoped settings can be stored in either the machine.config or app.exe.config files. Machine.config is always read-only, while app.exe.config is restricted by security considerations to read-only for most applications.

  • User-scoped settings can be stored in app.exe.config files, in which case they are treated as static defaults.

  • Non-default user-scoped settings are stored in a new file, user.config, where user is the user name of the person currently executing the application. You can specify a default for a user-scoped setting with DefaultSettingValueAttribute. Because user-scoped settings often change during application execution, user.config is always read/write.

All three configuration files store settings in XML format. The top-level XML element for application-scoped settings is <appSettings>, while <userSettings> is used for user-scoped settings. An app.exe.config file which contains both application-scoped settings and defaults for user-scoped settings would look like this:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <configSections>
        <sectionGroup name="applicationSettings" type="System.Configuration.ApplicationSettingsGroup, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" >
            <section name="WindowsApplication1.Properties.Settings" type="System.Configuration.ClientSettingsSection, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
        </sectionGroup>
        <sectionGroup name="userSettings" type="System.Configuration.UserSettingsGroup, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" >
            <section name="WindowsApplication1.Properties.Settings" type="System.Configuration.ClientSettingsSection, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" allowExeDefinition="MachineToLocalUser" />
        </sectionGroup>
    </configSections>
    <applicationSettings>
        <WindowsApplication1.Properties.Settings>
            <setting name="Cursor" serializeAs="String">
                <value>Default</value>
            </setting>
            <setting name="DoubleBuffering" serializeAs="String">
                <value>False</value>
            </setting>
        </WindowsApplication1.Properties.Settings>
    </applicationSettings>
    <userSettings>
        <WindowsApplication1.Properties.Settings>
            <setting name="FormTitle" serializeAs="String">
                <value>Form1</value>
            </setting>
            <setting name="FormSize" serializeAs="String">
                <value>595, 536</value>
            </setting>
        </WindowsApplication1.Properties.Settings>
    </userSettings>
</configuration>

For a definition of the elements within the application settings section of a configuration file, see Application Settings Schema.

Settings Bindings

Application settings uses the Windows Forms data binding architecture to provide two-way communication of settings updates between the settings object and components. If you use Visual Studio to create application settings and assign them to component properties, these bindings are generated automatically.

You can only bind an application setting to a component that supports the IBindableComponent interface. Also, the component must implement a change event for a specific bound property, or notify application settings that the property has changed through the INotifyPropertyChanged interface. If the component does not implement IBindableComponent and you are binding through Visual Studio, the bound properties will be set the first time, but will not update. If the component implements IBindableComponent but does not support property change notifications, the binding will not update in the settings file when the property is changed.

Some Windows Forms components, such as ToolStripItem, do not support settings bindings.

Settings Serialization

When LocalFileSettingsProvider must save settings to disk, it performs the following actions:

  1. Uses reflection to examine all of the properties defined on your ApplicationSettingsBase derived class, finding those that are applied with either ApplicationScopedSettingAttribute or UserScopedSettingAttribute.

  2. Serializes the property to disk. It first attempts to call the ConvertToString or ConvertFromString on the type's associated TypeConverter. If this does not succeed, it uses XML serialization instead.

  3. Determines which settings go in which files, based on the setting's attribute.

If you implement your own settings class, you can use the SettingsSerializeAsAttribute to mark a setting for either binary or custom serialization using the SettingsSerializeAs enumeration. For more information on creating your own settings class in code, see How to: Create Application Settings.

Settings File Locations

The location of the app.exe.config and user.config files will differ based on how the application is installed. For a Windows Forms-based application copied onto the local computer, app.exe.config will reside in the same directory as the base directory of the application's main executable file, and user.config will reside in the location specified by the Application.LocalUserAppDataPath property. For an application installed by means of ClickOnce, both of these files will reside in the ClickOnce Data Directory underneath %InstallRoot%\Documents and Settings\username\Local Settings.

The storage location of these files is slightly different if a user has enabled roaming profiles, which enables a user to define different Windows and application settings when he or she is using other computers within a domain. In that case, both ClickOnce applications and non-ClickOnce applications will have their app.exe.config and user.config files stored under %InstallRoot%\Documents and Settings\username\Application Data.

For more information about how the Application Settings feature works with the new deployment technology, see ClickOnce and Application Settings. For more information about the ClickOnce Data Directory, see Accessing Local and Remote Data in ClickOnce Applications.

Application Settings and Security

Application settings are designed to work in partial trust, a restricted environment that is the default for Windows Forms applications hosted over the Internet or an intranet. No special permissions beyond partial trust are needed to use application settings with the default settings provider.

When application settings are used in a ClickOnce application, the user.config file is stored in the ClickOnce data directory. The size of the application's user.config file cannot exceed the data directory quota set by ClickOnce. For more information, see ClickOnce and Application Settings.

Custom Settings Providers

In the Application Settings architecture, there is a loose coupling between the applications settings wrapper class, derived from ApplicationSettingsBase, and the associated settings provider or providers, derived from SettingsProvider. This association is defined only by the SettingsProviderAttribute applied to the wrapper class or its individual properties. If a settings provider is not explicitly specified, the default provider, LocalFileSettingsProvider, is used. As a result, this architecture supports creating and using custom settings providers.

For example, suppose that you want to develop and use SqlSettingsProvider, a provider that will store all settings data in a Microsoft SQL Server database. Your SettingsProvider-derived class would receive this information in its Initialize method as a parameter of type System.Collections.Specialized.NameValueCollection. You would then implement the GetPropertyValues method to retrieve your settings from the data store, and SetPropertyValues to save them. Your provider can use the SettingsPropertyCollection supplied to GetPropertyValues to determine the property's name, type, and scope, as well as any other settings attributes defined for that property.

Your provider will need to implement one property and one method whose implementations may not be obvious. The ApplicationName property is an abstract property of SettingsProvider; you should program it to return the following:

Public Overrides Property ApplicationName() As String 
    Get
        ApplicationName = System.Reflection.Assembly.GetExecutingAssembly().GetName().Name
    End Get 
    Set(ByVal value As String)
        ' Do nothing. 
    End Set 
End Property

public override string ApplicationName
{
    get
    {
        return (System.Reflection.Assembly.GetExecutingAssembly().GetName().Name);
    }
    set
    {
        // Do nothing.
    }
}

Your derived class must also implement an Initialize method that takes no arguments and returns no value. This method is not defined by SettingsProvider.

Finally, you implement IApplicationSettingsProvider on your provider to provide support for refreshing settings, reverting settings to their defaults, and upgrading settings from one application version to another.

Once you have implemented and compiled your provider, you need to instruct your settings class to use this provider instead of the default. You accomplish this through the SettingsProviderAttribute. If applied to an entire settings class, the provider is used for each setting that the class defines; if applied to individual settings, Application Settings architecture uses that provider for those settings only, and uses LocalFileSettingsProvider for the rest. The following code example shows how to instruct the settings class to use your custom provider.

Imports System.Configuration

<SettingsProvider("SqlSettingsProvider")> _
Public Class CustomSettings
    Inherits ApplicationSettingsBase

    ' Implementation goes here. 
End Class

using System;
using System.Collections.Generic;
using System.Text;
using System.Configuration;

namespace ApplicationSettingsArchitectureCS
{
    class CustomSettings : ApplicationSettingsBase
    {
        // Implementation goes here.
    }
}

A provider may be called from multiple threads simultaneously, but it will always write to the same storage location; therefore, the Application Settings architecture will only ever instantiate a single instance of your provider class.

Important noteImportant Note:

You should ensure that your provider is thread-safe, and only allows one thread at a time to write to the configuration files.

Your provider does not need to support all of the settings attributes defined in the System.Configuration namespace, though it must at a minimum support ApplicationScopedSettingAttribute and UserScopedSettingAttribute, and should also support DefaultSettingValueAttribute. For those attributes that it does not support, your provider should just fail without notification; it should not throw an exception. If the settings class uses an invalid combination of attributes, however — such as applying ApplicationScopedSettingAttribute and UserScopedSettingAttribute to the same setting — your provider should throw an exception and cease operation.

See Also

Concepts

Application Settings Overview

Application Settings for Custom Controls

ClickOnce and Application Settings

Reference

Application Settings Schema

ApplicationSettingsBase

SettingsProvider

LocalFileSettingsProvider