ApplicationSettingsBase Class
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Acts as a base class for deriving concrete wrapper classes to implement the application settings feature in Window Forms applications.
public ref class ApplicationSettingsBase abstract : System::Configuration::SettingsBase, System::ComponentModel::INotifyPropertyChanged
public abstract class ApplicationSettingsBase : System.Configuration.SettingsBase, System.ComponentModel.INotifyPropertyChanged
type ApplicationSettingsBase = class
inherit SettingsBase
interface INotifyPropertyChanged
Public MustInherit Class ApplicationSettingsBase
Inherits SettingsBase
Implements INotifyPropertyChanged
- Inheritance
- Implements
Examples
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
.
#using <System.dll>
#using <System.Drawing.dll>
#using <System.Windows.Forms.dll>
using namespace System;
using namespace System::ComponentModel;
using namespace System::Drawing;
using namespace System::Configuration;
using namespace System::Windows::Forms;
namespace AppSettingsSample
{
//Application settings wrapper class
ref class FormSettings sealed: public ApplicationSettingsBase
{
public:
[UserScopedSettingAttribute()]
property String^ FormText
{
String^ get()
{
return (String^)this["FormText"];
}
void set( String^ value )
{
this["FormText"] = value;
}
}
public:
[UserScopedSettingAttribute()]
[DefaultSettingValueAttribute("0, 0")]
property Point FormLocation
{
Point get()
{
return (Point)(this["FormLocation"]);
}
void set( Point value )
{
this["FormLocation"] = value;
}
}
public:
[UserScopedSettingAttribute()]
[DefaultSettingValueAttribute("225, 200")]
property Size FormSize
{
Size get()
{
return (Size)this["FormSize"];
}
void set( Size value )
{
this["FormSize"] = value;
}
}
public:
[UserScopedSettingAttribute()]
[DefaultSettingValueAttribute("LightGray")]
property Color FormBackColor
{
Color get()
{
return (Color)this["FormBackColor"];
}
void set(Color value)
{
this["FormBackColor"] = value;
}
}
};
ref class AppSettingsForm : Form
{
/// <summary>
/// Required designer variable.
/// </summary>
private:
System::ComponentModel::IContainer^ components;
/// <summary>
/// Clean up any resources being used. The Dispose(true)
/// pattern for embedded objects is implemented with this
/// code that just contains a destructor
/// </summary>
public:
~AppSettingsForm()
{
if (components != nullptr)
{
delete components;
}
}
#pragma region Windows Form Designer generated code
/// <summary>
/// Required method for Designer support - do not modify
/// the contents of this method with the code editor.
/// </summary>
private:
void InitializeComponent()
{
this->components = nullptr;
this->colorDialog = gcnew System::Windows::Forms::ColorDialog();
this->backColorButton = gcnew System::Windows::Forms::Button();
this->resetButton = gcnew System::Windows::Forms::Button();
this->statusDisplay = gcnew System::Windows::Forms::TextBox();
this->reloadButton = gcnew System::Windows::Forms::Button();
this->SuspendLayout();
//
// backColorButton
//
this->backColorButton->Location = System::Drawing::Point(26, 24);
this->backColorButton->Name = "backColorButton";
this->backColorButton->Size = System::Drawing::Size(159, 23);
this->backColorButton->TabIndex = 0;
this->backColorButton->Text = "Change Background Color";
this->backColorButton->Click += gcnew System::EventHandler
(this,&AppSettingsForm::BackColorButton_Click);
//
// resetButton
//
this->resetButton->Location = System::Drawing::Point(26, 90);
this->resetButton->Name = "resetButton";
this->resetButton->Size = System::Drawing::Size(159, 23);
this->resetButton->TabIndex = 1;
this->resetButton->Text = "Reset to Defaults";
this->resetButton->Click += gcnew System::EventHandler
(this,&AppSettingsForm::ResetButton_Click);
//
// statusDisplay
//
this->statusDisplay->Location = System::Drawing::Point(26, 123);
this->statusDisplay->Name = "statusDisplay";
this->statusDisplay->Size = System::Drawing::Size(159, 20);
this->statusDisplay->TabIndex = 2;
//
// reloadButton
//
this->reloadButton->Location = System::Drawing::Point(26, 57);
this->reloadButton->Name = "reloadButton";
this->reloadButton->Size = System::Drawing::Size(159, 23);
this->reloadButton->TabIndex = 3;
this->reloadButton->Text = "Reload from Storage";
this->reloadButton->Click += gcnew System::EventHandler
(this,&AppSettingsForm::ReloadButton_Click);
//
// AppSettingsForm
//
this->ClientSize = System::Drawing::Size(217, 166);
this->Controls->Add(this->reloadButton);
this->Controls->Add(this->statusDisplay);
this->Controls->Add(this->resetButton);
this->Controls->Add(this->backColorButton);
this->Name = "AppSettingsForm";
this->Text = "App Settings";
this->FormClosing += gcnew
System::Windows::Forms::FormClosingEventHandler
(this,&AppSettingsForm::AppSettingsForm_FormClosing);
this->Load += gcnew System::EventHandler(this,
&AppSettingsForm::AppSettingsForm_Load);
this->ResumeLayout(false);
this->PerformLayout();
}
#pragma endregion
private:
System::Windows::Forms::ColorDialog^ colorDialog;
System::Windows::Forms::Button^ backColorButton;
System::Windows::Forms::Button^ resetButton;
System::Windows::Forms::TextBox^ statusDisplay;
System::Windows::Forms::Button^ reloadButton;
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;
}
}
};
partial class Form1 : Form
{
private FormSettings frmSettings1 = new FormSettings();
public Form1()
{
InitializeComponent();
}
private void Form1_Load(object sender, EventArgs e)
{
this.FormClosing += new FormClosingEventHandler(Form1_FormClosing);
//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 bndLocation = new Binding("Location", frmSettings1,
"FormLocation", true, DataSourceUpdateMode.OnPropertyChanged);
this.DataBindings.Add(bndLocation);
// Assign Size property, since databinding to Size doesn't work well.
this.Size = frmSettings1.FormSize;
//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.FormSize = this.Size;
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; }
}
[UserScopedSettingAttribute()]
[DefaultSettingValueAttribute("0, 0")]
public Point FormLocation
{
get { return (Point)(this["FormLocation"]); }
set { this["FormLocation"] = value; }
}
[UserScopedSettingAttribute()]
[DefaultSettingValueAttribute("225, 200")]
public Size FormSize
{
get { return (Size)this["FormSize"]; }
set { this["FormSize"] = value; }
}
[UserScopedSettingAttribute()]
[DefaultSettingValueAttribute("LightGray")]
public Color FormBackColor
{
get { return (Color)this["FormBackColor"]; }
set { this["FormBackColor"] = value; }
}
}
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
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.
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
andset
accessors for read/write application settings, but only aget
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.
Constructors
ApplicationSettingsBase() |
Initializes an instance of the ApplicationSettingsBase class to its default state. |
ApplicationSettingsBase(IComponent) |
Initializes an instance of the ApplicationSettingsBase class using the supplied owner component. |
ApplicationSettingsBase(IComponent, String) |
Initializes an instance of the ApplicationSettingsBase class using the supplied owner component and settings key. |
ApplicationSettingsBase(String) |
Initializes an instance of the ApplicationSettingsBase class using the supplied settings key. |
Properties
Context |
Gets the application settings context associated with the settings group. |
IsSynchronized |
Gets a value indicating whether access to the object is synchronized (thread safe). (Inherited from SettingsBase) |
Item[String] |
Gets or sets the value of the specified application settings property. |
Properties |
Gets the collection of settings properties in the wrapper. |
PropertyValues |
Gets a collection of property values. |
Providers |
Gets the collection of application settings providers used by the wrapper. |
SettingsKey |
Gets or sets the settings key for the application settings group. |
Methods
Equals(Object) |
Determines whether the specified object is equal to the current object. (Inherited from Object) |
GetHashCode() |
Serves as the default hash function. (Inherited from Object) |
GetPreviousVersion(String) |
Returns the value of the named settings property for the previous version of the same application. |
GetType() |
Gets the Type of the current instance. (Inherited from Object) |
Initialize(SettingsContext, SettingsPropertyCollection, SettingsProviderCollection) |
Initializes internal properties used by SettingsBase object. (Inherited from SettingsBase) |
MemberwiseClone() |
Creates a shallow copy of the current Object. (Inherited from Object) |
OnPropertyChanged(Object, PropertyChangedEventArgs) |
Raises the PropertyChanged event. |
OnSettingChanging(Object, SettingChangingEventArgs) |
Raises the SettingChanging event. |
OnSettingsLoaded(Object, SettingsLoadedEventArgs) |
Raises the SettingsLoaded event. |
OnSettingsSaving(Object, CancelEventArgs) |
Raises the SettingsSaving event. |
Reload() |
Refreshes the application settings property values from persistent storage. |
Reset() |
Restores the persisted application settings values to their corresponding default properties. |
Save() |
Stores the current values of the application settings properties. |
ToString() |
Returns a string that represents the current object. (Inherited from Object) |
Upgrade() |
Updates application settings to reflect a more recent installation of the application. |
Events
PropertyChanged |
Occurs after the value of an application settings property is changed. |
SettingChanging |
Occurs before the value of an application settings property is changed. |
SettingsLoaded |
Occurs after the application settings are retrieved from storage. |
SettingsSaving |
Occurs before values are saved to the data store. |
Applies to
See also
.NET