指南

介绍

安装

指南

故障排除

迁移

引擎

本指南描述了如何创建、使用和关闭 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 构建器将抛出相应的异常。例如：”无法拦截 “file” 方案。”

用户代理

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

      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 等。请参阅下面的示例：

远程调试端口

请勿在 Mozilla Firefox、Microsoft Internet Explorer、Safari、Opera 等其他网络浏览器应用程序中打开远程调试 URL，否则可能会导致 Chromium DevTools 网络服务器本机崩溃。

远程调试功能仅与 DotNetBrowser 库使用的 Chromium 版本兼容。例如，如果您使用的是基于 Chromium 131.0.6778.70 的 DotNetBrowser 3.0.0，则只能在相同的Chromium/Google Chrome 中打开远程调试URL。如果使用以前的 DotNetBrowser 版本，则需要 [下载相应的 Chromium 版本]（/dotnetbrowser/zh/docs/guides/troubleshoot/unexpected-behavior.html）。

我们建议在 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())

    

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 和计费，否则语音识别功能无法正常工作。

启用语音 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