Engine

This guide describes how to create, use, and close Engine.

Refer to Architecture guide for information on how DotNetBrowser architecture is designed and works as well as main components it provides.

Creating an engine

To create a new IEngine instance, use the EngineFactory.Create() or the EngineFactory.Create(EngineOptions) static methods. The method overload with EngineOptions initializes and runs the Chromium engine with the passed options.

IEngine engine = EngineFactory.Create(engineOptions);

Depending on the hardware performance, the initialization process might take several seconds. We recommend that you do not call this method in the application UI thread because it might freeze the whole application for a while. Please use the approach described in the example.

When a new IEngine instance is created, DotNetBrowser performs the following actions:

  1. Checks the environment and makes sure that it is a supported one.
  2. Finds the Chromium binaries and extracts them to the required directory if necessary.
  3. Runs the main process of the Chromium engine.
  4. Establishes the IPC connection between .NET and the Chromium main process.

Engine options

This section highlights major Engine options you can customize.

Rendering mode

This option indicates how the content of a web page is rendered. DotNetBrowser supports the following rendering modes:

  • hardware-accelerated
  • off-screen

Hardware-accelerated mode

Chromium renders the content using GPU and displays it directly on a surface. See the code sample below:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    RenderingMode = RenderingMode.HardwareAccelerated
}
.Build());

Read more about hardware accelerated rendering mode, its performance, and limitations.

Off-screen mode

Chromium renders the content using GPU and copies the pixels to RAM. See the code sample below:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    RenderingMode = RenderingMode.OffScreen
}
.Build());

Read more about off-screen rendering mode, its performance, and limitations.

Language

This option configures the language used on the default error pages and message dialogs. By default, the language is dynamically configured according to the default locale of your .NET application. If the list of supported languages does not contain the language obtained from the .NET application locale, American English is used.

Current option allows to override the default behavior and configure the Chromium engine with the given language. See the code sample below:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    Language = DotNetBrowser.Ui.Language.German
}
.Build());

In the code sample above, we configure the IEngine with the German language. If DotNetBrowser fails to load a web page, the error page in German is displayed:

Error Page

User data directory

Represents an absolute path to the directory containing cache, cookies, history, GPU cache, local storage, visited links, web data, spell checking dictionary files, and so on. See the code sample below:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    UserDataDirectory = @"C:\Users\Me\DotNetBrowser"
}
.Build());

Same user data directory cannot be used simultaneously by multiple IEngine instances running in a single or different .NET applications. The IEngine creation fails if the directory is already used by another IEngine.

If you do not provide the user data directory path, DotNetBrowser creates and uses a temp directory in the user’s temp folder.

Incognito

This option indicates whether incognito mode for the IEngine instance is enabled. In this mode, the user data such as browsing history, cookies, site data, and the information entered in the forms on the web pages is stored in the memory and released once the IEngine is disposed.

By default, incognito mode is disabled.

The following example demonstrates how to enable incognito mode:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    IncognitoEnabled = true
}
.Build());

User agent

Using this option you can configure the default user agent string. See the code sample below:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    UserAgent = "<user-agent>"
}    
.Build());

You can override the default user agent string in each IBrowser instance.

Remote debugging port

This option allows to enable the Chrome Developer Tools (or DevTools) remote debugging. The following example demonstrates how to use this feature:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    RemoteDebuggingPort = 9222
}
.Build());

Now you can load the http://localhost:9222 web page in an IBrowser instance to open the Chrome DevTools page to inspect HTML, debug JavaScript, and others.

Remote Debugging Port

Do not open the remote debugging URL in other web browser applications such as Mozilla Firefox, Microsoft Internet Explorer, Safari, Opera, and others as it can result in a native crash in Chromium DevTools web server.

The remote debugging feature is compatible only with the Chromium version that equals to the version used by DotNetBrowser library. For example, if you use DotNetBrowser 2.0 based on Chromium 69.0.3497.12, you can open the remote debugging URL in Google Chrome/Chromium 69.0.3497.12 only.

We recommend loading the remote debugging URL in an IBrowser instance instead of Google Chrome.

If you want to open DevTools for a web page loaded in a particular IBrowser instance, you can use the approach described in this section.

Disabling touch menu

Long press on Windows 10 touch devices may show the following touch menu:

Touch Menu

The code sample below demonstrates how to disable this touch menu:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    TouchMenuDisabled = true
}
.Build());

Chromium binaries directory

Use this option to define an absolute or relative path to the directory where the Chromium binaries are located or should be extracted to. See the code sample below:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    ChromiumDirectory = @"C:\Users\Me\.DotNetBrowser\chromium"
}
.Build());

For details, refer to Chromium Binaries Location section.

Chromium switches

Use this option to define the Chromium switches passed to the Chromium main process. See the code sample below:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    ChromiumSwitches = { "--<switch-name>", "--<switch-name>=<switch-value>" }
}
.Build());

We do not recommend configuring Chromium using the switches. Instead use Chromium EngineOptions.

Google APIs

Some Chromium features such as Geolocation, Spelling, Speech, and others use Google APIs. To access those APIs, an API Key, OAuth 2.0 client ID, and client secret are required. To acquire the API Key, follow these instructions.

To provide the API Key, client ID, and client secret, use the following code sample:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    GoogleApiKey = "<api-key>",
    GoogleDefaultClientId = "<client-id>",
    GoogleDefaultClientSecret = "<client-secret>"
}
.Build());

Setting up API keys is optional. However, if this is not done, some APIs using Google services fail to work.

Geolocation

Geolocation is one of Chromium features using Google API. You must enable Google Maps Geolocation API and billing, otherwise, Geolocation API fails to work. Once you enable Google Maps Geolocation API and billing, you can provide the keys to DotNetBrowser Chromium engine.

To enable geolocation in DotNetBrowser, grant a specific permission.

Voice recognition

Voice recognition is one of those Chromium features that uses Google API. You must enable Speech API and billing, otherwise voice recognition does not work.

Once you enable Speech API and billing, you can provide the keys to DotNetBrowser Chromium engine.

Engine dispose

The IEngine instance allocates memory and system resources that must be released. When the IEngine is no longer needed, it must be disposed through the IEngine.Dispose() method to shutdown the native Chromium process and free all the allocated memory and system resources. See the example below:

IEngine engine = EngineFactory.Create();
...
engine.Dispose();

Any attempt to use an already disposed IEngine will lead to the ObjectDisposedException.

To check whether the IEngine is disposed, use the IsDisposed property shown in the code sample below:

bool disposed = engine.IsDisposed;

Engine events

Engine disposed

To get notifications when the IEngine is disposed, use the Disposed event shown in the code sample below:

engine.Disposed += (s, e) => {};

Engine crashed

To get notifications when the IEngine unexpectedly crashes due to an error inside the Chromium engine, use the approach shown in the code sample below:

engine.Disposed += (s, e) => 
{
    long exitCode = e.ExitCode;
    // The engine has been crashed if this exit code is non-zero.
});
Go Top