Interface IBrowser

Namespace

PuppeteerSharp

Assembly

PuppeteerSharp.dll

Provides methods to interact with a browser.

public interface IBrowser : IDisposable, IAsyncDisposable

Examples

An example of using a IBrowser to create a IPage:

var browser = await Puppeteer.LaunchAsync(new LaunchOptions());
var page = await browser.NewPageAsync();
await page.GoToAsync("https://example.com");
await browser.CloseAsync();

An example of disconnecting from and reconnecting to a Browser:

var browser = await Puppeteer.LaunchAsync(new LaunchOptions());
var browserWSEndpoint = browser.WebSocketEndpoint;
browser.Disconnect();
var browser2 = await Puppeteer.ConnectAsync(new ConnectOptions { BrowserWSEndpoint = browserWSEndpoint });
await browser2.CloseAsync();

Properties

AcceptInsecureCerts

Gets or Sets whether to ignore HTTPS errors during navigation.

bool AcceptInsecureCerts { get; set; }

Property Value

bool

BrowserType

Returns the browser type. Chrome, Chromium or Firefox.

SupportedBrowser BrowserType { get; }

Property Value

SupportedBrowser

DefaultContext

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

IBrowserContext DefaultContext { get; }

Property Value

IBrowserContext

The default context.

DefaultWaitForTimeout

Default wait time in milliseconds. Defaults to 30 seconds.

int DefaultWaitForTimeout { get; set; }

Property Value

int

IsClosed

Gets a value indicating if the browser is closed.

bool IsClosed { get; }

Property Value

bool

IsConnected

Indicates that the browser is connected.

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.

Process Process { get; }

Property Value

Process

Target

A target associated with the browser.

ITarget Target { get; }

Property Value

ITarget

WebSocketEndpoint

Gets the Browser websocket url.

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.

IBrowserContext[] BrowserContexts()

Returns

IBrowserContext[]

An array of IBrowserContext objects.

ClearCustomQueryHandlers()

Clears all registered handlers.

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.

Task CloseAsync()

Returns

Task

Task.

CreateBrowserContextAsync(BrowserContextOptions)

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

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.

void Disconnect()

GetUserAgentAsync()

Gets the browser's original user agent.

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.

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.

Task<IPage> NewPageAsync()

Returns

Task<IPage>

Task which resolves to a new IPage object.

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().

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.

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.

ITarget[] Targets()

Returns

ITarget[]

An Array of all active targets.

UnregisterCustomQueryHandler(string)

Unregister a custom query handler.

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/");

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.

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

event EventHandler Disconnected

Event Type

EventHandler

TargetChanged

Raised when the url of a target changes

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.open https://developer.mozilla.org/en-US/docs/Web/API/Window/open or NewPageAsync().

event EventHandler<TargetChangedArgs> TargetCreated

Event Type

EventHandler<TargetChangedArgs>

TargetDestroyed

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

event EventHandler<TargetChangedArgs> TargetDestroyed

Event Type

EventHandler<TargetChangedArgs>

TargetDiscovered

Raised when a target is discovered

event EventHandler<TargetChangedArgs> TargetDiscovered

Event Type

EventHandler<TargetChangedArgs>