Browser

Namespace: PuppeteerSharp

public abstract class Browser : IBrowser, IDisposable, IAsyncDisposable

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.

Inheritance: object

Implements: IBrowser, IDisposable, IAsyncDisposable

Derived: BidiBrowser, CdpBrowser

View source

Properties

BrowserType

public SupportedBrowser BrowserType { get; protected init; }

Returns the browser type. Chrome, Chromium or Firefox.

Value: SupportedBrowser

View source

DebugInfo

public abstract DebugInfo DebugInfo { get; }

Get debug information from Puppeteer.

Value: DebugInfo

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

View source

DefaultContext

public virtual IBrowserContext DefaultContext { get; protected set; }

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

Value: IBrowserContext — The default context.

View source

DefaultWaitForTimeout

public int DefaultWaitForTimeout { get; set; }

Default wait time in milliseconds. Defaults to 30 seconds.

Value: int

View source

IsClosed

public abstract bool IsClosed { get; }

Gets a value indicating if the browser is closed.

Value: bool

View source

IsConnected

public virtual bool IsConnected { get; }

Indicates that the browser is connected.

Value: bool

View source

Process

public Process Process { get; }

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

Value: Process

View source

Target

public virtual ITarget Target { get; }

A target associated with the browser.

Value: ITarget

View source

WebSocketEndpoint

public virtual string WebSocketEndpoint { get; }

Gets the Browser websocket url.

Value: string

Browser websocket endpoint which can be used as an argument to 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 <a href=“https://chromedevtools.github.io/devtools-protocol"&gt;https://chromedevtools.github.io/devtools-protocol&lt;/a> and the browser endpoint <a href=“https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target"&gt;https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target&lt;/a>.

View source

Events

Closed

public event EventHandler Closed

Raised when the IBrowser gets closed.

Value: EventHandler

View source

Disconnected

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

Value: EventHandler

View source

TargetChanged

public event EventHandler<TargetChangedArgs> TargetChanged

Raised when the url of a target changes

Value: EventHandler<TargetChangedArgs>

View source

TargetCreated

public event EventHandler<TargetChangedArgs> TargetCreated

Raised when a target is created, for example when a new page is opened by window.open <a href=“https://developer.mozilla.org/en-US/docs/Web/API/Window/open"&gt;https://developer.mozilla.org/en-US/docs/Web/API/Window/open&lt;/a> or NewPageAsync(CreatePageOptions).

Value: EventHandler<TargetChangedArgs>

View source

TargetDestroyed

public event EventHandler<TargetChangedArgs> TargetDestroyed

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

Value: EventHandler<TargetChangedArgs>

View source

TargetDiscovered

public event EventHandler<TargetChangedArgs> TargetDiscovered

Raised when a target is discovered

Value: EventHandler<TargetChangedArgs>

View source

Methods

AddScreenAsync(AddScreenParams)

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

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

Parameters

Name	Type	Description
params	AddScreenParams	The parameters for the new screen.

Returns: Task<ScreenInfo> — A task that resolves to the added screen information.

Only supported in headless mode.

View source

BrowserContexts()

public abstract IBrowserContext[] BrowserContexts()

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

Returns: IBrowserContext\[\] — An array of IBrowserContext objects.

View source

ClearCustomQueryHandlers()

public void ClearCustomQueryHandlers()

Clears all registered handlers.

View source

CloseAsync()

public abstract Task CloseAsync()

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

Returns: Task — Task.

View source

CreateBrowserContextAsync(BrowserContextOptions)

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

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

Parameters

Name	Type	Description
options	BrowserContextOptions	Options.

Returns: Task<IBrowserContext> — Task which resolves to a new IBrowserContext object.

Example

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

View source

CreateCDPSessionAsync()

public Task<ICDPSession> CreateCDPSessionAsync()

Creates a Chrome Devtools Protocol session attached to the browser.

Returns: Task<ICDPSession> — A task that returns a ICDPSession.

View source

DeleteCookieAsync(params CookieParam[])

public Task DeleteCookieAsync(params CookieParam[] cookies)

Removes cookies from the default browser context.

Parameters

Name	Type	Description
cookies	CookieParam\[\]	Complete CookieParam objects to be removed.

Returns: Task — Task.

View source

DeleteMatchingCookiesAsync(params DeleteCookiesRequest[])

public Task DeleteMatchingCookiesAsync(params DeleteCookiesRequest[] filters)

Deletes cookies matching the provided filters from the default IBrowserContext.

Parameters

Name	Type	Description
filters	DeleteCookiesRequest\[\]	Filters to match cookies against.

Returns: Task — Task.

View source

Disconnect()

public abstract void 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.

View source

Dispose()

public void Dispose()

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

View source

Dispose(bool)

protected virtual void Dispose(bool disposing)

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

Parameters

Name	Type	Description
disposing	bool	Indicates whether disposal was initiated by Dispose() operation.

View source

DisposeAsync()

public ValueTask DisposeAsync()

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

Returns: ValueTask — ValueTask.

View source

ExtensionsAsync()

public abstract Task<IReadOnlyDictionary<string, Extension>> ExtensionsAsync()

Returns a map of installed extensions, keyed by extension ID.

Returns: Task<IReadOnlyDictionary<string, Extension>> — A task that resolves to a dictionary of extension ID to Extension.

View source

GetCookiesAsync()

public Task<CookieParam[]> GetCookiesAsync()

Gets all cookies in the default browser context.

Returns: Task<CookieParam[]> — Task which resolves to an array of CookieParam.

View source

GetPWAStateAsync(GetPWAStateOptions)

public abstract Task<PWAState> GetPWAStateAsync(GetPWAStateOptions options)

Returns the OS-integration state of an installed Progressive Web App (PWA), such as its badge count and registered file handlers.

Parameters

Name	Type	Description
options	GetPWAStateOptions	Options for querying the PWA state.

Returns: Task<PWAState> — A task that resolves to the PWA state.

Only available over a pipe connection. See InstallPWAAsync(InstallPWAOptions). Meaningful only for an app that is currently installed; querying an unknown manifest id rejects.

View source

GetUserAgentAsync()

public abstract Task<string> GetUserAgentAsync()

Gets the browser’s original user agent.

Returns: Task<string> — Task which resolves to the browser’s original user agent.

Pages can override browser user agent with UserAgentMetadata).

View source

GetVersionAsync()

public abstract Task<string> GetVersionAsync()

Gets the browser’s version.

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.

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

View source

GetWindowBoundsAsync(string)

public abstract Task<WindowBounds> GetWindowBoundsAsync(string windowId)

Gets the specified window bounds.

Parameters

Name	Type	Description
windowId	string	The window ID.

Returns: Task<WindowBounds> — A task that resolves to the WindowBounds.

View source

InstallExtensionAsync(string, ExtensionInstallOptions)

public abstract Task<string> InstallExtensionAsync(string path, ExtensionInstallOptions options = null)

Installs an unpacked extension and returns the extension ID.

Parameters

Name	Type	Description
path	string	The path to the unpacked extension directory.
options	ExtensionInstallOptions	Options for installing the extension.

Returns: Task<string> — A task that resolves to the extension ID.

View source

InstallPWAAsync(InstallPWAOptions)

public abstract Task<string> InstallPWAAsync(InstallPWAOptions options)

Installs a Progressive Web App (PWA) and returns its manifest id.

Parameters

Name	Type	Description
options	InstallPWAOptions	Options for installing the PWA.

Returns: Task<string> — A task that resolves to the manifest id.

Only available when connected to the browser over a pipe connection. Set Pipe to true; it defaults to false. The underlying PWA CDP domain is not exposed over a WebSocket connection. The returned manifest id echoes ManifestId, so it can be passed directly to LaunchPWAAsync(LaunchPWAOptions), GetPWAStateAsync(GetPWAStateOptions), or UninstallPWAAsync(UninstallPWAOptions).

View source

LaunchPWAAsync(LaunchPWAOptions)

public abstract Task<IPage> LaunchPWAAsync(LaunchPWAOptions options)

Launches an installed Progressive Web App (PWA) and resolves with the IPage backing the app window.

Parameters

Name	Type	Description
options	LaunchPWAOptions	Options for launching the PWA.

Returns: Task<IPage> — A task that resolves to the page backing the app window.

Only available over a pipe connection. See InstallPWAAsync(InstallPWAOptions). PWA.launch resolves with the id of the launched tab target. Puppeteer does not expose tab targets through Targets(); this method instead resolves with the tab’s child page target (the app’s web contents). If Chromium focuses an existing app window, this returns that window’s existing page.

View source

NewPageAsync(CreatePageOptions)

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

Creates a new page.

Parameters

Name	Type	Description
options	CreatePageOptions	Options for creating the page.

Returns: Task<IPage> — Task which resolves to a new IPage object.

View source

OnClosed()

protected void OnClosed()

Emits Closed event.

View source

OnDisconnected()

protected void OnDisconnected()

Emits Disconnected event.

View source

OnTargetChanged(TargetChangedArgs)

protected void OnTargetChanged(TargetChangedArgs e)

Emits TargetChanged event.

Parameters

Name	Type	Description
e	TargetChangedArgs	The event arguments.

View source

OnTargetCreated(TargetChangedArgs)

protected void OnTargetCreated(TargetChangedArgs e)

Emits TargetCreated event.

Parameters

Name	Type	Description
e	TargetChangedArgs	The event arguments.

View source

OnTargetDestroyed(TargetChangedArgs)

protected void OnTargetDestroyed(TargetChangedArgs e)

Emits TargetDestroyed event.

Parameters

Name	Type	Description
e	TargetChangedArgs	The event arguments.

View source

OnTargetDiscovered(TargetChangedArgs)

protected void OnTargetDiscovered(TargetChangedArgs e)

Emits TargetDiscovered event.

Parameters

Name	Type	Description
e	TargetChangedArgs	The event arguments.

View source

PagesAsync(bool)

public Task<IPage[]> PagesAsync(bool includeAll = false)

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

Parameters

Name	Type	Description
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.

View source

RegisterCustomQueryHandler(string, CustomQueryHandler)

public void RegisterCustomQueryHandler(string name, CustomQueryHandler queryHandler)

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.

Parameters

Name	Type	Description
name	string	The name that the custom query handler will be registered under.
queryHandler	CustomQueryHandler	The query handler to register.

Example

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

View source

RemoveScreenAsync(string)

public abstract Task RemoveScreenAsync(string screenId)

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

Parameters

Name	Type	Description
screenId	string	The ID of the screen to remove.

Returns: Task — A task that completes when the screen is removed.

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

View source

RestrictNetworkAsync(NetworkRestrictions)

public virtual Task RestrictNetworkAsync(NetworkRestrictions restrictions = null)

Sets the network restrictions (blocklist or allowlist) and re-applies them to all targets. To clear all restrictions, call it without arguments or pass null.

Parameters

Name	Type	Description
restrictions	NetworkRestrictions	The network restrictions to apply.

Returns: Task — A task that resolves when the restrictions were applied.

Only supported for Chrome and the CDP protocol. Targets that are already on a blocked URL when this method is called stay attached and stay on the blocked page. This differs from launching the browser with network restrictions, where such targets are detached on the initial attach.

View source

ScreensAsync()

public abstract Task<ScreenInfo[]> ScreensAsync()

Gets a list of ScreenInfo objects.

Returns: Task<ScreenInfo[]> — A task that resolves to an array of screen information objects.

View source

SetCookieAsync(params CookieData[])

public Task SetCookieAsync(params CookieData[] cookies)

Sets cookies in the default browser context.

Parameters

Name	Type	Description
cookies	CookieData\[\]	Cookies to set.

Returns: Task — Task.

View source

SetPermissionAsync(string, params PermissionEntry[])

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

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

Parameters

Name	Type	Description
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.

View source

SetWindowBoundsAsync(string, WindowBounds)

public abstract Task SetWindowBoundsAsync(string windowId, WindowBounds windowBounds)

Sets the specified window bounds.

Parameters

Name	Type	Description
windowId	string	The window ID.
windowBounds	WindowBounds	The bounds to set.

Returns: Task — A task that resolves when the bounds have been set.

View source

Targets()

public abstract ITarget[] Targets()

Returns An Array of all active targets.

Returns: ITarget\[\] — An Array of all active targets.

View source

UninstallExtensionAsync(string)

public abstract Task UninstallExtensionAsync(string id)

Uninstalls a previously installed extension by its ID.

Parameters

Name	Type	Description
id	string	The extension ID to uninstall.

Returns: Task — A task that completes when the extension is uninstalled.

View source

UninstallPWAAsync(UninstallPWAOptions)

public abstract Task UninstallPWAAsync(UninstallPWAOptions options)

Uninstalls a previously installed Progressive Web App (PWA).

Parameters

Name	Type	Description
options	UninstallPWAOptions	Options for uninstalling the PWA.

Returns: Task — A task that completes when the PWA is uninstalled.

Only available over a pipe connection. See InstallPWAAsync(InstallPWAOptions).

View source

UnregisterCustomQueryHandler(string)

public void UnregisterCustomQueryHandler(string name)

Unregister a custom query handler.

Parameters

Name	Type	Description
name	string	The name of the query handler to unregistered.

View source

WaitForTargetAsync(Func<ITarget, bool>, WaitForOptions)

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

This searches for a target in this specific browser context.

<example>

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

</example>

Parameters

Name	Type	Description
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.

View source