SendMailErrorEventArgs.Handled Property
Assembly: System.Web (in system.web.dll)
/** @property */ public boolean get_Handled () /** @property */ public void set_Handled (boolean value)
public function get Handled () : boolean public function set Handled (value : boolean)
Not applicable.
Property Value
If true, the exception is consumed and handled by the SendMailErrorEventHandler delegate. If false, the exception is rethrown, including the original call stack and error message. The default is false.The Handled property indicates if the Exception has been handled. The exception is raised by the SMTP mail provider when an e-mail message cannot be sent by the ChangePassword control or the CreateUserWizard. The most common reason for the exception is a configuration error in the smtp Element (Network Settings) of the machine configuration file. Although an error like this is typically discovered during the development and debugging of an application, mail servers can fail unexpectedly in a production environment, and you must determine whether you want the entire application to fail in that situation. If not, handling the event allows your application to proceed.
If you do not create an event handler for the SendMailError event, or if you create an event handler but leave the Handled property set to false, your Web application will stop running if an error occurs when sending an e-mail message, and ASP.NET will display an error message. Handling the event allows your Web application to continue to run even though an exception has occurred. This is useful when it is not critical to send an e-mail message. For example, if the exception occurs when a user is working through a multi-step wizard, it can be advantageous to log the error, display an informative message to the user, and allow the user to complete the wizard.
The following code example demonstrates an ASP.NET page that uses a ChangePassword Web control, and includes an event handler for the SendMailError event named SendMailError. The code example assumes that the ASP.NET Web site has been configured to use ASP.NET membership and Forms authentication, and that a user has been created whose name and password are known to you. For more information, see How to: Implement Simple Forms Authentication.
If the password change succeeds, the code in the SendingMail event handler attempts to send an e-mail message to the user to confirm the change. SMTP must already be configured on the server in order for this code example to work. For information about how to configure an SMTP server, see How to: Configure an SMTP Virtual Server. For the purposes of this example, it is not necessary to configure an SMTP server; the example is constructed to test for a failure to send an e-mail message.
If a mail server is not configured correctly or some other error occurs and the e-mail message cannot be sent, the SendMailError function is called. A message is displayed to the user. In addition, an event is logged to the Windows Application event log with the assumption that an event source named MySamplesSite already exists. See the code example below to create the specified event source. For more information about creating an event source, see Server Event Handling in ASP.NET Web Pages. The Handled property of the SendMailErrorEventArgs object is set to true to indicate that the error has been handled.
Use the following code example if you need to programmatically add the event source named MySamplesSite to your Application log. This event source must exist in order for the first code example to work correctly. The following code example requires Administrator privileges.
Reference
SendMailErrorEventArgs ClassSendMailErrorEventArgs Members
System.Web.UI.WebControls Namespace
CreateUserWizard.SendMailError Event
ChangePassword.SendMailError Event
PasswordRecovery.SendMailError Event
MailMessage
Other Resources
Server Event Handling in ASP.NET Web PagesHandling and Raising Events
Web Site Administration Tool Application Tab