ApplicationSettingsBase Class (System.Configuration)

Switch on low bandwidth view

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2005/.NET Framework 2.0

Other versions are also available for the following:

.NET Framework Class Library

ApplicationSettingsBase Class

Note: This class is new in the .NET Framework version 2.0.

Acts as a base class for deriving concrete wrapper classes to implement the application settings feature in Window Forms applications.

Namespace: System.Configuration
Assembly: System (in system.dll)

Syntax

Visual Basic (Declaration)

Public MustInherit Class ApplicationSettingsBase
    Inherits SettingsBase
    Implements INotifyPropertyChanged

Visual Basic (Usage)

Dim instance As ApplicationSettingsBase

public abstract class ApplicationSettingsBase : SettingsBase, INotifyPropertyChanged

C++

public ref class ApplicationSettingsBase abstract : public SettingsBase, INotifyPropertyChanged

public abstract class ApplicationSettingsBase extends SettingsBase implements INotifyPropertyChanged

JScript

public abstract class ApplicationSettingsBase extends SettingsBase implements INotifyPropertyChanged

Remarks

ApplicationSettingsBase adds the following functionality to the SettingsBase class, which is used by Web-based applications:

The ability to detect attributes on a derived, settings wrapper class. ApplicationSettingsBase supports the declarative model used for wrapper class properties, as described later.
Higher-level Save and Reload methods.
Additional validation events that you can handle to ensure the correctness of individual settings.

In the application settings architecture, to access a group of settings properties you need to derive a concrete wrapper class from ApplicationSettingsBase. The wrapper class customizes ApplicationSettingsBase in the following ways:

For every settings property to be accessed, a corresponding strongly typed public property is added to the wrapper class. This property has get and set accessors for read/write application settings, but only a get accessor for read-only settings.
Appropriated attributes must be applied to the wrapper class's public properties to indicate characteristics of the settings property, such as the setting's scope (application or user), whether the setting should support roaming, the default value for the setting, the settings provider to be used, and so on. Each property is required to specify its scope, using either ApplicationScopedSettingAttribute or UserScopedSettingAttribute. Application-scoped settings are read-only if the default LocalFileSettingsProvider is used.

The ApplicationSettingsBase class uses reflection to detect these attributes at run time. Most of this information gets passed to the settings provider layer, which is responsible for storage, persistence format, and so on.

When an application has multiple settings wrapper classes, each class defines a settings group. Each group has the following characteristics:

A group can contain any number or type of property settings.
If the group name is not explicitly set by the decorating the wrapper class with a SettingsGroupNameAttribute, then a name is automatically generated.

By default, all client-based applications use the LocalFileSettingsProvider to provide storage. If an alternate settings provider is desired, then the wrapper class or property must be decorated with a corresponding SettingsProviderAttribute.

For more information about using application settings, see Application Settings for Windows Forms.

Example

The following code example demonstrates the use of application settings to persist the following attributes of the main form: location, size, background color, and title bar text. All of these attributes are persisted as single application settings properties in the FormSettings class, named FormLocation, FormSize, FormBackColor and FormText, respectively. All except for FormText are data bound to their associated form properties and have a default setting value, DefaultSettingValueAttribute applied.

The form contains four child controls that have the following names and functions:

A button named btnBackColor used to display the Color common dialog box.
A button named btnReload used to Reload the application settings.
A button named btnReset used to Reset the application settings.
A textbox named tbStatus used to display status information about the program.

Notice that after every execution of the application, an additional period character is appended to the title text of the form.

partial class Form1 : Form
{
    private FormSettings frmSettings1 = new FormSettings();

    public Form1()
    {
        InitializeComponent();
    

    private void Form1_Load(object sender, EventArgs e)
    {
        //Associate settings property event handlers.
        frmSettings1.SettingChanging += new SettingChangingEventHandler(
                                            frmSettings1_SettingChanging);
        frmSettings1.SettingsSaving += new SettingsSavingEventHandler(
                                            frmSettings1_SettingsSaving);

        //Data bind settings properties with straightforward associations.
        Binding bndBackColor = new Binding("BackColor", frmSettings1, 
            "FormBackColor", true, DataSourceUpdateMode.OnPropertyChanged);
        this.DataBindings.Add(bndBackColor);
        Binding bndSize = new Binding("Size", frmSettings1, "FormSize", 
            true, DataSourceUpdateMode.OnPropertyChanged);
        this.DataBindings.Add(bndSize);
        Binding bndLocation = new Binding("Location", frmSettings1, 
            "FormLocation", true, DataSourceUpdateMode.OnPropertyChanged);
        this.DataBindings.Add(bndLocation);

        //For more complex associations, manually assign associations.
        String savedText = frmSettings1.FormText;
        //Since there is no default value for FormText.
        if (savedText != null)
            this.Text = savedText;
    

    private void Form1_FormClosing(object sender, FormClosingEventArgs e)
    {
        //Synchronize manual associations first.
        frmSettings1.FormText = this.Text + '.';
        frmSettings1.Save();
    

    private void btnBackColor_Click(object sender, EventArgs e)
    {
        if (DialogResult.OK == colorDialog1.ShowDialog())
        {
            Color c = colorDialog1.Color;
            this.BackColor = c;
        
    

    private void btnReset_Click(object sender, EventArgs e)
    {
        frmSettings1.Reset();
        this.BackColor = SystemColors.Control;
    

    private void btnReload_Click(object sender, EventArgs e)
    {
        frmSettings1.Reload();
    

    void frmSettings1_SettingChanging(object sender, SettingChangingEventArgs e)
    {
        tbStatus.Text = e.SettingName + ": " + e.NewValue;
    

    void frmSettings1_SettingsSaving(object sender, CancelEventArgs e)
    {
        //Should check for settings changes first.
        DialogResult dr = MessageBox.Show(
                        "Save current values for application settings?",
                        "Save Settings", MessageBoxButtons.YesNo);
        if (DialogResult.No == dr)
        {
            e.Cancel = true;
        
    



//Application settings wrapper class
sealed class FormSettings : ApplicationSettingsBase
{
    [UserScopedSettingAttribute()]
    public String FormText
    {
        get { return (String)this["FormText"]; 
        set { this["FormText"] = value; 
    

    [UserScopedSetting()]
    [DefaultSettingValueAttribute("0, 0")]
    public Point FormLocation
    {
        get { return (Point)(this["FormLocation"]); 
        set { this["FormLocation"] = value; 
    

    [UserScopedSetting()]
    [DefaultSettingValueAttribute("225, 200")]
    public Size FormSize
    {
        get { return (Size)this["FormSize"]; 
        set { this["FormSize"] = value; 
    

    [UserScopedSetting()]
    [DefaultSettingValueAttribute("LightGray")]
    public Color FormBackColor
    {
        get { return (Color)this["FormBackColor"]; 
        set { this["FormBackColor"] = value;

C++

    FormSettings ^ formSettings;

public:
    AppSettingsForm()
    {
        formSettings = gcnew FormSettings;
        InitializeComponent();
    

private:
    void AppSettingsForm_Load(Object^ sender, EventArgs^ e)
    {
        //Associate settings property event handlers.
        formSettings->SettingChanging += gcnew SettingChangingEventHandler(
            this, &AppSettingsForm::FormSettings_SettingChanging);
        formSettings->SettingsSaving += gcnew SettingsSavingEventHandler(
            this,&AppSettingsForm::FormSettings_SettingsSaving);

        //Data bind settings properties with straightforward associations.
        Binding^ backColorBinding = gcnew Binding("BackColor", 
            formSettings, "FormBackColor", true, 
            DataSourceUpdateMode::OnPropertyChanged);
        this->DataBindings->Add(backColorBinding);
        Binding^ sizeBinding = gcnew Binding("Size", formSettings,
            "FormSize", true, DataSourceUpdateMode::OnPropertyChanged);
        this->DataBindings->Add(sizeBinding);
        Binding^ locationBinding = gcnew Binding("Location", formSettings,
            "FormLocation", true, DataSourceUpdateMode::OnPropertyChanged);
        this->DataBindings->Add(locationBinding);

        //For more complex associations, manually assign associations.
        String^ savedText = formSettings->FormText;
        //Since there is no default value for FormText.
        if (savedText != nullptr)
        {
            this->Text = savedText;
        
    

private:
    void AppSettingsForm_FormClosing(Object^ sender,
        FormClosingEventArgs^ e)
    {
        //Synchronize manual associations first.
        formSettings->FormText = this->Text + '.';
        formSettings->Save();
    

private:
    void BackColorButton_Click(Object^ sender, EventArgs^ e)
    {
        if (::DialogResult::OK == colorDialog->ShowDialog())
        {
            Color color = colorDialog->Color;
            this->BackColor = color;
        
    

private:
    void ResetButton_Click(Object^ sender, EventArgs^ e)
    {
        formSettings->Reset();
        this->BackColor = SystemColors::Control;
    

private:
    void ReloadButton_Click(Object^ sender, EventArgs^ e)
    {
        formSettings->Reload();
    

private:
    void FormSettings_SettingChanging(Object^ sender,
        SettingChangingEventArgs^ e)
    {
        statusDisplay->Text = e->SettingName + ": " + e->NewValue;
    

private:
    void FormSettings_SettingsSaving(Object^ sender,
        CancelEventArgs^ e)
    {
        //Should check for settings changes first.
        ::DialogResult^ dialogResult = MessageBox::Show(
            "Save current values for application settings?",
            "Save Settings", MessageBoxButtons::YesNo);
        if (::DialogResult::No == dialogResult)
        {
            e->Cancel = true;
        
    
;

Inheritance Hierarchy

System.Object
System.Configuration.SettingsBase
System.Configuration.ApplicationSettingsBase

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Platforms

Windows 98, Windows 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

Version Information

.NET Framework

Supported in: 2.0

Reference

ApplicationSettingsBase Members
System.Configuration Namespace
LocalFileSettingsProvider
ApplicationScopedSettingAttribute Class
UserScopedSettingAttribute
SettingsGroupNameAttribute
LocalFileSettingsProvider
SettingsProviderAttribute

Other Resources

Application Settings for Windows Forms