Migrating DotNetBrowser from 2.2 to 2.3

In DotNetBrowser 2.3 the Chromium engine has been upgraded to version 84. This Chromium version has several breaking changes in the source code that affect the public API of product. In this migration guide we describe what API has been removed/changed in 2.3 and what alternatives you should use instead.

Removed API

Network

Overriding HTTP request readers

The SendHeadersHandler and SendProxyHeadersHandler have been removed in Chromium 84.

v2.2

network.SendHeadersHandler =
    new Handler<SendHeadersParameters, SendHeadersResponse>((parameters) =>
    {
        IEnumerable<IHttpHeader> headers = parameters.Headers;
        List<HttpHeader> newHttpHeaders = headers.Cast<HttpHeader>().ToList();
        newHttpHeaders.Add(new HttpHeader("<header-name>", "<header-value>"));
        return SendHeadersResponse.OverrideHeaders(newHttpHeaders);
    });
network.SendProxyHeadersHandler =
    new Handler<SendProxyHeadersParameters, SendProxyHeadersResponse>(p =>
    {
        IEnumerable<IHttpHeader> headers = p.Headers;
        List<HttpHeader> newHttpHeaders = headers.Cast<HttpHeader>().ToList();
        newHttpHeaders.Add(new HttpHeader("<header-name>", "<header-value>"));
        return SendProxyHeadersResponse.OverrideHeaders(newHttpHeaders);
    });

v2.3

To override the HTTP headers before they will be sent to a web server use the INetwork.StartTransactionHandler API:

INetwork.StartTransactionHandler = 
    new Handler<StartTransactionParameters, StartTransactionResponse>(p =>
    {
        IEnumerable<IHttpHeader> headers = p.Headers;
        List<HttpHeader> newHttpHeaders = headers.Cast<HttpHeader>().ToList();
        newHttpHeaders.Add(new HttpHeader("<header-name>", "<header-value>"));
        return StartTransactionResponse.OverrideHeaders(newHttpHeaders);
    });

Filtering resources

The LoadResourceHandler handler has been removed in Chromium 84.

v2.2

engine.Network.LoadResourceHandler =
    new Handler<LoadResourceParameters, LoadResourceResponse>(p =>
    {
        if (p.ResourceType == ResourceType.Image)
        {
            return LoadResourceResponse.Cancel();
        }

        return LoadResourceResponse.Continue();
    });

v2.3

The SendUrlRequestHandler should be used instead. In DotNetBrowser 2.3, it also provides an ability to cancel the request:

engine.Network.SendUrlRequestHandler =
    new Handler<SendUrlRequestParameters, SendUrlRequestResponse>(p =>
    {
        if (p.ResourceType == ResourceType.Image)
        {
            return SendUrlRequestResponse.Cancel();
        }

        return SendUrlRequestResponse.Continue();
    });

The RequestCompleted event

The RequestCompletedEventArgs.IsStarted property has been removed because now the URL Request cannot be completed if it hasn’t been started. So, there’s no sense in this property because it always returns true.

The FrameLoadFailed event

The FrameLoadFailedEventArgs.ErrorDescription property has been removed. It is no longer supported in Chromium 84.

Added or updated API

URL Request

The UrlRequest class has been extended with the Browser, ResourceType, SslVersion properties. All these properties can be used to obtain more information about this URL request, including the browser that initiated this request, the type of the requested resource, and the SSL version used to perform this request.

As a result, it is now possible to obtain the bound IBrowser instance in InterceptRequestHandler :

Engine.Network.InterceptRequestHandler =
    new Handler<InterceptRequestParameters, InterceptRequestResponse>(data =>
    {
        //Access the browser bound to the URL request.
        IBrowser browser = data.UrlRequest.Browser;
        //Tell the Chromium engine to handle this request.
        return InterceptRequestResponse.Proceed();
    });

Save as PDF

The SuggestedFileName and SuggestedDirectoryproperties were added to the SaveAsPdfParameters.

browser.Dialogs.SaveAsPdfHandler =
    new Handler<SaveAsPdfParameters, SaveAsPdfResponse>(p =>
    {
        // The given file should be saved.
        string pdfFile = Path.Combine(p.SuggestedDirectory, p.SuggestedFileName);
        return SaveAsPdfResponse.SaveToFile(pdfFile);
    });

Drag and Drop

The EnterDragHandler and DropHandler are added to IDragAndDrop. These handlers can be used to intercept the corresponding drag and drop events on the web page in the hardware-accelerated rendering mode. For example:

browser.DragAndDrop.EnterDragHandler = new Handler<EnterDragParameters>(OnDragEnter);
browser.DragAndDrop.DropHandler = new Handler<DropParameters>(OnDrop);
private void OnDragEnter(EnterDragParameters arg)
{
    if (arg.Event.DropData != null)
    {
        //Write file names to debug output.
        foreach (IFileValue file in arg.Event.DropData.Files)
        {
            Debug.WriteLine($"OnDragEnter: File = {file?.FileName}");
        }
    }
}
private void OnDrop(DropParameters arg)
{
    if (arg.Event.DropData != null)
    {
        //Write file names to debug output.
        foreach (IFileValue file in arg.Event.DropData.Files)
        {
            Debug.WriteLine($"OnDrop: File = {file?.FileName}");
        }
    }
}

In .NET Framework, it is also possible to work with the IDataObject instance in the scope of these handlers to receive and process the platform-specific representation of the dragged and dropped data. This functionality becomes available when the --enable-com-in-drag-drop Chromium switch is specified. For example:

private void OnDragEnter(EnterDragParameters arg)
{
    System.Runtime.InteropServices.ComTypes.IDataObject dataObject = arg.Event.DataObject;
    if (dataObject != null)
    {
        //Process IDataObject contents.
    }
}
private void OnDrop(DropParameters arg)
{
    System.Runtime.InteropServices.ComTypes.IDataObject dataObject = arg.Event.DataObject;
    if (dataObject != null)
    {
        //Process IDataObject contents.
    }
}

DOM

DOM key events

The DomKeyCode enumeration is introduced and used in DOM key events instead of the existing KeyCode enumeration. The previous implementation of obtaining the key code relied on the obsolete DOM API, and appeared to work improperly in some cases.

The Character property is also added to DOM key events to provide an actuat character when it is available for the DOM event.

Go Top