Web Event Providers

Microsoft ASP.NET 2.0 Providers: Introduction
Membership Providers
Role Providers
Site Map Providers
Session State Providers
Profile Providers
Web Event Providers
Web Parts Personalization Providers

Introduction

Web event providers provide the interface between Microsoft ASP.NET's health monitoring subsystem and data sources for the events ("Web events") fired by that subsystem. ASP.NET 2.0 ships with the following Web event providers:

• EventLogWebEventProvider, which logs Web events in the Windows event log.
• SqlWebEventProvider, which log Web events in Microsoft SQL Server and Microsoft SQL Server Express databases.
• SimpleMailWebEventProvider and TemplatedMailWebEventProvider, which respond to Web events by sending e-mail.
• TraceWebEventProvider, which forwards Web events to diagnostics trace.
• WmiWebEventProvider, which forwards Web events to the Microsoft Windows Management Instrumentation (WMI) subsystem.

The Microsoft .NET Framework's System.Web.Management namespace includes a class named WebEventProvider that defines the basic characteristics of a Web event provider. It also contains a WebEventProvider-derivative named BufferedWebEventProvider that adds buffering support. SqlWebEventProvider derives from BufferedWebEventProvider and improves performance by "batching" Web events and committing them to the database en masse. BufferedWebEventProvider is prototyped as follows:

public abstract class BufferedWebEventProvider : WebEventProvider
{
    // Properties
    public bool UseBuffering { get; }
    public string BufferMode { get; }

    // Virtual methods
    public override void Initialize (string name,
        NameValueCollection config);
    public override void ProcessEvent (WebBaseEvent raisedEvent);
    public override void Flush ();

    // Abstract methods
    public abstract void ProcessEventFlush (WebEventBufferFlushInfo
        flushInfo);
}

The following section documents the implementation of SqlWebEventProvider.

SqlWebEventProvider

SqlWebEventProvider is the Microsoft Web event provider for SQL Server databases. It logs Web events in the provider database, using the schema documented in "Data Schema," and it uses the stored procedure documented in "Data Access." Knowledge of the database schema is hidden in the stored procedure, so that porting SqlWebEventProvider to other database types requires little more than modifying the stored procedure. (Depending on the targeted database type, the ADO.NET code used to call the stored procedure might have to change, too. The Microsoft Oracle .NET provider, for example, uses a different syntax for named parameters.)

The ultimate reference for SqlWebEventProvider is the SqlWebEventProvider source code, which is found in SqlWebEventProvider.cs. The sections that follow highlight key aspects of SqlWebEventProvider's design and operation.

Provider Initialization

Initialization occurs in SqlWebEventProvider.Initialize, which is called one time—when the provider is loaded—by ASP.NET. SqlWebEventProvider.Initialize processes the connectionStringName and maxDetailsEventLength configuration attributes. Then, it calls base.Initialize to process other supported configuration attributes such, as useBuffering, and throw an exception if unrecognized configuration attributes remain.

SqlWebEventProvider.Initialize reads the connection string identified by the connectionStringName attribute from the <connectionStrings> configuration section, and caches it in a private field. It throws a ConfigurationErrorsException if the attribute is empty or nonexistent, if the attribute references a nonexistent connection string, or if the connection string doesn't use integrated security.

Data Schema

SqlWebEventProvider logs Web events in the aspnet_WebEvents_Events table of the provider database. Each record in aspnet_ WebEvents_Events corresponds to one Web event. Table 7-1 documents the aspnet_ WebEvents_Events table's schema.

Table 7-1. The aspnet_WebEvent_Events table

aspnet_WebEvents_Events is a stand-alone table that has no relationships with other tables in the provider database. Many of its fields are filled with values obtained from WebBaseEvent properties of the same name. ApplicationPath, ApplicationVirtualPath, and MachineName contain values obtained from the Web event's ApplicationInformation property. For details of how values are generated for all aspnet_WebEvents_Events fields, see the SqlWebEventProvider.FillParams method in SqlWebEventProvider.cs.

Data Access

SqlWebEventProvider performs all database accesses through the stored procedure named aspnet_WebEvent_LogEvent (Table 7-2). That stored procedure is a simple one consisting of a single INSERT statement that initializes the fields of the new record with the input parameters generated by SqlWebEventProvider.FillParams.

Table 7-2. Stored procedure used by SqlWebEventProvider

Processing Web Events

When a Web event is raised, the Web events subsystem calls the ProcessEvent method of each Web event provider mapped to that event type. If buffering is not enabled, SqlWebEventProvider.ProcessEvent records the Web event in the provider database, by calling the helper method WriteToSQL. If buffering is enabled, SqlWebEventProvider.ProcessEvent buffers the Web event by calling the base class's ProcessEvent method. The following is the source code for SqlWebEventProvider.ProcessEvent, with diagnostic code removed for clarity:

public override void ProcessEvent(WebBaseEvent eventRaised)
{
    if (UseBuffering) {
        base.ProcessEvent(eventRaised);
    }
    else {
        WriteToSQL(new WebBaseEventCollection(eventRaised),
            0, new DateTime(0));
    }
}

If buffering is enabled, the Web events subsystem calls the provider's ProcessEventFlush method to flush buffered Web events. ProcessEventFlush's job is to read buffered Web events from the event buffer, and commit them to the database. SqlWebEventProvider.ProcessEventFlush calls WriteToSQL to log the buffered events. as follows:

public override void ProcessEventFlush
    (WebEventBufferFlushInfo flushInfo)
{
    WriteToSQL(flushInfo.Events,
        flushInfo.EventsDiscardedSinceLastNotification,
        flushInfo.LastNotificationUtc);
}

SqlWebEventProvider.WriteToSQL contains the logic for recording Web events in the provider database. WriteToSQL calls FillParams to generate the parameters written to the database, and then calls the stored procedure aspnet_WebEvent_LogEvent to write the parameters to the provider database. WriteToSql is capable of writing one Web event or multiple Web events, and it contains built-in logic for delaying retries for at least 30 seconds (or the number of seconds specified by the commandTimeout configuration attribute) after a failed attempt to write to the database.

Differences Between the Published Source Code and the .NET Framework's SqlWebEventProvider

The published source code for SqlWebEventProvider differs from the .NET Framework version in the following respects:

• Declarative and imperative CAS checks were commented out. Because the source code can be compiled standalone, and thus will run as user code rather than trusted code in the global assembly cache, the CAS checks are not necessary.
• The published version includes a derived event type called MyWebBaseEvent that is used for manipulating events in the provider. The .NET Framework provider uses the base WebBaseEvent class directly, because the .NET Framework provider is able to call internal WebBaseEvent methods.

Return to part 6,Profile Providers.

Go on to part 8, Web Parts Personalization Providers.

© Microsoft Corporation. All rights reserved.