BrowserView

The document describes how to embed a visual component that displays content of web pages in WinForms and WPF applications.

Embedding

DotNetBrowser can be used in .NET applications built with the following .NET GUI frameworks:

  • WinForms
  • WPF

The IBrowser component itself is not a visual one that allows displaying web page. To display the content of a web page loaded in IBrowser, please use one of the following controls, depending on the GUI framework used:

  • DotNetBrowser.WinForms.BrowserView
  • DotNetBrowser.Wpf.BrowserView

Both of these controls implement the IBrowserView interface. The connection of a view with a specific IBrowser instance is established when necessary by calling InitializeFrom(IBrowser) extension method.

It is not possible to initialize several views from a single browser - if there is a browser view bound to this browser instance, that view will be de-initialized by a subsequent InitializeFrom call.

The InitializeFrom(IBrowser) extension method should be called from the UI thread.

The IBrowserView implementations do not dispose the connected IBrowser or IEngine instances when the application is closed. As a result, the browser and engine will appear alive even after all the application windows are closed and prevent the application from terminating. To handle this case, it is necessary to dispose IBrowser or IEngine instances during your application shutdown.

WinForms

To display the content of a web page in a .NET WinForms application create an instance of the DotNetBrowser.WinForms.BrowserView:

using DotNetBrowser.WinForms;
...
BrowserView view = new BrowserView();
view.InitializeFrom(browser);

And embed it into a Form:

form.Controls.Add(view);

Here is the complete example:

using System.Threading.Tasks;
using System.Windows.Forms;
using DotNetBrowser.Browser;
using DotNetBrowser.Engine;
using DotNetBrowser.WinForms;

namespace WinForms.Sample
{
    public partial class Form1 : Form
    {
        BrowserView webView;

        private IBrowser browser;
        private IEngine engine;

        public Form1()
        {
            webView = new BrowserView() { Dock = DockStyle.Fill };
            Task.Run(() =>
                {
                    engine = EngineFactory.Create(
                        new EngineOptions.Builder
                        {
                            RenderingMode = RenderingMode.HardwareAccelerated 
                        }
                        .Build());
                    browser = engine.CreateBrowser();
                })
                .ContinueWith(t =>
                {
                    webView.InitializeFrom(browser);
                    browser.Navigation.LoadUrl("https://www.teamdev.com/");
                }, TaskScheduler.FromCurrentSynchronizationContext());
            InitializeComponent();
            FormClosing += Form1_FormClosing;
            Controls.Add(webView);
        }

        private void Form1_FormClosing(object sender, FormClosingEventArgs e)
        {
            browser?.Dispose();
            engine?.Dispose();
        }
    }
}

The output of this example looks as follows: WinForms View

WPF

To display the content of a web page in a WPF application, create an instance of the DotNetBrowser.Wpf.BrowserView:

using DotNetBrowser.Wpf;
...
BrowserView view = new BrowserView();
view.InitializeFrom(browser);

Here is the complete example:

MainWindow.xaml

<Window
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:WPF="clr-namespace:DotNetBrowser.Wpf;assembly=DotNetBrowser.Wpf" 
    x:Class="WPF.Sample.MainWindow"
    mc:Ignorable="d"
    Title="MainWindow" Height="480" Width="800" Closed="Window_Closed">
    <Grid>
        <WPF:BrowserView Name="browserView" />
    </Grid>
</Window>

MainWindow.xaml.cs

using System;
using System.Threading.Tasks;
using System.Windows;
using DotNetBrowser.Browser;
using DotNetBrowser.Engine;

namespace WPF.Sample
{
    /// <summary>
    /// Interaction logic for MainWindow.xaml
    /// </summary>
    public partial class MainWindow : Window
    {
        private IBrowser browser;
        private IEngine engine;

        public MainWindow()
        {
            Task.Run(() =>
                {
                    engine = EngineFactory.Create(
                        new EngineOptions.Builder
                        {
                            RenderingMode = RenderingMode.HardwareAccelerated 
                        }
                        .Build());
                    browser = engine.CreateBrowser();
                })
                .ContinueWith(t =>
                {
                    browserView.InitializeFrom(browser);
                    browser.Navigation.LoadUrl("https://www.teamdev.com/");
                }, TaskScheduler.FromCurrentSynchronizationContext());

            InitializeComponent();
        }

        private void Window_Closed(object sender, EventArgs e)
        {
            browser.Dispose();
            engine.Dispose();
        }
    }
}

The output of this example looks as follows: WPF View

ElementHost

We recommend using WinForms BrowserView in WinForms applications as well as WPF BrowserView in WPF applications.

Sometimes you need to embed WPF BrowserView into a WinForms application. For example, when developing a complex web browser control using WPF UI Toolkit, and you have to display this WPF control in a WinForms application.

Since v.2.0, you can embed WPF BrowserView into a WinForms window using ElementHost. It is supported with all rendering modes.

using System.Windows.Forms;
using System.Windows.Forms.Integration;
using DotNetBrowser.Browser;
using DotNetBrowser.Engine;
using DotNetBrowser.Wpf;

namespace WinForms.ElementHostSample
{
    public partial class Form1 : Form
    {
        private IEngine engine;
        private IBrowser browser;

        public Form1()
        {
            InitializeComponent();

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

            BrowserView browserView = new BrowserView();
            browser = engine.CreateBrowser();
            browser.Navigation.LoadUrl("https://teamdev.com/dotnetbrowser");
            browserView.InitializeFrom(browser);

            ElementHost host = new ElementHost
            {
                Dock = DockStyle.Fill,
                Child = browserView
            };

            Controls.Add(host);
        }

        private void Form1_FormClosed(object sender, FormClosedEventArgs e)
        {
            browser.Dispose();
            engine.Dispose();
        }
    }
}

Rendering

DotNetBrowser supports several rendering modes. In this section, we describe each of the modes with their performance and limitations, and provide you with recommendations on choosing the right mode depending on the type of the .NET application.

Hardware-accelerated

The library renders the content of a web page using the GPU in Chromium GPU process and displays it directly on a surface. In this mode the BrowserView creates and embeds a native heavyweight window (surface) on which the library renders the produced pixels.

Off-screen

The library renders the content of a web page using the GPU in Chromium GPU process and copies the pixels to an off-screen buffer allocated in the .NET process memory. In this mode, BrowserView creates and embeds a lightweight component that reads the pixels from the off-screen buffer and displays them using the UI framework capabilities.

Limitations

WPF airspace issue

It is not recommended to display other WPF components over the BrowserView when the HardwareAccelerated rendering mode is enabled since BrowserView displays a native Win32 window using HwndHost. As a result, it can often cause well-known airspace issues.

WPF layered windows

Configuring a WPF Window with the AllowsTransparency style adds the WS_EX_LAYERED window style flag to WPF window on Windows. This flag is used to create a layered window. The layered window is a window that draws its content off-screen. If we embed a native window into a layered window when the HardwareAccelerated rendering mode is enabled, its content is not painted due to the window types conflict.

Mouse, keyboard, touch, drag and drop

In the OffScreen rendering mode, mouse, keyboard, and touch events are processed on the .NET side and forwarded to the Chromium engine.

At the moment .NET does not provide a fully functional touch events support, so DotNetBrowser does not support touch gestures in this rendering mode. The same limitation applies to the Drag and Drop (DnD) functionality.

Go Top