How to: Validate Application Settings

This topic demonstrates how to validate application settings before they are persisted.

Because application settings are strongly typed, you have some confidence that users cannot assign data of an incorrect type to a given setting. However, a user still may attempt to assign a value to a setting that falls outside of acceptable bounds—for example, supplying a birth date that occurs in the future. ApplicationSettingsBase, the parent class of all application settings classes, exposes four events to enable such bounds checking. Handling these events puts all of your validation code in a single location, rather than scattering it throughout your project.

The event you use depends upon when you need to validate your settings, as described in the following table.

Event	Occurrence and use
SettingsLoaded	Occurs after the initial loading of a settings property group. Use this event to validate initial values for the entire property group before they are used within the application.
SettingChanging	Occurs before the value of a single settings property is changed. Use this event to validate a single property before it is changed. It can provide immediate feedback to users regarding their actions and choices.
PropertyChanged	Occurs after the value of a single settings property is changed. Use this event to validate a single property after it is changed. This event is rarely used for validation unless a lengthy, asynchronous validation process is required.
SettingsSaving	Occurs before the settings property group is stored. Use this event to validate values for the entire property group before they are persisted to disk.

Typically, you will not use all of these events within the same application for validation purposes. For example, it is often possible to fulfill all validation requirements by handling only the SettingChanging event.

An event handler generally performs one of the following actions when it detects an invalid value:

• Automatically supplies a value known to be correct, such as the default value.

• Re-queries the user of server code for information.

• For events raised before their associated actions, such as SettingChanging and SettingsSaving, uses the CancelEventArgs argument to cancel the operation.

For more information about event handling, see Event Handlers Overview (Windows Forms).

The following procedures show how to test for a valid birth date using either the SettingChanging or the SettingsSaving event. The procedures were written under the assumption that you have already created your application settings; in this example, we will perform bounds checking on a setting named DateOfBirth. For more information about creating settings, see How to: Create Application Settings.

To obtain the application settings object

• Obtain a reference to the application settings object (the wrapper instance) by completing one of the following bulleted items:

  • If you created your settings using the Visual Studio Application Settings dialog box in the Property Editor, you can retrieve the default settings object generated for your language through the following expression.

    Configuration.Settings.Default 
    

    MySettings.Default 
    

    -or-

  • If you are a Visual Basic developer and you created your application settings using the Project Designer, you can retrieve your settings by using the My.Settings Object.

    -or-

  • If you created your settings by deriving from ApplicationSettingsBase directly, you need to instantiate your class manually.

    MyCustomSettings settings = new MyCustomSettings();
    

    Dim Settings as New MyCustomSettings()
    

The following procedures were written under the assumption that the application settings object was obtained by completing the last bulleted item in this procedure.

To validate Application Settings when a setting is changing

1. If you are a C# developer, in your form or control's Load event, add an event handler for the SettingChanging event.

   -or-

   If you are a Visual Basic developer, you should declare the Settings variable using the WithEvents keyword.

   public void Form1_Load(Object sender, EventArgs e) 
   {
       settings.SettingChanging += new SettingChangingEventHandler(MyCustomSettings_SettingChanging);
   }
   

   Public Sub Form1_Load(sender as Object, e as EventArgs)
       AddHandler settings.SettingChanging, AddressOf MyCustomSettings_SettingChanging
   End Sub 
   

2. Define the event handler, and write the code inside of it to perform bounds checking on the birth date.

   private void MyCustomSettings_SettingChanging(Object sender, SettingChangingEventArgs e)
   {
       if (e.SettingName.Equals("DateOfBirth")) {
           Date newDate = (Date)e.NewValue;
           If (newDate > Date.Now) {
               e.Cancel = true;
               // Inform the user.
           }
       }
   }
   

   Private Sub MyCustomSettings_SettingChanging(sender as Object, e as SettingChangingEventArgs) Handles Settings.SettingChanging
       If (e.SettingName.Equals("DateOfBirth")) Then
           Dim NewDate as Date = CType(e.NewValue, Date)
           If (NewDate > Date.Now) Then
               e.Cancel = True
               ' Inform the user.
           End If
       End If
   End Sub
   

To validate Application Settings when a Save occurs

1. In your form or control's Load event, add an event handler for the SettingsSaving event.

   public void Form1_Load(Object sender, EventArgs e) 
   {
       settings.SettingsSaving += new SettingsSavingEventHandler(MyCustomSettings_SettingsSaving);
   }
   

   Public Sub Form1_Load(Sender as Object, e as EventArgs)
       AddHandler settings.SettingsSaving, AddressOf MyCustomSettings_SettingsSaving
   End Sub
   

2. Define the event handler, and write the code inside of it to perform bounds checking on the birth date.

   private void MyCustomSettings_SettingsSaving(Object sender, SettingsSavingEventArgs e)
   {
       if (this["DateOfBirth"] > Date.Now) {
           e.Cancel = true;
       }
   }
   

   Private Sub MyCustomSettings_SettingsSaving(Sender as Object, e as SettingsSavingEventArgs)
       If (Me["DateOfBirth"] > Date.Now) Then
           e.Cancel = True
       End If
   End Sub
   

See Also

Tasks

How to: Create Application Settings

Other Resources

Creating Event Handlers in Windows Forms