How to: Implement and Raise Custom ASP.NET Health Monitoring Events

  • Article

The example in this section illustrates how to raise ASP.NET custom health monitoring events. When you add a custom event to your application, you must consider the following points:

  • How to set the scope for the health monitoring event. If the event is intended to be raised in all applications on a server, you must configure the event to have machine-wide scope. A preferred way to do this, as shown in this example, is to create an HTTP module that raises the custom event. You then install the module at the machine level. The module is called in all applications on the computer where it is installed.

  • When to raise a health monitoring event. You can raise health monitoring events at any time during request processing. Typical times to raise a custom WebRequestEvent are in the system BeginRequest event or EndRequest event.

The example demonstrates the following features:

Running the example requires the following:

To build the HTTP module

  • Place the source code from Raising Custom ASP.NET Health Monitoring Events Example in your ASP.NET application's App_Code directory in a file named SampleModule.vb or SampleModule.cs.

    Note

    If you already have source code in the App_Code directory of your application, you must add the version of the custom event provider that is written in the same language as the existing code in the directory.

    ASP.NET will compile the custom event provider code when a page in your application is requested. For more information, see Shared Code Folders in ASP.NET Web Site Projects.

    - Or-

  • Compile the custom event provider as a library and place the library in your ASP.NET application's Bin directory, or strongly name the assembly and place it in the global assembly cache (GAC).

    The following command example shows how you can compile the example using the command-line compiler.

    vbc /out:<example_name>.dll /t:library <example_name>.vb /r:System.Web.dll /r:System.Configuration.dll /r:<required namespace>

    csc /out:<example_name>.dll /t:library <example_name>.cs /r:System.Web.dll /r:System.Configuration.dll  /r:<required namespace>

    Note

    If you cannot execute the compiler command, you must add the .NET Framework installation path to the Windows PATH variable before running the command. In Windows, right-click My Computer, click Properties, click the Advanced tab, and then click the Environment Variables button. In the System variables list, double-click the Path variable. In the Variable value text box, add a semicolon (;) to the end of the existing values in the text box, and then type the path of your .NET Framework installation. The .NET Framework is usually installed in the Windows installation folder at \Microsoft.NET\Framework\versionNumber.

To configure the ASP.NET application to use the example

  1. If a file named Web.config already exists in the root folder of your ASP.NET application, open it. Otherwise, create a text file named Web.config and copy in the following text:

    <?xml version="1.0"?>
<configuration xmlns="https://schemas.microsoft.com/.NetConfiguration/v2.0">
  <system.web>
  </system.web>
</configuration>

  2. Inside the system.web tags, add the following httpModules element and healthMonitoring Element (ASP.NET Settings Schema) element.

    <httpModules>
  <add name="Raising Custom Web Events" 
    type="Samples.AspNet.Management.CustomWebEvents" 
  />
</httpModules>
<healthMonitoring 
  heartbeatInterval="0" 
  enabled="true">
  <eventMappings>
    <add name="SampleWebRequestEvent" 
      type="Samples.AspNet.Management.SampleWebRequestEvent" 
    />
  </eventMappings>
  <profiles>
    <add name="Custom" 
      minInstances="1" 
      maxLimit="Infinite" 
      minInterval="00:00:00" 
    />
  </profiles>
  <rules>
    <clear />
      <add name="Custom Web Request Event" 
        eventName="SampleWebRequestEvent"
        provider="EventLogProvider" 
        profile="Custom" 
     />
  </rules>
</healthMonitoring>

    The type attribute can list just the class name as it does in the preceding code example, or it can list a fully qualified type, as in the following example:

    type="Samples.AspNet.Management.SampleWebRequestEvent,
Sample.SampleModule,Version=1.0.0.0,Culture=neutral, 
PublicKeyToken=xxxxxxxxxxxx"

    Note

    The fully qualified type is required only if the class has been installed in the GAC or in the Bin directory.

To test the custom Web event

  1. Run the Windows Event Viewer on the server where your Web application runs. To do this, click Start, click Run, type eventvwr in the Run dialog box, and then click OK.

  2. In the event log tree of the Event Viewer, click Application.

  3. Refresh the view of the Application log by clicking Action and then clicking Refresh.

    Make note of the date, time, and name of the most recent event. You will use this later to verify that your custom event has been raised.

  4. In your browser, request any page from the Web application.

    To make use of the custom event in your application, you run a page from the application in the browser. You can then examine the results created by the custom event.

  5. Refresh the application log again and verify that the health event information issued by the custom event has been logged.

See Also

Tasks

Raising Custom ASP.NET Health Monitoring Events Example

Reference

healthMonitoring Element (ASP.NET Settings Schema)

EventLogWebEventProvider

Concepts

ASP.NET Health Monitoring Overview

Other Resources

Extending ASP.NET Processing with HTTP Modules