List icon 目录

引擎

本指南描述了如何创建、使用和关闭 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 会执行以下操作:

  1. 检查环境并确保它是受支持的
  2. 查找 Chromium 二进制文件并在必要时将它们提取到所需的目录
  3. 运行 Chromium 引擎的主进程
  4. 在 .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 请求。

并非所有方案都可以被拦截。 例如,无法拦截 chromedatachrome-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 126.0.6478.57 的 DotNetBrowser 2.27.2,则只能在相同的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())

禁用谷歌流量

此选项会禁用不必要的流量访问诸如 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计费,否则语音识别功能无法正常工作。

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