Table of Contents

Class CdpFrame

Namespace
PuppeteerSharp.Cdp
Assembly
PuppeteerSharp.dll

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.
public class CdpFrame : Frame, IFrame
Inheritance
CdpFrame
Implements

Examples

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

Properties

ChildFrames

Gets the child frames of the this frame.

public override IReadOnlyCollection<IFrame> ChildFrames { get; }

Property Value

IReadOnlyCollection<IFrame>

Client

Gets the CDPSession associated with this environment.

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

Property Value

CDPSession

Page

The IPage associated with the frame.

public override IPage Page { get; }

Property Value

IPage

Methods

AddScriptTagAsync(AddTagOptions)

Adds a <script> tag into the page with the desired url or content.

public override Task<IElementHandle> AddScriptTagAsync(AddTagOptions options)

Parameters

options AddTagOptions

add script tag options.

Returns

Task<IElementHandle>

Task which resolves to the added tag when the script's onload fires or when the script content was injected into frame.

See Also

AddStyleTagAsync(AddTagOptions)

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

public override Task<IElementHandle> AddStyleTagAsync(AddTagOptions options)

Parameters

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.

See Also

GetDeviceRequestPromptManager()

Gets the prompts manager for the current client.

protected override DeviceRequestPromptManager GetDeviceRequestPromptManager()

Returns

DeviceRequestPromptManager

The DeviceRequestPromptManager.

GoToAsync(string, NavigationOptions)

Navigates to an url.

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

Parameters

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.

Remarks

GoToAsync(string, int?, WaitUntilNavigation[]) 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.

 <xref href="PuppeteerSharp.IFrame.GoToAsync(System.String%2cSystem.Nullable%7bSystem.Int32%7d%2cPuppeteerSharp.WaitUntilNavigation%5b%5d)" data-throw-if-not-resolved="false"></xref> 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 <xref href="PuppeteerSharp.IResponse.Status" data-throw-if-not-resolved="false"></xref>

 > **NOTE** <xref href="PuppeteerSharp.IFrame.GoToAsync(System.String%2cSystem.Nullable%7bSystem.Int32%7d%2cPuppeteerSharp.WaitUntilNavigation%5b%5d)" data-throw-if-not-resolved="false"></xref> 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">upstream issue</see>.
See Also

SetContentAsync(string, NavigationOptions)

Sets the HTML markup to the page.

public override Task SetContentAsync(string html, NavigationOptions options = null)

Parameters

html string

HTML markup to assign to the page.

options NavigationOptions

The options.

Returns

Task

Task.

See Also

WaitForNavigationAsync(NavigationOptions)

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.

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

Parameters

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.

Examples

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

Remarks

Usage of the History APIhttps://developer.mozilla.org/en-US/docs/Web/API/History_API to change the URL is considered a navigation.

Request doc improvement