CdpFrame

Namespace: PuppeteerSharp.Cdp

public class CdpFrame : Frame, IFrame

Provides methods to interact with a single page frame in Chromium. One IPage instance might have multiple IFrame instances. At every point of time, page exposes its current frame tree via the MainFrame and ChildFrames properties.

IFrame object’s lifecycle is controlled by three events, dispatched on the page object

• FrameAttached - fires when the frame gets attached to the page. A Frame can be attached to the page only once
• FrameNavigated - fired when the frame commits navigation to a different URL
• FrameDetached - fired when the frame gets detached from the page. A Frame can be detached from the page only once.

Inheritance: object → Frame

Implements: IFrame

Example

An example of dumping frame tree.

var browser = await Puppeteer.LaunchAsync(new LaunchOptions());
var page = await browser.NewPageAsync();
await page.GoToAsync("https://www.google.com/chrome/browser/canary.html");
dumpFrameTree(page.MainFrame, string.Empty);
await browser.CloseAsync();

void dumpFrameTree(IFrame frame, string indent)
{
    Console.WriteLine(indent + frame.Url);
    foreach (var child in frame.ChildFrames)
    {
        dumpFrameTree(child, indent + "  ");
    }
}

View source

Properties

ChildFrames

public override IReadOnlyCollection<IFrame> ChildFrames { get; }

Gets the child frames of the this frame.

Value: IReadOnlyCollection<IFrame>

View source

Client

public override sealed ICDPSession Client { get; protected set; }

Gets the CDPSession associated with this environment.

Value: ICDPSession

View source

Page

public override IPage Page { get; }

The IPage associated with the frame.

Value: IPage

View source

Methods

AddStyleTagAsync(AddTagOptions)

public override Task<IElementHandle> AddStyleTagAsync(AddTagOptions options)

Adds a <link rel="stylesheet"> tag into the page with the desired url or a <link rel="stylesheet"> tag with the content.

Parameters

Name	Type	Description
options	AddTagOptions	add style tag options.

Returns: Task<IElementHandle> — Task which resolves to the added tag when the stylesheet’s onload fires or when the CSS content was injected into frame.

View source

ExtensionRealms()

public override IReadOnlyList<Realm> ExtensionRealms()

Retrieves the list of extension realms within this frame.

Returns: IReadOnlyList<Realm> — A list of Realm instances representing extension execution contexts.

View source

FrameElementAsync()

public override Task<ElementHandle> FrameElementAsync()

The frame element associated with this frame (if any).

Returns: Task<ElementHandle> — Task which resolves to the frame element.

View source

GetDeviceRequestPromptManager()

protected override DeviceRequestPromptManager GetDeviceRequestPromptManager()

Gets the prompts manager for the current client.

Returns: DeviceRequestPromptManager — The DeviceRequestPromptManager.

View source

GoToAsync(string, NavigationOptions)

public override Task<IResponse> GoToAsync(string url, NavigationOptions options)

Navigates to an url.

Parameters

Name	Type	Description
url	string	URL to navigate page to. The url should include scheme, e.g. https://.
options	NavigationOptions	Navigation parameters.

Returns: Task<IResponse> — Task which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.

WaitUntilNavigation%5b%5d) will throw an error if:

• there’s an SSL error (e.g. in case of self-signed certificates).
• target URL is invalid.
• the timeout is exceeded during navigation.
• the remote server does not respond or is unreachable.
• the main resource failed to load.
• the URL is blocked by blocklist/allowlist rules.

WaitUntilNavigation%5b%5d) will not throw an error when any valid HTTP status code is returned by the remote server, including 404 “Not Found” and 500 “Internal Server Error”. The status code for such responses can be retrieved by calling Status

> NOTE WaitUntilNavigation%5b%5d) either throws an error or returns a main resource response. The only exceptions are navigation to about:blank or navigation to the same URL with a different hash, which would succeed and return null.

> NOTE Headless mode doesn’t support navigation to a PDF document. See the <see fref=“https://bugs.chromium.org/p/chromium/issues/detail?id=761295"&gt;upstream issue</see>.

View source

OnDetach()

protected override void OnDetach()

Called when this frame is being detached. Subclasses can override to perform additional cleanup.

View source

SetContentAsync(string, NavigationOptions)

[Obsolete]
public override Task SetContentAsync(string html, NavigationOptions options)

Sets the HTML markup to the page.

Parameters

Name	Type	Description
html	string	HTML markup to assign to the page.
options	NavigationOptions	The options.

Returns: Task — Task.

Obsolete

This API is obsolete.

View source

WaitForNavigationAsync(NavigationOptions)

public override Task<IResponse> WaitForNavigationAsync(NavigationOptions options = null)

This resolves when the frame navigates to a new URL or reloads. It is useful for when you run code which will indirectly cause the frame to navigate.

Parameters

Name	Type	Description
options	NavigationOptions	navigation options.

Returns: Task<IResponse> — Task which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with null.

Usage of the History API <a href=“https://developer.mozilla.org/en-US/docs/Web/API/History_API"&gt;https://developer.mozilla.org/en-US/docs/Web/API/History_API&lt;/a> to change the URL is considered a navigation.

Example

var navigationTask = Page.WaitForNavigationAsync();
await Page.MainFrame.ClickAsync("a.my-link");
await navigationTask;

View source