System 2.0.0.0 4.0.0.0 System.Configuration.SettingsBase System.ComponentModel.INotifyPropertyChanged

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

The ability to detect attributes on a derived, settings wrapper class. supports the declarative model used for wrapper class properties, as described later.

Higher-level and 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 . The wrapper class customizes 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 or . Application-scoped settings are read-only if the default is used.

The 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 , then a name is automatically generated.

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

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

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

- Constructor
  2.0.0.0
  4.0.0.0

  The default constructor was designed to work under the assumption that there is no component associated with the current settings wrapper class, which derives from .

  When an instance of a wrapper class is created, inherited code will automatically perform the following actions:

  Reflect over the class.

  For each property on the wrapper marked with either [UserScopedSettingAttribute] or [ApplicationScopedSettingAttribute], a corresponding is created.

  Each has some of its properties set based on other attributes that are optionally present on the wrapper's properties, such as the default value or the settings provider.

  All other attributes are simply put into an attribute bag, the property of the class.

  All objects are added to a represented by the property of the class. This collection is then passed to the method.

  As implied by step 3 mentioned previously, natively works with several property attributes, specifically the following: , , and . All other settings attributes are simply passed through to the appropriate underlying provider.

  Initializes an instance of the class to its default state.

- Constructor
  2.0.0.0
  4.0.0.0

  This constructor is exactly equivalent to the constructor using the invocation:

  ApplicationSettingsBase(owner, String.Empty)

  For information about how reflection is used during the instantiation of a wrapper class, see the default constructor.

  Initializes an instance of the class using the supplied owner component.

  The component that will act as the owner of the application settings object.
- Constructor
  2.0.0.0
  4.0.0.0

  This constructor initializes the property to the value of the parameter. This property is useful in disambiguating different instances of the settings wrapper class in the same application domain.

  For information about how reflection is used during the instantiation of a wrapper class, see the default constructor.

  Initializes an instance of the class using the supplied settings key.

  A that uniquely identifies separate instances of the wrapper class.
- Constructor
  2.0.0.0
  4.0.0.0

  The object specified by the parameter acts as the owner of the current instance of this applications settings class. During the initialization of the settings wrapper class derived from , the owner's site is queried for a . If one exists, it is used in preference to native settings provider for all the properties of the wrapper class, as specified by the .

  This constructor initializes the property to the value of the parameter. This property is useful in disambiguating different instances of the wrapper class in the same application domain.

  For information about how reflection is used during the instantiation of a wrapper class, see the default constructor.

  Initializes an instance of the class using the supplied owner component and settings key.

  The component that will act as the owner of the application settings object.
  A that uniquely identifies separate instances of the wrapper class.
- Property
  2.0.0.0
  4.0.0.0
  System.ComponentModel.Browsable(false)
  System.Configuration.SettingsContext To be added.

  Each settings wrapper class derived from has a context associated with it. The context is passed to the settings provider for each property to identify how the property is used. Context therefore acts as a hint to help the settings provider determine how best to persist the associated application settings values.

  In contrast, the property enables the settings provider to disambiguate multiple instances of the same wrapper class.

  Gets the application settings context associated with the settings group.

- Method
  2.0.0.0
  4.0.0.0
  System.Object ``

  The method is often used in conjunction with the method when migrating application settings during the installation of a new version of an application.

  Returns the value of the named settings property for the previous version of the same application.

  An containing the value of the specified if found; otherwise, null.

  A containing the name of the settings property whose value is to be returned.
- Property
  2.0.0.0
  4.0.0.0
  System.MonoTODO
  System.Object `` To be added. To be added. To be added. To be added.
- Method
  2.0.0.0
  4.0.0.0
  System.Void `` ``

  Raising an event invokes the event handler through a delegate. For more information, see Raising an Event.

  The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

  Raises the event.

  The source of the event. A that contains the event data.
- Method
  2.0.0.0
  4.0.0.0
  System.Void `` ``

  Raising an event invokes the event handler through a delegate. For more information, see Raising an Event.

  The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

  Raises the event.

  The source of the event. A that contains the event data.
- Method
  2.0.0.0
  4.0.0.0
  System.Void `` ``

  Raising an event invokes the event handler through a delegate. For more information, see Raising an Event.

  The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

  Raises the event.

  The source of the event. A that contains the event data.
- Method
  2.0.0.0
  4.0.0.0
  System.Void `` ``

  Raising an event invokes the event handler through a delegate. For more information, see Raising an Event.

  The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

  Raises the event.

  The source of the event. A that contains the event data.
- Property
  2.0.0.0
  4.0.0.0
  System.ComponentModel.Browsable(false)
  System.Configuration.SettingsPropertyCollection To be added.

  The get accessor of the property reflects over the metadata of the settings wrapper class, which is derived from , to dynamically determine the set of available application settings properties.

  The class natively recognizes certain characteristics of an application setting, such as its name, property type, settings provider, default value, read only status, and a serialization preference. These characteristics are mirrored as properties in the class. All other attributes of the settings property are just passed through to its associated settings provider.

  Gets the collection of settings properties in the wrapper.

- Event
  2.0.0.0
  4.0.0.0
  System.ComponentModel.PropertyChangedEventHandler

  The event is raised when a settings property is changed through the set accessor of the method, or for every property that is restored when a call is made to the or methods.

  There is no corresponding PropertyChanging event for this class; instead, see the event.

  Occurs after the value of an application settings property is changed.

- Property
  2.0.0.0
  4.0.0.0
  System.ComponentModel.Browsable(false)
  System.Configuration.SettingsPropertyValueCollection To be added. To be added.

  Gets a collection of property values.

- Property
  2.0.0.0
  4.0.0.0
  System.ComponentModel.Browsable(false)
  System.Configuration.SettingsProviderCollection To be added.

  The determines what setting provider is used by a settings wrapper class or an individual setting property. If this attribute is not specified, a client application will use the .

  Gets the collection of application settings providers used by the wrapper.

- Method
  2.0.0.0
  4.0.0.0
  System.Void

  The method clears the currently cached property values, causing a reload of these values from persistent storage when they are subsequently accessed. This method performs the following actions:

  It clears the currently cached properties by clearing the collection represented by the property.

  It raises the event for every member of the collection.

  contrasts with in that the former will load the last set of saved application settings values, whereas the latter will load the saved default values.

  Refreshes the application settings property values from persistent storage.

- Method
  2.0.0.0
  4.0.0.0
  System.Void

  The method overwrites the user-scoped settings properties by restoring the currently persisted value of each application settings. This method performs the following actions:

  It calls the method on every settings provider that supports this optional method.

  It calls the method to force a refresh of the settings property values.

  contrasts with in that the former will load the last set of saved application settings values, whereas the latter will load the saved default values.

  Restores the persisted application settings values to their corresponding default properties.

- Method
  2.0.0.0
  4.0.0.0
  System.Void

  The method writes the current value of each settings property to its associated data store. For each property, this method calls the method on the associated settings provider.

  This method differs from the base class implementation in that it raises the event before the values are written.

  If the only settings defined are application-scoped settings, will have no effect and return no error if called with the default . only saves user-scoped settings.

  There is no corresponding Load method because the values of application settings are automatically loaded during wrapper class initialization. In contrast, these values are not automatically saved when an application ends. Therefore, you must explicitly call the method to persist the current values of the application settings. This is typically performed in the event handler of the primary or containing .

  Stores the current values of the application settings properties.

- Event
  2.0.0.0
  4.0.0.0
  System.Configuration.SettingChangingEventHandler

  The event occurs before an application setting value property is changed through the method. This event is not raised when the or methods are called. can be canceled through the event data class.

  You typically use the event to handle immediate validation of an individual settings property. For more information about validation, see How to: Validate Application Settings.

  There is no corresponding SettingChanged event for this class; instead, see the event.

  Occurs before the value of an application settings property is changed.

- Property
  2.0.0.0
  4.0.0.0
  System.ComponentModel.Browsable(false)
  System.String To be added.

  The property is provided to enable client code, and in particular the settings provider, to disambiguate between multiple instances of the same application settings class.

  Unless the settings wrapper class is designed using the singleton pattern, there can be multiple instances of the same application settings class in a single application. The value of should be set according to how the property values are intended to be shared.

  If the settings properties of the wrapper are intended to be shared across all instances of the wrapper in the same application, then should have the same value in all of the instances. This is the default behavior of the class.

  If the settings properties of the wrapper are intended to be per instance, then should have a unique value for every instance. The version of the constructor enables you to initialize to a unique string.

  In contrast, the property provides hints to the settings provider to enable it to persist values in an efficient and orderly manner.

  The class contains a similar property that helps identify the source of the event.

  Gets or sets the settings key for the application settings group.

- Event
  2.0.0.0
  4.0.0.0
  System.Configuration.SettingsLoadedEventHandler

  The event occurs only after the initial get access of the first configuration property used, typically through the method. Subsequent accesses use values for the settings property that are cached locally. The and methods will clear all cached values so this event will be raised again upon subsequent property access.

  Occurs after the application settings are retrieved from storage.

- Event
  2.0.0.0
  4.0.0.0
  System.Configuration.SettingsSavingEventHandler

  The event is raised by the method before it stores the application settings properties to their associated data store. The associated event handler can cancel this event.

  Occurs before values are saved to the data store.

- Method
  2.0.0.0
  4.0.0.0
  System.Void

  The method performs two actions to assure smooth transition to a new version of an application:

  It notifies all of the corresponding settings providers of the existence of the upgraded application through a call to their method, assuming they have implemented the interface. This action is not performed if the settings wrapper class is marked with .

  It reloads the values for all of the application settings.

  You can override the default behavior of to implement custom upgrading or merging behavior. Use the method to retrieve individual values for a setting for the previous version of the application. Examples of custom upgrade behavior include:

  Using new policy defaults that override one or more of the previous user-specified values or previous defaults.

  Special translation of old values to be compatible with newer ranges, a different settings property group, and so on.

  Updates application settings to reflect a more recent installation of the application.