CefSharp.Dom - Async DOM API

[amaitland]

CefSharp.Dom is an asynchronous library for accessing/modifying the DOM.

• Alternative to using JavaScript to access the DOM
• It uses the Chromium DevTools Protocol and originally started out as a port of Puppeteer Sharp.
• The package requires CefSharp 104.4.180 or greater.
• Supports keyboard, mouse and touch emulation for automating websites.

The following examples are an excerpt from the Readme

// Add using CefSharp.Dom to access CreateDevToolsContextAsync and related extension methods.
await using var devToolsContext = await chromiumWebBrowser.CreateDevToolsContextAsync();

// Get element by Id
// https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector
var element = await devToolsContext.QuerySelectorAsync<HtmlElement>("#myElementId");

//Strongly typed element types (this is only a subset of the types mapped)
var htmlDivElement = await devToolsContext.QuerySelectorAsync<HtmlDivElement>("#myDivElementId");
var htmlSpanElement = await devToolsContext.QuerySelectorAsync<HtmlSpanElement>("#mySpanElementId");
var htmlSelectElement = await devToolsContext.QuerySelectorAsync<HtmlSelectElement>("#mySelectElementId");
var htmlInputElement = await devToolsContext.QuerySelectorAsync<HtmlInputElement>("#myInputElementId");
var htmlFormElement = await devToolsContext.QuerySelectorAsync<HtmlFormElement>("#myFormElementId");
var htmlAnchorElement = await devToolsContext.QuerySelectorAsync<HtmlAnchorElement>("#myAnchorElementId");
var htmlImageElement = await devToolsContext.QuerySelectorAsync<HtmlImageElement>("#myImageElementId");
var htmlTextAreaElement = await devToolsContext.QuerySelectorAsync<HtmlImageElement>("#myTextAreaElementId");
var htmlButtonElement = await devToolsContext.QuerySelectorAsync<HtmlButtonElement>("#myButtonElementId");
var htmlParagraphElement = await devToolsContext.QuerySelectorAsync<HtmlParagraphElement>("#myParagraphElementId");
var htmlTableElement = await devToolsContext.QuerySelectorAsync<HtmlTableElement>("#myTableElementId");

// Get a custom attribute value
var customAttribute = await element.GetAttributeAsync<string>("data-customAttribute");

//Set innerText property for the element
await element.SetInnerTextAsync("Welcome!");

//Get innerText property for the element
var innerText = await element.GetInnerTextAsync();

//Get all child elements
var childElements = await element.QuerySelectorAllAsync("div");

//Change CSS style background colour
await element.EvaluateFunctionAsync("e => e.style.backgroundColor = 'yellow'");

//Type text in an input field
await element.TypeAsync("Welcome to my Website!");

//Click The element
await element.ClickAsync();

// Simple way of chaining method calls together when you don't need a handle to the HtmlElement
var htmlButtonElementInnerText = await devToolsContext.QuerySelectorAsync<HtmlButtonElement>("#myButtonElementId")
    .AndThen(x => x.GetInnerTextAsync());

//Event Handler
//Expose a function to javascript, functions persist across navigations
//So only need to do this once
await devToolsContext.ExposeFunctionAsync("jsAlertButtonClick", () =>
{
    _ = devToolsContext.EvaluateExpressionAsync("window.alert('Hello! You invoked window.alert()');");
});

var jsAlertButton = await devToolsContext.QuerySelectorAsync<HtmlButtonElement>("#jsAlertButton");

//Write up the click event listner to call our exposed function
_ = jsAlertButton.AddEventListenerAsync("click", "jsAlertButtonClick");

//Get a collection of HtmlElements
var divElements = await devToolsContext.QuerySelectorAllAsync<HtmlDivElement>("div");

foreach (var div in divElements)
{
    // Get a reference to the CSSStyleDeclaration
    var style = await div.GetStyleAsync();

    //Set the border to 1px solid red
    await style.SetPropertyAsync("border", "1px solid red", important: true);

    await div.SetAttributeAsync("data-customAttribute", "123");
    await div.SetInnerTextAsync("Updated Div innerText");
}

//Using standard array
var tableRows = await htmlTableElement.GetRowsAsync().ToArrayAsync();

foreach (var row in tableRows)
{
    var cells = await row.GetCellsAsync().ToArrayAsync();
    foreach (var cell in cells)
    {
        var newDiv = await devToolsContext.CreateHtmlElementAsync<HtmlDivElement>("div");
        await newDiv.SetInnerTextAsync("New Div Added!");
        await cell.AppendChildAsync(newDiv);
    }
}

//Get a reference to the HtmlCollection and use async enumerable
//Requires Net Core 3.1 or higher
var tableRowsHtmlCollection = await htmlTableElement.GetRowsAsync();

await foreach (var row in tableRowsHtmlCollection)
{
    var cells = await row.GetCellsAsync();
    await foreach (var cell in cells)
    {
        var newDiv = await devToolsContext.CreateHtmlElementAsync<HtmlDivElement>("div");
        await newDiv.SetInnerTextAsync("New Div Added!");
        await cell.AppendChildAsync(newDiv);
    }
}

[mwpowellhtx]

Could this perhaps be adapted to watch input events, changed, etc? Or submit button clicks? In part I can watch browser address changes for click side effects, but might be better if we detect the event to initiate a new sequence. And watching for inputs approaching that click. Cheers 🍻

[mwpowellhtx]

Re: the context, assuming also that instance would need to be maintained over the life time of exposed functional callbacks, correct?

[mwpowellhtx]

I am trying to expose a function, but it is hanging on the await.

private IDictionary<string, Action> ExposedFunctions { get; set; } = new ConcurrentDictionary<string, Action> { };

private async Task InstallEventListenerAsync<T>(string querySelector, string functionName, string eventType, Action callback = null)
    where T : Element
{
    callback ??= delegate { };

    if (!ExposedFunctions.ContainsKey(functionName))
    {
        ExposedFunctions.Add(functionName, callback);
        await Context.ExposeFunctionAsync(functionName, callback);
        //            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    }

    var element = await Context.QuerySelectorAsync<T>(querySelector);
    await element.AddEventListenerAsync(eventType, functionName);
}

Basically bundles the entire sequence, IMO. Expose the function if necessary. Identify the element for which the event shall be installed, and add the EL.

[mwpowellhtx]

I can puppeteer easily enough, have demonstrated that. And can watch for browser address changes, wait for render idle, etc. Easy peasey. I was curious whether I could take a more "passive" listener approach and coordinate my session logic around that. If the EL stuff cannot be installed, then that pretty much makes that notion a non-starter.

[amaitland]

Could this perhaps be adapted to watch input events, changed, etc? Or submit button clicks?

That should already be possible. The example above is just a subset, check the unit tests for more examples.

Pull requests with enhancements and improvements are welcome.

Re: the context, assuming also that instance would need to be maintained over the life time of exposed functional callbacks, correct?

Do you mean ExposeFunctionAsync? Functions registered should survive navigations.

https://github.com/cefsharp/CefSharp.Dom/blob/dc7f2928e53afcf1061e3026439362ef269b7a04/lib/PuppeteerSharp/DevToolsContext.cs#L2578

I am trying to expose a function, but it is hanging on the await.

If your having problems then I'd suggest downloading the source and adding a unit test that mimics your failing code, then you can easily debug.

There are some unit tests already.

https://github.com/cefsharp/CefSharp.Dom/blob/dc7f2928e53afcf1061e3026439362ef269b7a04/lib/PuppeteerSharp.Tests/DevToolsContextTests/ExposeFunctionTests.cs#L31

[mwpowellhtx]

I was successful in puppeteering after all, so this admittedly extreme approach at listening to inputs turned out to be unnecessary. However, that being said, will bear this in mind for future reference. Thanks again. Best. 🍻