Guides

Introduction
Guides

BrowserView

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

Embedding

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

  • WinForms
  • WPF
  • Avalonia UI

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
  • DotNetBrowser.AvaloniaUi.BrowserView

All 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 browserView = new BrowserView();
browserView.InitializeFrom(browser);

Imports DotNetBrowser.WinForms
' ...
Dim browserView As New BrowserView()
browserView.InitializeFrom(browser)

And embed it into a Form:

form.Controls.Add(view);

form.Controls.Add(view)

Here is the complete example:

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

namespace Embedding.WinForms
{
    /// <summary>
    ///     This example demonstrates how to embed DotNetBrowser
    ///     into a Windows Forms application.
    /// </summary>
    public partial class Form1 : Form
    {
        private const string Url = "https://html5test.teamdev.com/";
        private readonly IBrowser browser;
        private readonly IEngine engine;

        public Form1()
        {
            // Create the Windows Forms BrowserView control.
            BrowserView browserView = new BrowserView
            {
                Dock = DockStyle.Fill
            };

            // Create and initialize the IEngine instance.
            EngineOptions engineOptions = new EngineOptions.Builder
            {
                RenderingMode = RenderingMode.HardwareAccelerated
            }.Build();
            engine = EngineFactory.Create(engineOptions);

            // Create the IBrowser instance.
            browser = engine.CreateBrowser();

            InitializeComponent();

            // Add the BrowserView control to the Form.
            Controls.Add(browserView);
            FormClosed += Form1_FormClosed;

            // Initialize the Windows Forms BrowserView control.
            browserView.InitializeFrom(browser);
            browser.Navigation.LoadUrl(Url);
        }

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

Imports System.Windows.Forms
Imports DotNetBrowser.Browser
Imports DotNetBrowser.Engine
Imports DotNetBrowser.WinForms

Namespace Embedding.WinForms
    ''' <summary>
    '''     This example demonstrates how to embed DotNetBrowser
    '''     into a Windows Forms application.
    ''' </summary>
    Partial Public Class Form1
        Inherits Form

        Private Const Url As String = "https://html5test.teamdev.com/"
        Private ReadOnly browser As IBrowser
        Private ReadOnly engine As IEngine

        Public Sub New()
            ' Create the Windows Forms BrowserView control.
            Dim browserView As New BrowserView With {.Dock = DockStyle.Fill}

            ' Create and initialize the IEngine instance.
            Dim engineOptions As EngineOptions = New EngineOptions.Builder With {
                .RenderingMode = RenderingMode.HardwareAccelerated
            }.Build()
            engine = EngineFactory.Create(engineOptions)

            ' Create the IBrowser instance.
            browser = engine.CreateBrowser()

            InitializeComponent()

            ' Add the BrowserView control to the Form.
            Controls.Add(browserView)
            AddHandler FormClosed, AddressOf Form1_FormClosed

            ' Initialize the Windows Forms BrowserView control.
            browserView.InitializeFrom(browser)
            browser.Navigation.LoadUrl(Url)
        End Sub

        Private Sub Form1_FormClosed(sender As Object, e As FormClosedEventArgs)
            browser?.Dispose()
            engine?.Dispose()
        End Sub
    End Class
End Namespace

The output of this example looks as follows: WinForms View

The complete project is available in our repository: C#, VB.

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 browserView = new BrowserView();
browserView.InitializeFrom(browser);

Imports DotNetBrowser.Wpf
' ...
Dim browserView As New BrowserView()
browserView.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="Embedding.Wpf.MainWindow"
    mc:Ignorable="d"
    Title="MainWindow" Height="480" Width="800" Closed="Window_Closed">
    <Grid>
        <WPF:BrowserView Name="browserView" />
    </Grid>
</Window>

MainWindow.xaml.cs

MainWindow.xaml.vb

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

namespace Embedding.Wpf
{
    /// <summary>
    ///     This example demonstrates how to embed DotNetBrowser
    ///     into a WPF application.
    /// </summary>
    public partial class MainWindow : Window
    {
        private const string Url = "https://html5test.teamdev.com/";
        private readonly IBrowser browser;
        private readonly IEngine engine;

        public MainWindow()
        {
            // Create and initialize the IEngine instance.
            EngineOptions engineOptions = new EngineOptions.Builder
            {
                RenderingMode = RenderingMode.HardwareAccelerated
            }.Build();
            engine = EngineFactory.Create(engineOptions);

            // Create the IBrowser instance.
            browser = engine.CreateBrowser();

            InitializeComponent();

            // Initialize the WPF BrowserView control.
            browserView.InitializeFrom(browser);
            browser.Navigation.LoadUrl(Url);
        }

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

Imports System.Windows
Imports DotNetBrowser.Browser
Imports DotNetBrowser.Engine

Namespace Embedding.Wpf
    ''' <summary>
    '''     This example demonstrates how to embed DotNetBrowser
    '''     into a WPF application.
    ''' </summary>
    Partial Public Class MainWindow
        Inherits Window

        Private Const Url As String = "https://html5test.teamdev.com/"
        Private ReadOnly browser As IBrowser
        Private ReadOnly engine As IEngine

        Public Sub New()
            ' Create and initialize the IEngine instance.
            Dim engineOptions As EngineOptions = New EngineOptions.Builder With {
                .RenderingMode = RenderingMode.HardwareAccelerated
            }.Build()
            engine = EngineFactory.Create(engineOptions)

            ' Create the IBrowser instance.
            browser = engine.CreateBrowser()

            InitializeComponent()

            ' Initialize the WPF BrowserView control.
            browserView.InitializeFrom(browser)
            browser.Navigation.LoadUrl(Url)
        End Sub

        Private Sub Window_Closed(sender As Object, e As EventArgs)
            browser?.Dispose()
            engine?.Dispose()
        End Sub
    End Class
End Namespace

The output of this example looks as follows: WPF View

The complete project is available in our repository: C#, VB.

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;
using System.Windows.Forms;
using System.Windows.Forms.Integration;
using DotNetBrowser.Browser;
using DotNetBrowser.Engine;
using DotNetBrowser.Wpf;

namespace ElementHostEmbedding.WinForms
{
    public partial class Form1 : Form
    {
        private const string Url = "https://html5test.teamdev.com";
        private readonly IBrowser browser;
        private readonly IEngine engine;
        private readonly ElementHost host;

        public Form1()
        {
            // Create and initialize the IEngine instance.
            EngineOptions engineOptions = new EngineOptions.Builder
            {
                RenderingMode = RenderingMode.OffScreen,
                // Set the license key programmatically.
                LicenseKey = "your_license_key_goes_here"
            }.Build();
            engine = EngineFactory.Create(engineOptions);

            // Create the IBrowser instance.
            browser = engine.CreateBrowser();
            // Create the WPF BrowserView control.
            BrowserView browserView = new BrowserView();
            
            InitializeComponent();
            FormClosed += Form1_FormClosed;

            // Create and initialize the ElementHost control.
            host = new ElementHost
            {
                Dock = DockStyle.Fill,
                Child = browserView
            };
            Controls.Add(host);

            // Initialize the WPF BrowserView control.
            browserView.InitializeFrom(browser);
            browser.Navigation.LoadUrl(Url);
        }

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

Imports System.Windows.Forms.Integration
Imports DotNetBrowser.Browser
Imports DotNetBrowser.Engine
Imports DotNetBrowser.Wpf

Namespace ElementHostEmbedding.WinForms
    Partial Public Class Form1
        Inherits Form

        Private Const Url As String = "https://html5test.teamdev.com"
        Private ReadOnly browser As IBrowser
        Private ReadOnly engine As IEngine
        Private ReadOnly host As ElementHost

        Public Sub New()
            ' Create and initialize the IEngine instance.
            Dim engineOptions As EngineOptions = New EngineOptions.Builder With {
                .RenderingMode = RenderingMode.OffScreen,
                .LicenseKey = "your_license_key_goes_here"
            }.Build()
            engine = EngineFactory.Create(engineOptions)

            ' Create the IBrowser instance.
            browser = engine.CreateBrowser()
            ' Create the WPF BrowserView control.
            Dim browserView As New BrowserView()

            InitializeComponent()
            AddHandler FormClosed, AddressOf Form1_FormClosed

            ' Create and initialize the ElementHost control.
            host = New ElementHost With {
                .Dock = DockStyle.Fill,
                .Child = browserView
            }
            Controls.Add(host)

            ' Initialize the WPF BrowserView control.
            browserView.InitializeFrom(browser)
            browser.Navigation.LoadUrl(Url)
        End Sub

        Private Sub Form1_FormClosed(sender As Object, e As EventArgs)
            browser?.Dispose()
            engine?.Dispose()
        End Sub
    End Class
End Namespace

The complete example is available in our repository: C#, VB.

Avalonia UI

To display the content of a web page in an Avalonia UI application, create an instance of the DotNetBrowser.AvaloniaUi.BrowserView:

using DotNetBrowser.AvaloniaUi;
// ...
BrowserView browserView = new BrowserView();
browserView.InitializeFrom(browser);

Imports DotNetBrowser.AvaloniaUi
' ...
Dim browserView As New BrowserView()
browserView.InitializeFrom(browser)

Here is the complete example:

MainWindow.axaml

<Window xmlns="https://github.com/avaloniaui"
        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:app="clr-namespace:DotNetBrowser.AvaloniaUi;assembly=DotNetBrowser.AvaloniaUi"
        mc:Ignorable="d" d:DesignWidth="800" d:DesignHeight="450"
        x:Class="Embedding.AvaloniaUi.MainWindow"
        Title="Embedding.AvaloniaUi" Closed="Window_Closed">
    <app:BrowserView x:Name="BrowserView"/>
</Window>

MainWindow.axaml.cs

using System;
using Avalonia.Controls;
using DotNetBrowser.Browser;
using DotNetBrowser.Engine;

namespace Embedding.AvaloniaUi
{

    /// <summary>
    ///     This example demonstrates how to embed DotNetBrowser
    ///     into an Avalonia application.
    /// </summary>
    public partial class MainWindow : Window
    {
        private const string Url = "https://html5test.teamdev.com/";
        private readonly IBrowser browser;
        private readonly IEngine engine;

        public MainWindow()
        {
            // Create and initialize the IEngine instance.
            EngineOptions engineOptions = new EngineOptions.Builder
            {
                //LicenseKey = "your_license_key"
            }.Build();
            engine = EngineFactory.Create(engineOptions);

            // Create the IBrowser instance.
            browser = engine.CreateBrowser();

            InitializeComponent();

            // Initialize the Avalonia UI BrowserView control.
            BrowserView.InitializeFrom(browser);
            browser.Navigation.LoadUrl(Url);
        }

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

The output of this example looks as follows: Avalonia UI View

The complete project is available in our repository: C#, VB.

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, full touch and gestures support is available in WPF and Avalonia UI. In WinForms, this functionality is limited to tapping and long-pressing, because touch support in WinForms itself is limited.

Drag and Drop (DnD) functionality is not supported for WPF, WinForms, and Avalonia UI in the OffScreen rendering mode.

Go Top