Tutorials

Getting Started

Getting Started

Launching Chrome with a Real Browser Profile

Browser Profiles: Signed-In vs Temporary Automation Engines The GPAL Factory The Event System

Complete Program

Here's the whole workflow, start to finish. Each piece is broken down and explained below.

using System;

using System.Diagnostics;

using GenerallyPositive;

using GenerallyPositive.Browser;

using static GenerallyPositive.Enums;


GPAL

.WithExceptionHandler(ExceptionEventHandler)

.WithInformationHandler(InformationEventHandler);


IBrowser browser = GPAL.Browser

.WithBrowserType(BrowserType.Chrome)

.WithProfileName("Person 1")

.WithAutomationEngine(AutomationEngine.PuppeteerPort)

.ToGPALObject();


browser.GoTo("https://www.ebay.com");


browser.Close(true);


void ExceptionEventHandler(object sender, EventArgs e)

{

Debug.WriteLine(((GPAL.GPALEventArgs)e).Message);

Debug.WriteLine(((GPAL.GPALEventArgs)e).ExceptionRaised?.Message);

}


void InformationEventHandler(object sender, EventArgs e)

{

Debug.WriteLine(((GPAL.GPALEventArgs)e).Message);

}

WithProfileName Picks an Existing Chrome Profile

Chrome stores each profile (the ones you switch between in the top-right avatar menu) under a name like "Person 1", "Person 2", and so on. Passing that name to WithProfileName tells GPAL to launch Chrome using that profile's user data - cookies, saved logins, extensions, everything - instead of a clean temporary profile.

IBrowser browser = GPAL.Browser

.WithBrowserType(BrowserType.Chrome)

.WithProfileName("Person 1")

.WithAutomationEngine(AutomationEngine.PuppeteerPort)

.ToGPALObject();

NOTE

Because the launched browser is using a real profile's storage, sites that previously had you signed in will treat the automated session the same way - no login step needed. This is the difference between this tutorial and a normal GPAL.Browser call, which starts from a fresh, unauthenticated profile. See Browser Profiles: Signed-In vs Temporary.

GoTo vs Get

Once the browser exists, navigation works exactly the same as any other GPAL workflow - GoTo opens a visible window and navigates to the URL, while Get does the same thing for a headless run.

browser.GoTo("https://www.ebay.com");


// or, for a headless run:

// browser.Get("https://www.ebay.com");

Wire Up Exception and Information Handlers

Before doing anything else, the program registers handlers for GPAL's exception and information events. These fire throughout the run and are the easiest way to see what GPAL is doing (or where it's failing) without instrumenting every call yourself.

GPAL

.WithExceptionHandler(ExceptionEventHandler)

.WithInformationHandler(InformationEventHandler);


void ExceptionEventHandler(object sender, EventArgs e)

{

Debug.WriteLine(((GPAL.GPALEventArgs)e).Message);

Debug.WriteLine(((GPAL.GPALEventArgs)e).ExceptionRaised?.Message);

}


void InformationEventHandler(object sender, EventArgs e)

{

Debug.WriteLine(((GPAL.GPALEventArgs)e).Message);

}

Close When You're Done

Close(true) shuts down the browser and kills the underlying driver process for this run.

browser.Close(true);

WARNING

A profile can be open in only one browser. Before launching, GPAL checks whether another browser process holds the named profile. If one does, GPAL waits up to 15 seconds for it to be let go (a browser that just closed can hold it briefly), then publishes an ERROR and throws a GPALException: Profile [..] is already open in [chrome.exe] process [..]. Close any open Chrome windows using that profile before running a profile-based workflow, or give the run a profile of its own.

Behind the Scenes: Every Engine, Every Mode

The actual test program in the repo wraps this workflow in three nested loops, running it for every BrowserType, every AutomationEngine, and both headless and headful modes. That's purely for regression testing - it makes sure profile-based launches work no matter which engine drives the browser. Your own code only needs the single pass shown above. See Automation Engines for the full list of engines and how they differ.

On this page

Getting Started
Launching Chrome with a Real Browser Profile
  • Complete Program
  • WithProfileName Picks an Existing Chrome Profile
  • GoTo vs Get
  • Wire Up Exception and Information Handlers
  • Close When You're Done
  • Behind the Scenes: Every Engine, Every Mode
    • 💬 Ask GPAL