指南

介绍

安装

指南

故障排除

移民

引擎

本指南描述了如何创建、使用和关闭 Engine。

有关 DotNetBrowser 架构的设计和工作方式以及它提供的主要组件的信息，请参阅架构指南。

创建引擎

要创建一个新的 IEngine 实例，可以使用 EngineFactory.Create() 或 EngineFactory.Create(EngineOptions) 静态方法。使用 EngineOptions 的重载方法初始化并运行具有传递选项的 Chromium 引擎。

      IEngine engine = EngineFactory.Create(engineOptions);

    

      Dim engine As IEngine = EngineFactory.Create(engineOptions)

    

根据硬件性能，初始化过程可能需要几秒钟。我们建议您不要在应用程序 UI 线程中调用此方法，因为它可能会冻结整个应用程序一段时间。请使用示例中描述的方法。

创建新的 IEngine 实例时，DotNetBrowser 会执行以下操作：

检查环境并确保它是受支持的。
查找 Chromium 二进制文件并在必要时将它们提取到所需的目录。
运行 Chromium 引擎的主进程。
在 .NET 和 Chromium 主进程之间建立 IPC 连接。

引擎选项

本节重点介绍您可以自定义的主要引擎选项。

渲染模式

此选项指示网页内容的呈现方式。 DotNetBrowser 支持以下渲染模式：

硬件加速
离屏

硬件加速模式

Chromium 使用 GPU 渲染内容并将其直接显示在表面上。请参阅以下代码示例：

      IEngine engine = EngineFactory.Create(RenderingMode.HardwareAccelerated);

    

      Dim engine As IEngine = EngineFactory.Create(RenderingMode.HardwareAccelerated)

    

阅读有关硬件加速渲染模式、其性能和限制的更多信息。

离屏模式

Chromium 使用 GPU 渲染内容并将像素复制到 RAM。请参阅以下代码示例：

      IEngine engine = EngineFactory.Create(RenderingMode.OffScreen);

    

      Dim engine As IEngine = EngineFactory.Create(RenderingMode.OffScreen)

    

阅读有关离屏渲染模式、其性能和限制的更多信息。

语言

此选项配置默认错误页面和消息对话框中使用的语言。默认情况下，语言是根据 .NET 应用程序的默认语言环境动态配置的。如果支持的语言列表不包含从 .NET 应用程序区域设置获得的语言，则使用美国英语。

当前选项允许覆盖默认行为并使用给定语言配置 Chromium 引擎。请参阅以下代码示例：

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

    

      Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .Language = DotNetBrowser.Ui.Language.German
}.Build())

    

在上面的代码示例中，我们使用德语配置 IEngine 。如果 DotNetBrowser 加载网页失败，将显示德语错误页面：

Error Page

用户数据目录

表示包含配置文件及其数据（例如缓存、cookie、历史记录、GPU 缓存、本地存储、访问过的链接、网络数据、拼写检查字典文件等）的目录的绝对路径。请参阅以下代码示例：

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

    

      Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .UserDataDirectory = "C:\Users\Me\DotNetBrowser"
}.Build())

    

运行在单个或不同 .NET 应用程序中的多个 IEngine 实例不能同时使用相同的用户数据目录。如果该目录已被另一个 IEngine 使用，则 IEngine 创建失败。

如果您不提供用户数据目录路径，DotNetBrowser 会在用户的临时文件夹中创建并使用一个临时目录。

隐身

此选项指示是否启用默认配置文件的隐身模式。在这种模式下，浏览历史记录、cookies、站点数据等用户数据以及在网页表格中输入的信息都存储在内存中。一旦您删除 Profile 或处理 IEngine，它就会被释放。

默认情况下，隐身模式处于禁用状态。

以下示例演示了如何启用隐身模式：

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

    

      Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .IncognitoEnabled = true
}.Build())

    

按照 URI 方案拦截请求

Schemes 选项可用于配置每个方案的 URL 请求拦截。以下是如何将其配置为拦截和处理自定义 URI 方案的所有请求：

      Handler<InterceptRequestParameters, InterceptRequestResponse> handler =
    new Handler<InterceptRequestParameters, InterceptRequestResponse>(p =>
    {
        UrlRequestJobOptions options = new UrlRequestJobOptions
        {
            Headers = new List<HttpHeader>
            {
                new HttpHeader("Content-Type", "text/html", "charset=utf-8")
            }
        };

        UrlRequestJob job = p.Network.CreateUrlRequestJob(p.UrlRequest, options);

        Task.Run(() =>
        {
            // 请求处理在工作线程中进行
            // 以避免网页冻结。
            job.Write(Encoding.UTF8.GetBytes("Hello world!"));
            job.Complete();
        });

        return InterceptRequestResponse.Intercept(job);
    });

EngineOptions engineOptions = new EngineOptions.Builder
{
    Schemes = 
    {
        { Scheme.Create("myscheme"), handler }
    }
}.Build();

using (IEngine engine = EngineFactory.Create(engineOptions))
{
    using (IBrowser browser = engine.CreateBrowser())
    {
        NavigationResult result =
            browser.Navigation.LoadUrl("myscheme://test1").Result;

        // 如果未设置方案处理程序，则 LoadResult 将为
        // LoadResult.Stopped。
        // 然而，使用方案处理程序，网页会被加载并且
        // 其结果会是 LoadResult.Completed。
        Console.WriteLine($"Load result: {result.LoadResult}");
        Console.WriteLine($"HTML: {browser.MainFrame.Html}");
    }
}

    

      Dim interceptRequestHandler =
        New Handler(Of InterceptRequestParameters, InterceptRequestResponse)(
            Function(p)
                Dim options = New UrlRequestJobOptions With {
                        .Headers = New List(Of HttpHeader) From {
                        New HttpHeader("Content-Type", "text/html",
                                       "charset=utf-8")
                        }
                        }

                Dim job As UrlRequestJob =
                        p.Network.CreateUrlRequestJob(p.UrlRequest, options)

                Task.Run(Sub()
                             ' 请求处理在工作线程中进行
                             ' 以避免网页冻结。
                             job.Write(Encoding.UTF8.GetBytes("Hello world!"))
                             job.Complete()
                         End Sub)

                Return InterceptRequestResponse.Intercept(job)
            End Function)


Dim engineOptionsBuilder = new EngineOptions.Builder
With engineOptionsBuilder
    .Schemes.Add(Scheme.Create("myscheme"), interceptRequestHandler)
End With

Dim engineOptions = engineOptionsBuilder.Build()

Using engine As IEngine = EngineFactory.Create(engineOptions)

    Using browser As IBrowser = engine.CreateBrowser()
        Dim result As NavigationResult =
                browser.Navigation.LoadUrl("myscheme://test1").Result
        ' 如果未设置方案处理程序，则 LoadResult 将为
        ' LoadResult.Stopped。
        ' 然而，使用方案处理程序，网页会被加载并且
        ' 其结果会是 LoadResult.Completed。
        Console.WriteLine($"Load result: {result.LoadResult.ToString()}")
        Console.WriteLine($"HTML: {browser.MainFrame.Html}")
    End Using
End Using

    

前往我们的存储库获取完整示例： C#, VB.NET.

可以使用相同的方法来拦截和处理所有 HTTPS 请求。

并非所有方案都可以被拦截。例如，无法拦截 chrome、data 或 chrome-extensions 等方案。拦截它们的尝试可能会导致意外行为或 Chromium 内部崩溃。

此外，一些方案被视为本地方案，例如 file。它们无法被拦截，因为它不是网络请求。

如果无法拦截指定的方案， EngineOptions 构建器将抛出相应的异常。例如：“无法拦截“文件”方案。”

用户代理

使用此选项，您可以配置默认用户代理字符串。请参阅以下代码示例：

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

    

      Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .UserAgent = "<user-agent>"
}.Build())

    

您可以覆盖每个 IBrowser 实例中的默认用户代理字符串。

远程调试端口

此选项允许启用 Chrome 开发者工具（或 DevTools）远程调试。以下示例演示了如何使用此功能：

      IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    ChromiumSwitches = { "--remote-allow-origins=http://localhost:9222" },
    RemoteDebuggingPort = 9222
}.Build());

    

      Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .ChromiumSwitches = { "--remote-allow-origins=http://localhost:9222" },
    .RemoteDebuggingPort = 9222
}.Build())

    

从Chromium 111开始，需要指定 remote-allow-origins 开关以允许来自指定来源的网络套接字连接。更多信息请参见Issue 1422444.。

现在，您可以在 IBrowser 实例中加载远程调试 URL，以打开 DevTools 页面来检查 HTML、调试 JavaScript 等。请参阅下面的示例：

Remote Debugging Port

不要在其他网页浏览器应用程序（例如 Mozilla Firefox、Microsoft Internet Explorer、Safari、Opera 等）中打开远程调试 URL，因为它可能会导致 Chromium DevTools 网络服务器本机崩溃。

远程调试功能仅与 DotNetBrowser 库使用的 Chromium 版本兼容。比如你使用基于Chromium 119.0.6045.105 的 DotNetBrowser 2.24.2，你只能在同一个Chromium/Google Chrome中打开远程调试 URL。如果您使用以前的 DotNetBrowser 版本，则需要下载相应的 Chromium 版本。

我们建议在 IBrowser 实例而不是 Google Chrome 中加载远程调试 URL。

禁用触摸菜单

在 Windows 10 触摸设备上长按可能会显示以下触摸菜单：

下面的代码示例演示了如何禁用此触摸菜单：

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

    

      Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .TouchMenuDisabled = true
}.Build())

    

禁用谷歌流量

此选项禁用不必要的流量到诸如 Google Cloud Messaging、Translate Ranker、Extensions Updater、Safe Browsing 等 Chromium 服务。

请参阅下面的代码示例：

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

    

      Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .GoogleTrafficDisabled = true
}.Build())

    

Chromium 二进制文件目录

使用此选项定义 Chromium 二进制文件所在目录或应提取到的目录的绝对路径或相对路径。请参阅以下代码示例：

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

    

      Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .ChromiumDirectory = @"C:\Users\Me\.DotNetBrowser\chromium"
}.Build())

    

有关详细信息，请参阅 Chromium 二进制文件位置部分。

自动播放视频

要在网页上启用自动播放视频内容，请使用以下选项：

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

    

      Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .AutoplayEnabled = true
}.Build())

    

Chromium 开关

使用此选项定义传递给 Chromium 主进程的 Chromium 开关。请参阅下面的代码示例：

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

    

      Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .ChromiumSwitches = { "--<switch-name>", "--<switch-name>=<switch-value>" }
}.Build())

    

并非所有 Chromium 开关都受 DotNetBrowser 支持，因此不能保证传递的开关会正常工作且不会导致任何错误。我们建议通过引擎选项而不是开关来配置 Chromium。

Google APIs

一些 Chromium 功能（如地理位置、拼写、语音等）使用 Google API。要访问这些 API，需要 API 密钥、OAuth 2.0 客户端 ID 和客户端密钥。要获取 API 密钥，请按照以下说明进行操作。

要提供 API 密钥、客户端 ID 和客户端密钥，请使用以下代码示例：

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

    

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

    

设置 API 密钥是可选的。但是，如果不这样做，某些使用 Google 服务的 API 将无法工作。

地理定位

地理定位是使用 Google API 的 Chromium 功能之一。您必须启用 Google Maps Geolocation API 和计费，否则 Geolocation API 将无法工作。启用 Google Maps Geolocation API 和计费后，您可以向 DotNetBrowser Chromium 引擎提供密钥。

要在 DotNetBrowser 中启用地理定位，请授予特定权限。

语音识别

语音识别是使用 Google API 的 Chromium 功能之一。您必须启用 Speech API 和 billing，否则语音识别功能无法正常工作。

启用语音 API 和计费后，您可以向 DotNetBrowser Chromium 引擎提供密钥。

引擎处理

IEngine 实例分配必须释放的内存和系统资源。当不再需要 IEngine 时，必须通过 IEngine.Dispose() 方法对其进行处理，以关闭本机 Chromium 进程并释放所有分配的内存和系统资源。请参阅以下示例：

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

    

      Dim engine As IEngine = EngineFactory.Create()
' ...
engine.Dispose()

    

任何使用已处理 IEngine 的尝试都将导致 ObjectDisposedException。

要检查 IEngine 是否已被处理，请使用以下代码示例中显示的 IsDisposed 属性：

      bool disposed = engine.IsDisposed;

    

      Dim disposed As Boolean = engine.IsDisposed

    

引擎事件

引擎处理

要在处理 IEngine 时获得通知，请使用以下代码示例中显示的 Disposed 事件：

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

    

      AddHandler engine.Disposed, Sub(s, e)
End Sub

引擎崩溃

要在 IEngine 由于 Chromium 引擎内部错误而意外崩溃时获得通知，请使用以下代码示例中显示的方法：

      engine.Disposed += (s, e) => 
{
    long exitCode = e.ExitCode;
    // 如果此退出代码不为零，则引擎已崩溃。
});

    

      AddHandler engine.Disposed, Sub(s, e)
    Dim exitCode As Long = e.ExitCode
    ' 如果此退出代码不为零，则引擎已崩溃。
End Sub)

    

Go Top