Concepts

Core Concepts

Core Concepts

The Event System

GPAL never writes files or logs anything on its own. Instead it publishes structured events to two channels. Information and Exception. That you subscribe to and handle however you choose.

Events, Not Files

GPAL's philosophy is to publish, not persist. Every significant operation -- element found, not found, action taken, exception raised -- fires an event on either the Information channel or the Exception channel. What you do with those events is entirely up to you: write to a file, insert to a database, display in a UI, send an email, or ignore them entirely. GPAL imposes nothing.

Subscribing and Publishing

Subscribe by attaching handlers to GPAL.InformationHandler and GPAL.ExceptionHandler. You can also publish your own events into the same channels using GPAL.PublishSimpleEvent. GPAL automatically captures the calling method name and a screenshot, so your events arrive with the same rich context as GPAL's own.

// Subscribe to the information channel

GPAL.InformationHandler += (sender, e) => {

Console.WriteLine($"[{e.GPALEventType}] {e.Message}");

};

// Subscribe to the exception channel

GPAL.ExceptionHandler += (sender, e) => {

// e.ScreenShot shows browser state at the moment of the exception

e.ScreenShot?.Save("exception-context.png");

File.AppendAllText("errors.log",

$"{e.DateTimeStamp}: {e.Message}

{e.ExceptionRaised}

");

};

// Publish your own event into the same channels

GPAL.PublishSimpleEvent(

GPALEventType.INFO,

"Login step completed",

browser,

GPALObjectType.Browser

);

TIP

GPAL.WithPublishToConsole() and GPAL.WithPublishToDebug() subscribe built-in handlers for quick output during development. WithPublishToDatabase routes all events to a SQL table. Use these for rapid setup; replace with custom handlers for production.

What Every Event Carries

GPALEventArgs contains: GPALEventType (INFO/WARNING/ERROR/EXCEPTION/DEBUG), Message, DateTimeStamp, the current UOW and Selector, GPALObject (the Browser or Application that raised the event), matched element list, a Screenshot of the browser at the moment of the event, ExceptionRaised (on EXCEPTION events), and Tokens/TokenList for data-bearing events. The screenshot is included by default because its utility on exception events. Seeing exactly what the browser showed when something failed. Is high enough to justify the overhead.

WARNING

If you do not subscribe to the event channels, all events are silently discarded. GPAL will never create log files, write to disk, or output to console on its own. Subscribe to the channels you need before starting any workflow.

On this page

Core Concepts
The Event System
  • Events, Not Files
  • Subscribing and Publishing
  • What Every Event Carries