This documentation is archived and is not being maintained.

ApplicationSettingsBase Class

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)

'Declaration
Public MustInherit Class ApplicationSettingsBase _
	Inherits SettingsBase _
	Implements INotifyPropertyChanged
'Usage
Dim instance As ApplicationSettingsBase

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.

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 and Size are data bound to their associated form properties and have a default setting value applied using DefaultSettingValueAttribute.

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.

This code example requires a Form with a ColorDialog class named colorDialog1, and a StatusStrip control with a ToolStripStatusLabel named tbStatus. Additionally, it requires three Button objects named btnReload, btnReset, and btnBackColor.

Imports System.Configuration
Imports System.ComponentModel

Public Class Form1

    Private WithEvents frmSettings1 As New FormSettings

    Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs) _
            Handles MyBase.Load
        'Settings property event handlers are associated through WithEvents  
        '  and Handles combination. 

        'Data bind settings properties with straightforward associations. 
        Dim bndBackColor As New Binding("BackColor", frmSettings1, "FormBackColor", _
                True, DataSourceUpdateMode.OnPropertyChanged)
        Me.DataBindings.Add(bndBackColor)
        Dim bndLocation As New Binding("Location", frmSettings1, "FormLocation", _
                True, DataSourceUpdateMode.OnPropertyChanged)
        Me.DataBindings.Add(bndLocation)

        ' Assign Size property, since databinding to Size doesn't work well. 
        Me.Size = frmSettings1.FormSize

        'For more complex associations, manually assign associations. 
        Dim savedText As String = frmSettings1.FormText
        'Since there is no default value for FormText. 
        If (savedText IsNot Nothing) Then 
            Me.Text = savedText
        End If 
    End Sub 

    Private Sub Form1_FormClosing_1(ByVal sender As Object, ByVal e As _
            FormClosingEventArgs) Handles MyBase.FormClosing
        'Synchronize manual associations first.
        frmSettings1.FormText = Me.Text + "."c

        ' Save size settings manually.
        frmSettings1.FormSize = Me.Size

        frmSettings1.Save()
    End Sub 

    Private Sub btnBackColor_Click(ByVal sender As Object, ByVal e As EventArgs) _
            Handles btnBackColor.Click
        If System.Windows.Forms.DialogResult.OK = colorDialog1.ShowDialog() Then 
            Dim c As Color = colorDialog1.Color
            Me.BackColor = c
        End If 
    End Sub 

    Private Sub btnReset_Click(ByVal sender As Object, ByVal e As EventArgs) _
            Handles btnReset.Click
        frmSettings1.Reset()
        Me.BackColor = SystemColors.Control
    End Sub 

    Private Sub btnReload_Click(ByVal sender As Object, ByVal e As EventArgs) _
            Handles btnReload.Click
        frmSettings1.Reload()
    End Sub 

    Private Sub frmSettings1_SettingChanging(ByVal sender As Object, ByVal e As _
            SettingChangingEventArgs) Handles frmSettings1.SettingChanging
        tbStatus.Text = e.SettingName & ": " & e.NewValue.ToString
    End Sub 

    Private Sub frmSettings1_SettingsSaving(ByVal sender As Object, ByVal e As _
            CancelEventArgs) Handles frmSettings1.SettingsSaving
        'Should check for settings changes first. 
        Dim dr As DialogResult = MessageBox.Show( _
            "Save current values for application settings?", "Save Settings", _
            MessageBoxButtons.YesNo)
        If (System.Windows.Forms.DialogResult.No = dr) Then
            e.Cancel = True 
        End If 
    End Sub 
End Class 

'Application settings wrapper class. This class defines the settings we intend to use in our application. 
NotInheritable Class FormSettings
    Inherits ApplicationSettingsBase

    <UserScopedSettingAttribute()> _
    Public Property FormText() As String 
        Get 
            Return CStr(Me("FormText"))
        End Get 
        Set(ByVal value As String)
            Me("FormText") = value
        End Set 
    End Property

    <UserScopedSettingAttribute(), DefaultSettingValueAttribute("0, 0")> _
    Public Property FormLocation() As Point
        Get 
            Return CType(Me("FormLocation"), Point)
        End Get 
        Set(ByVal value As Point)
            Me("FormLocation") = value
        End Set 
    End Property

    <UserScopedSettingAttribute(), DefaultSettingValueAttribute("225, 200")> _
    Public Property FormSize() As Size
        Get 
            Return CType(Me("FormSize"), Size)
        End Get 
        Set(ByVal value As Size)
            Me("FormSize") = value
        End Set 
    End Property

    <UserScopedSettingAttribute(), DefaultSettingValueAttribute("LightGray")> _
    Public Property FormBackColor() As Color
        Get 
            Return CType(Me("FormBackColor"), Color)
        End Get 
        Set(ByVal value As Color)
            Me("FormBackColor") = value
        End Set 
    End Property 
End Class

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

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

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

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

.NET Framework

Supported in: 3.5, 3.0, 2.0
Show: