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

object

Browser

Implements

IBrowser

IDisposable

IAsyncDisposable

Derived

BidiBrowser

CdpBrowser

Properties

BrowserType

Returns the browser type. Chrome, Chromium or Firefox.

public SupportedBrowser BrowserType { get; protected init; }

Property Value

SupportedBrowser

DebugInfo

Get debug information from Puppeteer.

public abstract DebugInfo DebugInfo { get; }

Property Value

DebugInfo

Remarks

Currently, includes pending protocol calls. In the future, more info might be added.

DefaultContext

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

public virtual 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 virtual 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 virtual ITarget Target { get; }

Property Value

ITarget

WebSocketEndpoint

Gets the Browser websocket url.

public virtual 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

AddScreenAsync(AddScreenParams)

Adds a new screen with specified parameters and returns a ScreenInfo object, including the new screen's ID.

public abstract Task<ScreenInfo> AddScreenAsync(AddScreenParams @params)

Parameters

params AddScreenParams

The parameters for the new screen.

Returns

Task<ScreenInfo>

A task that resolves to the added screen information.

Remarks

Only supported in headless mode.

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

CreateCDPSessionAsync()

Creates a Chrome Devtools Protocol session attached to the browser.

public Task<ICDPSession> CreateCDPSessionAsync()

Returns

Task<ICDPSession>

A task that returns a ICDPSession.

DeleteCookieAsync(params CookieParam[])

Removes cookies from the default browser context.

public Task DeleteCookieAsync(params CookieParam[] cookies)

Parameters

cookies CookieParam[]

Complete CookieParam objects to be removed.

Returns

Task

Task.

DeleteMatchingCookiesAsync(params DeleteCookiesRequest[])

Deletes cookies matching the provided filters from the default IBrowserContext.

public Task DeleteMatchingCookiesAsync(params DeleteCookiesRequest[] filters)

Parameters

filters DeleteCookiesRequest[]

Filters to match cookies against.

Returns

Task

Task.

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.

GetCookiesAsync()

Gets all cookies in the default browser context.

public Task<CookieParam[]> GetCookiesAsync()

Returns

Task<CookieParam[]>

Task which resolves to an array of CookieParam.

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.

GetWindowBoundsAsync(string)

Gets the specified window bounds.

public abstract Task<WindowBounds> GetWindowBoundsAsync(string windowId)

Parameters

windowId string

The window ID.

Returns

Task<WindowBounds>

A task that resolves to the WindowBounds.

InstallExtensionAsync(string)

Installs an unpacked extension and returns the extension ID. In Chrome, this is only available if the browser was created using pipe mode and the --enable-unsafe-extension-debugging flag is set.

public abstract Task<string> InstallExtensionAsync(string path)

Parameters

path string

The path to the unpacked extension directory.

Returns

Task<string>

A task that resolves to the extension ID.

NewPageAsync(CreatePageOptions)

Creates a new page.

public abstract Task<IPage> NewPageAsync(CreatePageOptions options = null)

Parameters

options CreatePageOptions

Options for creating the page.

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

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(bool includeAll = false)

Parameters

includeAll bool

Experimental. When true, includes all kinds of pages.

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/…").

RemoveScreenAsync(string)

Removes the screen associated with the given screen ID, unless it is the primary screen.

public abstract Task RemoveScreenAsync(string screenId)

Parameters

screenId string

The ID of the screen to remove.

Returns

Task

A task that completes when the screen is removed.

Remarks

Only supported in headless mode. Fails if the primary screen ID is specified.

ScreensAsync()

Gets a list of ScreenInfo objects.

public abstract Task<ScreenInfo[]> ScreensAsync()

Returns

Task<ScreenInfo[]>

A task that resolves to an array of screen information objects.

SetCookieAsync(params CookieData[])

Sets cookies in the default browser context.

public Task SetCookieAsync(params CookieData[] cookies)

Parameters

cookies CookieData[]

Cookies to set.

Returns

Task

Task.

SetPermissionAsync(string, params PermissionEntry[])

Sets the permission for a specific origin on the default browser context.

public Task SetPermissionAsync(string origin, params PermissionEntry[] permissions)

Parameters

origin string

The origin to set the permission for, e.g. "https://example.com". Use "*" for all origins (CDP only).

permissions PermissionEntry[]

The permissions to set.

Returns

Task

The task.

SetWindowBoundsAsync(string, WindowBounds)

Sets the specified window bounds.

public abstract Task SetWindowBoundsAsync(string windowId, WindowBounds windowBounds)

Parameters

windowId string

The window ID.

windowBounds WindowBounds

The bounds to set.

Returns

Task

A task that resolves when the bounds have been set.

Targets()

Returns An Array of all active targets.

public abstract ITarget[] Targets()

Returns

ITarget[]

An Array of all active targets.

UninstallExtensionAsync(string)

Uninstalls a previously installed extension by its ID. In Chrome, this is only available if the browser was created using pipe mode and the --enable-unsafe-extension-debugging flag is set.

public abstract Task UninstallExtensionAsync(string id)

Parameters

id string

The extension ID to uninstall.

Returns

Task

A task that completes when the extension is uninstalled.

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

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>