Table of Contents

Class Browser

Namespace
PuppeteerSharp
Assembly
PuppeteerSharp.dll

Supports all classes in the .NET class hierarchy and provides low-level services to derived classes. This is the ultimate base class of all .NET classes; it is the root of the type hierarchy.

public abstract class Browser : IBrowser, IDisposable, IAsyncDisposable
Inheritance
Browser
Implements
Derived

Properties

AcceptInsecureCerts

Gets or Sets whether to ignore HTTPS errors during navigation.

public bool AcceptInsecureCerts { get; set; }

Property Value

bool

BrowserType

Returns the browser type. Chrome, Chromium or Firefox.

public SupportedBrowser BrowserType { get; protected init; }

Property Value

SupportedBrowser

DefaultContext

Returns the default browser context. The default browser context can not be closed.

public IBrowserContext DefaultContext { get; protected set; }

Property Value

IBrowserContext

The default context.

DefaultWaitForTimeout

Default wait time in milliseconds. Defaults to 30 seconds.

public int DefaultWaitForTimeout { get; set; }

Property Value

int

IsClosed

Gets a value indicating if the browser is closed.

public abstract bool IsClosed { get; }

Property Value

bool

IsConnected

Indicates that the browser is connected.

public bool IsConnected { get; }

Property Value

bool

Process

Gets the spawned browser process. Returns null if the browser instance was created with ConnectAsync(ConnectOptions, ILoggerFactory) method.

public Process Process { get; }

Property Value

Process

Target

A target associated with the browser.

public ITarget Target { get; }

Property Value

ITarget

WebSocketEndpoint

Gets the Browser websocket url.

public string WebSocketEndpoint { get; }

Property Value

string

Remarks

Browser websocket endpoint which can be used as an argument to ConnectAsync(ConnectOptions, ILoggerFactory). The format is ws://\({host}:\){port}/devtools/browser/[id] You can find the webSocketDebuggerUrl from http://\({host}:\){port}/json/version. Learn more about the devtools protocol https://chromedevtools.github.io/devtools-protocol and the browser endpoint https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target.

Methods

BrowserContexts()

Returns an array of all open IBrowserContext. In a newly created browser, this will return a single instance of IBrowserContext.

public abstract IBrowserContext[] BrowserContexts()

Returns

IBrowserContext[]

An array of IBrowserContext objects.

ClearCustomQueryHandlers()

Clears all registered handlers.

public void ClearCustomQueryHandlers()

CloseAsync()

Closes Chromium and all of its pages (if any were opened). The browser object itself is considered disposed and cannot be used anymore.

public abstract Task CloseAsync()

Returns

Task

Task.

CreateBrowserContextAsync(BrowserContextOptions)

Creates a new browser context. This won't share cookies/cache with other browser contexts.

public abstract Task<IBrowserContext> CreateBrowserContextAsync(BrowserContextOptions options = null)

Parameters

options BrowserContextOptions

Options.

Returns

Task<IBrowserContext>

Task which resolves to a new IBrowserContext object.

Examples

using(var browser = await Puppeteer.LaunchAsync(new LaunchOptions()))
{
    // Create a new browser context.
    var context = await browser.CreateBrowserContextAsync();
    // Create a new page in a pristine context.
    var page = await context.NewPageAsync();
    // Do stuff
    await page.GoToAsync("https://example.com");
}

Disconnect()

Disconnects Puppeteer from the browser, but leaves the process running. After calling Disconnect(), the browser object is considered disposed and cannot be used anymore.

public abstract void Disconnect()

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Dispose(bool)

Closes Connection and any Chromium Process that was created by Puppeteer.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

Indicates whether disposal was initiated by Dispose() operation.

DisposeAsync()

Closes Connection and any Chromium Process that was created by Puppeteer.

public ValueTask DisposeAsync()

Returns

ValueTask

ValueTask.

GetUserAgentAsync()

Gets the browser's original user agent.

public abstract Task<string> GetUserAgentAsync()

Returns

Task<string>

Task which resolves to the browser's original user agent.

Remarks

Pages can override browser user agent with SetUserAgentAsync(string, UserAgentMetadata).

GetVersionAsync()

Gets the browser's version.

public abstract Task<string> GetVersionAsync()

Returns

Task<string>

For headless Chromium, this is similar to HeadlessChrome/61.0.3153.0. For non-headless, this is similar to Chrome/61.0.3153.0.

Remarks

the format of GetVersionAsync() might change with future releases of Chromium.

NewPageAsync()

Creates a new page.

public abstract Task<IPage> NewPageAsync()

Returns

Task<IPage>

Task which resolves to a new IPage object.

OnClosed()

Emits Closed event.

protected void OnClosed()

OnDisconnected()

Emits Disconnected event.

protected void OnDisconnected()

OnTargetChanged(TargetChangedArgs)

Emits TargetChanged event.

protected void OnTargetChanged(TargetChangedArgs e)

Parameters

e TargetChangedArgs

The event arguments.

OnTargetCreated(TargetChangedArgs)

Emits TargetCreated event.

protected void OnTargetCreated(TargetChangedArgs e)

Parameters

e TargetChangedArgs

The event arguments.

OnTargetDestroyed(TargetChangedArgs)

Emits TargetDestroyed event.

protected void OnTargetDestroyed(TargetChangedArgs e)

Parameters

e TargetChangedArgs

The event arguments.

OnTargetDiscovered(TargetChangedArgs)

Emits TargetDiscovered event.

protected void OnTargetDiscovered(TargetChangedArgs e)

Parameters

e TargetChangedArgs

The event arguments.

PagesAsync()

Returns a Task which resolves to an array of all open pages. Non visible pages, such as "background_page", will not be listed here. You can find them using PageAsync().

public Task<IPage[]> PagesAsync()

Returns

Task<IPage[]>

Task which resolves to an array of all open pages inside the Browser. In case of multiple browser contexts, the method will return an array with all the pages in all browser contexts.

RegisterCustomQueryHandler(string, CustomQueryHandler)

Registers a custom query handler. After registration, the handler can be used everywhere where a selector is expected by prepending the selection string with name/. The name is only allowed to consist of lower- and upper case latin letters.

public void RegisterCustomQueryHandler(string name, CustomQueryHandler queryHandler)

Parameters

name string

The name that the custom query handler will be registered under.

queryHandler CustomQueryHandler

The query handler to register.

Examples

Puppeteer.RegisterCustomQueryHandler("text", "{ … }"); var aHandle = await page.QuerySelectorAsync("text/…").

Targets()

Returns An Array of all active targets.

public abstract ITarget[] Targets()

Returns

ITarget[]

An Array of all active targets.

UnregisterCustomQueryHandler(string)

Unregister a custom query handler.

public void UnregisterCustomQueryHandler(string name)

Parameters

name string

The name of the query handler to unregistered.

WaitForTargetAsync(Func<ITarget, bool>, WaitForOptions)

This searches for a target in this specific browser context. 

await page.EvaluateAsync("() => window.open('https://www.example.com/')");
var newWindowTarget = await browserContext.WaitForTargetAsync((target) => target.Url == "https://www.example.com/");

public Task<ITarget> WaitForTargetAsync(Func<ITarget, bool> predicate, WaitForOptions options = null)

Parameters

predicate Func<ITarget, bool>

A function to be run for every target.

options WaitForOptions

options.

Returns

Task<ITarget>

Resolves to the first target found that matches the predicate function.

Events

Closed

Raised when the IBrowser gets closed.

public event EventHandler Closed

Event Type

EventHandler

Disconnected

Raised when puppeteer gets disconnected from the Chromium instance. This might happen because one of the following

  • Chromium is closed or crashed
  • Disconnect() method was called
public event EventHandler Disconnected

Event Type

EventHandler

TargetChanged

Raised when the url of a target changes

public event EventHandler<TargetChangedArgs> TargetChanged

Event Type

EventHandler<TargetChangedArgs>

TargetCreated

Raised when a target is created, for example when a new page is opened by window.openhttps://developer.mozilla.org/en-US/docs/Web/API/Window/open or NewPageAsync().

public event EventHandler<TargetChangedArgs> TargetCreated

Event Type

EventHandler<TargetChangedArgs>

TargetDestroyed

Raised when a target is destroyed, for example when a page is closed

public event EventHandler<TargetChangedArgs> TargetDestroyed

Event Type

EventHandler<TargetChangedArgs>

TargetDiscovered

Raised when a target is discovered

public event EventHandler<TargetChangedArgs> TargetDiscovered

Event Type

EventHandler<TargetChangedArgs>
Request doc improvement