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.
Occurrence and use
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.
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.
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.
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 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.
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.
If you created your settings by deriving from ApplicationSettingsBase directly, you need to instantiate your class manually.
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
If you are a C# developer, in your form or control's Load event, add an event handler for the SettingChanging event.
If you are a Visual Basic developer, you should declare the Settings variable using the WithEvents keyword.
Define the event handler, and write the code inside of it to perform bounds checking on the birth date.