Migrating DotNetBrowser from 2.6 to 2.7

In this migration guide we describe what API has been removed/changed in 2.7 and what alternatives you should use instead.

Removed API

Loading HTML


In certain cases, it was possible to load a simple HTML document using the IFrame.LoadHtml() or IFrame.LoadData(). Here is how it looked like:

var html = "<html><head></head><body><h1>Hello world!</h1></body></html>";


The security restrictions became more tight. As a result, when an HTML document relying on external scripts is loaded using LoadHtml(), it never loads those scripts and logs errors saying Failed to load resource: net::ERR_NOT_IMPLEMENTED. The same behavior could also be observed with images in HTML.

There is no way to fix this behavior without breaking the Chromium security, that’s why both IFrame.LoadHtml and IFrame.LoadData were removed completely from the API.

The possible workaround is to use data: encoded URI and then load it using the regular LoadUrl call. Here is an example:

var html = "<html><head></head><body><h1>Html Encoded in URL!</h1></body></html>";
var base64EncodedHtml = Convert.ToBase64String(Encoding.UTF8.GetBytes(html));
browser.Navigation.LoadUrl("data:text/html;base64," + base64EncodedHtml).Wait();

However, the base URL cannot be set when using this workaround.

Another possible approach is to register a Scheme with a handler and intercept the corresponding request to provide the HTML. See the corresponding article.

Updated API

v2.6 Previously, it was necessary to pass the web page URL when setting a cookie:

Cookie cookie = new Cookie.Builder
    Name = "name",
    Value = "value",
    DomainName = ".google.com",
    Path = "/"

bool success = engine.CookieStore.SetCookie("https://www.google.com",cookie).Result;


ICookieStore.SetCookie() now has no URL parameter, as it was previously used for validation purposes only:

Cookie cookie = new Cookie.Builder
    Name = "name",
    Value = "value",
    DomainName = ".google.com",
    Path = "/"

bool success = engine.CookieStore.SetCookie(cookie).Result;

In addition, ICookieStore.Delete() now returns a Task instead of Task<bool>.

Added API

Default background color

When Chromium does not know the background color of a web page, or the color has not been specified at all, it uses the white color. In 2.7 we extended the API with new functionality that allows you to configure the default background color that Chromium should use instead of the default white color in such cases.

The following code demonstrates how to set the desired background color for about:blank page:

Color purple = new Color(0.6f, 0.3f, 0.6f);
browser.Settings.DefaultBackgroundColor = purple;

Get frame contents as text

The IFrame.Text property returns the content of the frame and its sub-frames as plain text:

string text = browser.MainFrame?.Text;

View page source

Now you can view source of the loaded web page or frame like in Google Chrome via IFrame.ViewSource:


The code above tells Chromium to create and open a new popup window with the HTML source of the main frame.

JavaScript Promise support

Now you can can work with the JavaScript promises directly without a need to create a wrapper over IJsObject. For example:

IJsPromise promise = browser.MainFrame

//Invoke some .NET code when the promise is fulfilled or rejected.
promise.Then(o => Console.WriteLine("Promise fulfilled"),
             e => Console.WriteLine("Promise rejected"));

Preferred color scheme

It is possible to force the preferred color scheme via browser settings:

browser.Settings.PreferredColorScheme = PreferredColorScheme.Dark; //forces dark mode
browser.Settings.PreferredColorScheme = PreferredColorScheme.Light; //forces light mode

The websites which respect the prefers-color-scheme media query will switch to the light or dark mode accordingly.

Chromium profiles support

Each Engine has a default Profile you can access via:

IProfile defaultProfile = engine.Profiles.Default;

The below services now belong to Profile. You can manage cookies, downloads, permissions, plugins, etc. independently for every profile:

  • ZoomLevels
  • Plugins
  • Proxy
  • Network
  • SpellChecker
  • CookieStore
  • HttpCache
  • Downloads
  • Permissions

Find out more in the corresponding guide.

Go Top