Article ID: 893664 - View products that this article applies to.
Beta InformationThis article discusses a Beta release of a Microsoft product. The information in this article is provided as-is and is subject to change without notice.
No formal product support is available from Microsoft for this Beta product. For information about how to obtain support for a Beta release, see the documentation that is included with the Beta product files, or check the Web location where you downloaded the release.
ASP.NET Support Voice ColumnTo customize this column to your needs, we invite you to submit your ideas about topics that interest you and issues that you want to see addressed in future Knowledge Base articles and Support Voice columns. You can submit your ideas and feedback by using the Ask For It
(http://support.microsoft.com/common/survey.aspx?scid=sw;en;1176&p0=&p1=&p2=&p3=&p4=)form. There's also a link to the form at the bottom of this column.
Welcome to the ASP.NET Support Voice column! My name is Jerry Orman. I have been with Microsoft over 5 years, and have spent most of my time focused on Web-related technologies such as FrontPage and the new SharePoint technologies. I have spent the last year working with ASP.NET as a support engineer.
This month in the Support Voice column, I am going to describe the new Web Events feature provided in the upcoming release of ASP.NET 2.0.
The Web Events feature in ASP.NET 2.0One of the major new services provided in ASP.NET 2.0 is the Web Events feature provided by the health monitoring system. By modifying the Web.config file, you can use the health monitoring system to log unhandled exceptions, expired forms, authentication tickets, and any other data you want logged in your application. This column will get you started using the Web Events feature, and will also provide examples of how to use the various providers in ASP.NET 2.0.
Logging is accomplished by defining a rule that associates events with a provider. The rule defines the type of events that are sent to the provider. The following base events are available for you to log:
The types of providers available allow you to send event output to Event Viewer, SQL Server, Windows Management Instrumentation (WMI), and e-mail. The pre-configured providers and event mappings reduce the amount of work necessary to get event output logged.
Collapse this tableExpand this table
ASP.NET 2.0 uses the Event Log provider out-of-the-box to log events based on application domains starting and stopping, as well as logging any unhandled exceptions. This helps to cover some of the basic scenarios. For example, let's say that your application throws an exception, but the user doesn't save the error and you can't reproduce it. With the default Event Log rule, you would be able to gather the exception and stack information to get a better idea of what kind of error occurred. Or, if your application is losing session state, you can look in the Event Log to determine whether the application domain is recycling, and why the application domain stopped in the first place.
Also, the health monitoring system is extensible. For example, you can define custom Web events, fire them within your application, and then define a rule to send the event information to a provider such as your e-mail. This allows you to easily tie your instrumentation to the health monitoring providers. As another example, you could fire an event each time an order is processed and set up a rule that sends each event to the SQL Server database. You could also fire an event when a user fails to log on multiple times in a row, and set up the event to use the e-mail-based providers.
The configuration for the default providers and events is stored in the global Web.config file. The global Web.config file stores all the Web-based settings that were stored in the Machine.config file in ASP.NET 1x. The global Web.config file is located in the following directory:
%windir%\Microsoft.Net\Framework\v2.0.*\config\Web.configThe <healthMonitoring> section of the global Web.config file provides default configuration settings. You can override these setting or configure your own settings by implementing the <healthMonitoring> section in the Web.config file for your application.
The <healthMonitoring> section of the global Web.config file contains the following items:
Provider sampleThis provider sample contains the following files:
How to store events to Event ViewerAs I mentioned earlier, the provider for logging events in the Event Viewer is configured for you in the global Web.config file. By default, all events based on WebBaseErrorEvent and WebFailureAuditEvent are logged. You can add additional rules to log additional information to the Event Log. For example, if you wanted to log all events (i.e., every event based on WebBaseEvent), you could add the following rule to your Web.config file:
This rule would link the All Events event map to the Event Log provider. Both eventMapping and the provider are included in the global Web.config file. You can then use the ViewEvents.aspx page to trigger the events generated by browsing the page. The page will also fire the MyEvent custom event in the Page_Load and a Button Click event.
To see the type of data generated, browse the Default.aspx page. This will throw a System.NullReferenceException exception, and the following event will be logged in the Event Viewer:
Event Type: Warning
How to store events to SQL ServerThis method uses the ASPNETDB database, which is generated by the Aspnet_regsql.exe tool. The default provider uses the LocalSqlServer connection string, which uses either a file-based database in the App_data folder or the local SQLExpress instance of SQL Server. Both the LocalSqlServer connection string and the SqlProvider are configured in the global Web.config file.
The LocalSqlServer connection string in the global Web.config file looks like this:
If you want to use another SQL Server server, you'll need to use the Aspnet_regsql.exe tool, which can be found in the %windir%\Microsoft.Net\Framework\v2.0.*\Aspnet_regsql.exe folder. Use the Aspnet_regsql.exe tool to generate a custom ASPNETDB database on the SQL Server server, then add the connection string to your applications .config file, and then add a provider by using the new connection string. Once you have the ASPNETDB database created, you'll need to set a rule to link an eventMapping to the sqlProvider.
To configure a custom database, follow these steps:
If you wanted to only send errors to SQL Server, you could add the following rule:
How to forward events to WMIYou can also forward the events to WMI. The WMI provider is configured for you in the global Web.config file by default.
The following code example adds a rule to forward the events to WMI:
You will need to add a rule to associate an eventMapping to the provider, and also a WMI listener application to listen for the events. The following code example adds a rule to link the WMI provider to the All Events event map:
The sample console application SampleASPNET uses the ManagementEventWatcher object to monitor for events and display them in the console window.
To use SampleASPNET, follow these steps:
Note If you are monitoring events on a remote computer, the listening application needs to be running on that computer as an account with admin access.
Collapse this imageExpand this image
How to forward events to e-mailYou can also forward events to e-mail. This would allow you to get information about your application directly in your (probably overflowing) Inbox. Be careful about which event rules you map to your e-mail provider, as you can unintentionally send yourself a lot of information that may be better suited for SQL Server or the Event Log.
There are two e-mail providers, SimpleMailWebEventProvider and TemplatedMailWebEventProvider. Each has the same configuration attributes, with the exception of the "template" and "detailedTemplateErrors" attributes, which are only available on the TemplatedMailWebEventProvider.
Note Neither of these e-mail providers is configured for you. You'll need to add them to your Web.config file.
The main difference between these two e-mail providers is that SimpleMailWebEventProvider sends e-mails in a generic template that cannot be modified. The sample Web.config file adds this e-mail provider to the list of configured providers by using the following rule:
The following rule is also added to tie the e-mail provider to the All Events event map:
The e-mail alert message is similar to the following: The following is an e-mail alert message that shows an unhandled exception: TemplatedMailWebEventProvider allows you to specify an ASPX page as a -- you guessed it -- template. The output of the ASPX page is used in the body of the e-mail, allowing you to customize the look of the data you receive.
The sample application uses the following code to add TemplatedMailWebEventProvider to the Web.config file and specify the EmailTemplateTest.aspx page as the template. (The EmailTemplateTest.aspx page loops through the available events in the buffer, and displays them in a table.)
The e-mail alert message is similar to the following: In both cases, if the buffer attribute is false, the e-mail will contain only one event. With buffering set to true, you also need to specify a bufferMode, which indicates how often to flush the buffer. There are some default bufferModes in the global Web.config file.
If detailedTemplateErrors="true", then any errors that occur when you execute the template will be sent in the body of the e-mail. If detailedTemplateErrors="false", a generic error is sent.
A detailed error thrown by EmailTemplateTest.aspx looks like this:
If the attribute is false and there is an error, you will only get a generic error message, which looks like this:
Server Error in '/WebSite3' Application.
An unhandled exception occurred during the execution of the template page used to create this event notification. The 1 events that were part of this message were discarded.
Description: An unhandled exception occurred during the execution of the current web request. Please review the stack trace for more information about the error and where it originated in the code.
Exception Details: System.Web.HttpException: Session state can only be used when enableSessionState is set to true, either in a configuration file or in the Page directive. Please also make sure that System.Web.SessionStateModule or a custom session state module is included in the <configuration>\<system.web>\<httpModules> section in the application configuration.
Source File: c:\Documents and Settings\user\Desktop\WebEvents\WebSite3\WebSite3\e-mailTemplateTest.aspx.cs Line: 17
Stack Trace: [HttpException (0x80004005): Session state can only be used when enableSessionState is set to true, either in a configuration file or in the Page directive. Please also make sure that System.Web.SessionStateModule or a custom session state module is included in the <configuration>\<system.web>\<httpModules> section in the application configuration.]
e-mailTemplateTest.Page_Load(Object sender, EventArgs e) in c:\Documents and Settings\user\Desktop\WebEvents\WebSite3\WebSite3\e-mailTemplateTest.aspx.cs:17
System.Web.Util.CalliHelper.EventArgFunctionCaller(IntPtr fp, Object o, Object t, EventArgs e) +13
System.Web.Util.CalliEventHandlerDelegateProxy.Callback(Object sender, EventArgs e) +45
System.Web.UI.Control.OnLoad(EventArgs e) +80
System.Web.UI.Page.ProcessRequestMain(Boolean includeStagesBeforeAsyncPoint, Boolean includeStagesAfterAsyncPoint) +3749
[HttpUnhandledException (0x80004005): Exception of type 'System.Web.HttpUnhandledException' was thrown.]
System.Web.UI.Page.HandleError(Exception e) +929
System.Web.UI.Page.ProcessRequestMain(Boolean includeStagesBeforeAsyncPoint, Boolean includeStagesAfterAsyncPoint) +7864
System.Web.UI.Page.ProcessRequest(Boolean includeStagesBeforeAsyncPoint, Boolean includeStagesAfterAsyncPoint) +229
System.Web.UI.Page.ProcessRequest(HttpContext context) +80
System.Web.HttpServerUtility.ExecuteInternal(IHttpHandler handler, TextWriter writer, Boolean preserveForm, VirtualPath path, VirtualPath filePath, String physPath, Exception error, String queryStringOverride) +1012
[HttpException (0x80004005): Error executing child request for /WebSite3/e-mailTemplateTest.aspx.]
System.Web.HttpServerUtility.ExecuteInternal(IHttpHandler handler, TextWriter writer, Boolean preserveForm, VirtualPath path, VirtualPath filePath, String physPath, Exception error, String queryStringOverride) +1525
System.Web.HttpServerUtility.Execute(String path, TextWriter writer, Boolean preserveForm) +754
System.Web.HttpServerUtility.ExecuteLocalRequestAndCaptureResponse(String path, TextWriter writer, ErrorFormatterGenerator errorFormatterGenerator) +249
Note For the buffering-related attributes, every flush results in a notification. If the flush contains more events than maxEventsPerMessage allows, the notification will be broken up into multiple e-mails, but they are all still considered to be the same notification. For example, a flush generates 13 events, but maxEventsPerMessage only allows five. You will get three e-mails: the first two e-mails will each contain five events, and the third e-mail will contain three events.
Server Error in '/WebSite3' Application.
An unhandled exception occurred during the execution of the template page used to create this event notification. The 8 events that were part of this message were discarded.
Description: The current configuration prevents the exception details from being included in this message. Add the "detailedTemplateErrors=true" attribute to the provider configuration to enable exception details to be reported.
If there are more e-mails than maxMessagesPerNotification allows, some events are dropped. For example, if you set maxMessagesPerNotification to two and you use the same maxEventsPerMessage as above, you would only receive two e-mails. The events that would be on the third e-mail are dropped. Any drops or truncation of notifications will be noted in one of the e-mails for the simple mail provider. The top of the e-mail will show the following: Since you have control of the format of the e-mail for the templated provider, you have to check for drops/truncation yourself and determine whether to include that in the e-mail.
Note Mail providers use System.Net.Mail, so you have to configure System.Net.Mail in your Web.config file.
For more information on the ASP.NET settings schema, visit the following Microsoft Web site:
healthMonitoring Element (ASP.NET Settings Schema)For more information about health monitoring in ASP.NET 2.0, visit the following Microsoft Web site:
How to use health monitoring in ASP.NET 2.0
As always, feel free to submit ideas on topics you want addressed in future columns or in the Knowledge Base by using the Ask For It
Article ID: 893664 - Last Review: September 10, 2012 - Revision: 4.0
Retired KB Content Disclaimer
This article was written about products for which Microsoft no longer offers support. Therefore, this article is offered "as is" and will no longer be updated.