mirror of
https://github.com/Stone-Red-Code/docs-desktop.git
synced 2026-09-07 23:43:19 +02:00
Initial winforms content migrated (#18)
* Merge winforms framework content to working branch (#14) * Breadcrumb / TOC / Move net5 to net folder (#15) * change path from net5 to net * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Add .net 5 winforms placeholder article (#16) * added some metadata and adjusted net5 placeholder * corrections * corrections * corrections * Test1 * Swapping landing page vs concept * fix links * Fix links * Fix desc
This commit is contained in:
Andy De George
+163
@@ -0,0 +1,163 @@
|
||||
---
|
||||
title: "How to: Validate Application Settings"
|
||||
ms.date: "03/30/2017"
|
||||
dev_langs:
|
||||
- "csharp"
|
||||
- "vb"
|
||||
helpviewer_keywords:
|
||||
- "validating application settings"
|
||||
- "application settings [Windows Forms], Windows Forms"
|
||||
- "application settings [Windows Forms], validating"
|
||||
ms.assetid: 9f145ada-4267-436a-aa4c-c4dcffd0afb7
|
||||
---
|
||||
# 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. <xref:System.Configuration.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|
|
||||
|-----------|------------------------|
|
||||
|<xref:System.Configuration.ApplicationSettingsBase.SettingsLoaded>|Occurs after the initial loading of a settings property group.<br /><br /> Use this event to validate initial values for the entire property group before they are used within the application.|
|
||||
|<xref:System.Configuration.ApplicationSettingsBase.SettingChanging>|Occurs before the value of a single settings property is changed.<br /><br /> Use this event to validate a single property before it is changed. It can provide immediate feedback to users regarding their actions and choices.|
|
||||
|<xref:System.Configuration.ApplicationSettingsBase.PropertyChanged>|Occurs after the value of a single settings property is changed.<br /><br /> 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.|
|
||||
|<xref:System.Configuration.ApplicationSettingsBase.SettingsSaving>|Occurs before the settings property group is stored.<br /><br /> 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 <xref:System.Configuration.ApplicationSettingsBase.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 <xref:System.Configuration.ApplicationSettingsBase.SettingChanging> and <xref:System.Configuration.ApplicationSettingsBase.SettingsSaving>, uses the <xref:System.ComponentModel.CancelEventArgs> argument to cancel the operation.
|
||||
|
||||
For more information about event handling, see [Event Handlers Overview](../event-handlers-overview-windows-forms.md).
|
||||
|
||||
The following procedures show how to test for a valid birth date using either the <xref:System.Configuration.ApplicationSettingsBase.SettingChanging> or the <xref:System.Configuration.ApplicationSettingsBase.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](how-to-create-application-settings.md).
|
||||
|
||||
### 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.
|
||||
|
||||
```csharp
|
||||
Configuration.Settings.Default
|
||||
```
|
||||
|
||||
```vb
|
||||
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](https://docs.microsoft.com/dotnet/visual-basic/language-reference/objects/my-settings-object).
|
||||
|
||||
-or-
|
||||
|
||||
- If you created your settings by deriving from <xref:System.Configuration.ApplicationSettingsBase> directly, you need to instantiate your class manually.
|
||||
|
||||
```csharp
|
||||
MyCustomSettings settings = new MyCustomSettings();
|
||||
```
|
||||
|
||||
```vb
|
||||
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 <xref:System.Configuration.ApplicationSettingsBase.SettingChanging> event.
|
||||
|
||||
-or-
|
||||
|
||||
If you are a Visual Basic developer, you should declare the `Settings` variable using the `WithEvents` keyword.
|
||||
|
||||
```csharp
|
||||
public void Form1_Load(Object sender, EventArgs e)
|
||||
{
|
||||
settings.SettingChanging += new SettingChangingEventHandler(MyCustomSettings_SettingChanging);
|
||||
}
|
||||
```
|
||||
|
||||
```vb
|
||||
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.
|
||||
|
||||
```csharp
|
||||
private void MyCustomSettings_SettingChanging(Object sender, SettingChangingEventArgs e)
|
||||
{
|
||||
if (e.SettingName.Equals("DateOfBirth"))
|
||||
{
|
||||
var newDate = (DateTime)e.NewValue;
|
||||
if (newDate > DateTime.Now)
|
||||
{
|
||||
e.Cancel = true;
|
||||
// Inform the user.
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```vb
|
||||
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 <xref:System.Configuration.ApplicationSettingsBase.SettingsSaving> event.
|
||||
|
||||
```csharp
|
||||
public void Form1_Load(Object sender, EventArgs e)
|
||||
{
|
||||
settings.SettingsSaving += new SettingsSavingEventHandler(MyCustomSettings_SettingsSaving);
|
||||
}
|
||||
```
|
||||
|
||||
```vb
|
||||
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.
|
||||
|
||||
```csharp
|
||||
private void MyCustomSettings_SettingsSaving(Object sender, SettingsSavingEventArgs e)
|
||||
{
|
||||
if (this["DateOfBirth"] > Date.Now) {
|
||||
e.Cancel = true;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```vb
|
||||
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
|
||||
|
||||
- [Creating Event Handlers in Windows Forms](../creating-event-handlers-in-windows-forms.md)
|
||||
- [How to: Create Application Settings](how-to-create-application-settings.md)
|
||||
Reference in New Issue
Block a user