网络

本指南展示了如何使用与网络相关的功能，例如代理、网络事件、身份验证、TLS、客户端证书验证等。

网络相关功能可通过 INetwork 实例访问，该实例可使用 Profile.Network 属性获取。 使用 IEngine.Network 属性将获得与默认 Profile 相关联的 Network 实例。

接受语言

DotNetBrowser 允许使用 INetwork.AcceptLanguage 属性配置 Accept-Language。 输入参数值表示 Accept-Language HTTP 标头的值。

例如，”fr, en-gb;q=0.8, en;q=0.7” 的值表示：”I prefer French, but will accept British English, and other types of English”：

network.AcceptLanguage = "fr, en-gb;q=0.8, en;q=0.7";

network.AcceptLanguage = "fr, en-gb;q=0.8, en;q=0.7"

服务器白名单

自 DotNetBrowser 1.9 起，您可以配置 HTTP 服务器授权白名单，该白名单由逗号/分号分隔的 URL 列表字符串表示。 此功能允许您对列出的域使用集成 Windows 身份验证 (IWA) 和 Kerberos 身份验证。

有了 IWA，Chromium 甚至无需提示用户输入用户名或密码，就能验证用户的网络服务器或代理服务器身份。 它通过使用缓存的凭据来做到这一点，而这些凭据是在用户首次登录浏览器运行的机器时建立的。 IWA 仅支持 Negotiate 和 NTLM 质询。

ServerWhiteList（服务器白名单）指定哪些服务器应列入集成身份验证的白名单。 默认情况下，仅当存在来自此允许列表中的代理或服务器的身份验证质询时，才会启用集成身份验证。 如果未设置此列表，Chromium引擎将尝试检测服务器是否位于 Intranet 上，并且仅针对 Intranet 服务器响应 IWA 请求。 如果服务器被检测为 Internet，则来自该服务器的 IWA 请求将被忽略。

DelegateWhiteList（委托白名单）指定 Chromium 可以委托的服务器。 如果未设置此列表，即使服务器被检测为 Intranet，Chromium 也不会委托用户凭据。

如果在列表中指定多个服务器名称，请用逗号分隔它们。 允许使用通配符 (*)。

自 Chromium 81 起，集成身份验证在隐身模式下被禁用。 在这种情况下，”AuthenticateHandler”处理程序将被调用以提供用户名和密码。 自 DotNetBrowser 2.23.3 起，可以覆盖此行为。 为此，有必要添加 --ambient-authentication-in-private-modes-enabled 的 Chromium 开关，以覆盖 AmbientAuthenticationInPrivateModesEnabled 策略。

HTTP 服务器授权白名单

请参阅以下代码示例：

network.HttpAuthPreferences.ServerWhiteList = "*google.com,*example.com,*baz";

network.HttpAuthPreferences.ServerWhiteList = "*google.com,*example.com,*baz"

HTTP 网络委托白名单

请参阅以下代码示例：

network.HttpAuthPreferences.DelegateWhiteList = "*google.com,*example.com,*baz";

network.HttpAuthPreferences.DelegateWhiteList = "*google.com,*example.com,*baz"

TLS

证书验证

默认情况下，Chromium 会在网页加载过程中验证从网络服务器获取的所有 SSL 证书。 DotNetBrowser 允许修改此默认行为并控制验证过程。

要处理证书验证，请使用 VerifyCertificateHandler 处理程序。 在它被调用之前，Chromium 验证 SSL 证书并将验证结果提供给处理程序。 处理程序会收到 SSL 证书本身以及验证结果。 您可以验证给定的 SSL 证书并通知引擎是否接受它。 请参阅以下代码示例：

engine.Profiles.Default.Network.VerifyCertificateHandler
    = new Handler<VerifyCertificateParameters, VerifyCertificateResponse>(p =>
    {
        // 需要验证的SSL证书。
        Certificate certificate = p.Certificate;
        // 默认验证器执行的验证结果。
        IEnumerable<CertificateVerificationStatus> certificateStatuses =
            p.VerifyStatuses;
        // 应使用默认验证的结果。
        return VerifyCertificateResponse.Default();
    });

engine.Profiles.Default.Network.VerifyCertificateHandler = 
    New Handler(Of VerifyCertificateParameters, VerifyCertificateResponse)(Function(p)
        ' 需要验证的 SSL 证书。
        Dim certificate As Certificate = p.Certificate
        ' 默认验证器执行的验证结果。
        Dim certificateStatuses As IEnumerable(Of CertificateVerificationStatus) = 
            p.VerifyStatuses
        ' 应使用默认验证的结果。
        Return VerifyCertificateResponse.Default()
    End Function)

客户端证书验证

DotNetBrowser 支持使用 HTTPS 客户端证书进行身份验证。 有关详细信息，请参阅身份验证指南。

网络事件和处理程序

INetwork API 定义了遵循网络请求生命周期的一组事件和处理程序。 您可以使用这些事件观察和分析流量。 通过这些处理程序，您可以拦截、阻止或修改请求。

成功请求的事件生命周期如下所示：

在 URL 请求前

当即将发生 HTTP 请求时，会调用 SendUrlRequestHandler 处理程序。 您可以使用此处理程序覆盖 URL 并将请求重定向到另一个位置。 例如：

network.SendUrlRequestHandler =
    new Handler<SendUrlRequestParameters, SendUrlRequestResponse>(p =>
    {
        return SendUrlRequestResponse.Override("<new-url>");
    });

network.SendUrlRequestHandler = 
    New Handler(Of SendUrlRequestParameters, SendUrlRequestResponse)(Function(p)
        Return SendUrlRequestResponse.Override("<new-url>")
    End Function)

发送上传数据之前

在将上传数据发送到网络服务器之前，会调用 SendUploadDataHandler 处理程序。 您可以在此覆盖上传数据。 例如：

network.SendUploadDataHandler =
    new Handler<SendUploadDataParameters, SendUploadDataResponse>(p =>
    {
        return SendUploadDataResponse.Override("<text-data>");
    });

network.SendUploadDataHandler = 
    New Handler(Of SendUploadDataParameters, SendUploadDataResponse)(Function(p)
        Return SendUploadDataResponse.Override("<text-data>")
    End Function)

如果请求中没有上传数据，则不会调用此处理程序。

支持以下上传数据类型：

• byte[] 代表字节序列；
• string - text/plain 内容类型的数据；
• FormData - application/x-www-form-urlencoded 内容类型的数据；
• MultipartFormData - multipart/form-data 内容类型的数据。

开始事务之前

StartTransactionHandler 处理程序在网络事务开始之前被调用。 您可以在 HTTP 请求头发送到网络服务器之前对其进行添加、修改和删除。 请参阅以下代码示例：

network.StartTransactionHandler
    = new Handler<StartTransactionParameters, StartTransactionResponse>(p =>
    {
        IEnumerable<IHttpHeader> headers = p.Headers;
        List<HttpHeader> newHttpHeaders = headers.Cast<HttpHeader>().ToList();
        newHttpHeaders.Add(new HttpHeader("<header-name>", "<header-value>"));
        return StartTransactionResponse.OverrideHeaders(newHttpHeaders);
    });

network.StartTransactionHandler = 
    New Handler(Of StartTransactionParameters, StartTransactionResponse)(Function(p)
        Dim headers As IEnumerable(Of IHttpHeader) = p.Headers
        Dim newHttpHeaders As List(Of HttpHeader) = 
            headers.Cast(Of HttpHeader)().ToList()
        newHttpHeaders.Add(New HttpHeader("<header-name>", "<header-value>"))
        Return StartTransactionResponse.OverrideHeaders(newHttpHeaders)
    End Function)

以下标头尚未提供给处理程序:

- Authorization
- Cache-Control
- Connection
- Content-Length
- Host
- If-Modified-Since
- If-None-Match
- If-Range
- Partial-Data
- Pragma
- Proxy-Authorization
- Proxy-Connection
- Transfer-Encoding
请注意，我们不保证此列表的完整性和稳定性。

接收标头

ReceiveHeadersHandler处理程序在接收到 HTTP 请求的标头后被调用。 您可以在此处添加、修改或删除通过网络接收到的 HTTP 标头。 请参阅以下代码示例：

network.ReceiveHeadersHandler =
    new Handler<ReceiveHeadersParameters, ReceiveHeadersResponse>(p =>
    {
        IEnumerable<IHttpHeader> headers = p.Headers;
        List<HttpHeader> newHttpHeaders = headers.Cast<HttpHeader>().ToList();
        newHttpHeaders.Add(new HttpHeader("<header-name>", "<header-value>"));
        return ReceiveHeadersResponse.OverrideHeaders(newHttpHeaders);
    });

network.ReceiveHeadersHandler = 
    New Handler(Of ReceiveHeadersParameters, ReceiveHeadersResponse)(Function(p)
        Dim headers As IEnumerable(Of IHttpHeader) = p.Headers
        Dim newHttpHeaders As List(Of HttpHeader) = 
            headers.Cast(Of HttpHeader)().ToList()
        newHttpHeaders.Add(New HttpHeader("<header-name>", "<header-value>"))
        Return ReceiveHeadersResponse.OverrideHeaders(newHttpHeaders)
    End Function)

收到重定向响应代码

当请求收到重定向响应码3xx时，将触发RedirectResponseCodeReceived事件。 您可以获得重定向的详细信息，如新的 URL 和响应代码。 请参阅以下代码示例：

network.RedirectResponseCodeReceived += (s, e) => 
{
    string newUrl = e.NewUrl;
    int responseCode = e.ResponseCode;
};

AddHandler network.RedirectResponseCodeReceived, Sub(s, e)
    Dim newUrl As String = e.NewUrl
    Dim responseCode As Integer = e.ResponseCode
End Sub

响应开始

当收到 URL 响应主体的第一个字节时，会触发 ResponseStarted 事件。 对于 HTTP 请求，这意味着状态行和响应标头可用。 在此事件中，您可以访问相应的请求和响应代码。 请参阅以下代码示例：

network.ResponseStarted += (s, e) => 
{
    UrlRequest urlRequest = e.UrlRequest;
    int responseCode = e.ResponseCode;
};

AddHandler network.ResponseStarted, Sub(s, e)
    Dim urlRequest As UrlRequest = e.UrlRequest
    Dim responseCode As Integer = e.ResponseCode
End Sub

请求完成

当 URL 请求成功完成或失败时, 会触发 RequestCompleted 事件。 您可以检查请求是否已启动，获取请求状态的详细信息并访问响应代码。 请参阅以下代码示例：

network.RequestCompleted += (s, e) => 
{
    UrlRequest urlRequest = e.UrlRequest;
    // URL 请求状态的详细信息。
    RequestStatus urlRequestStatus = e.Status;
    // HTTP 响应代码。
    int responseCode = e.ResponseCode;
};

AddHandler network.RequestCompleted, Sub(s, e)
    Dim urlRequest As UrlRequest = e.UrlRequest
    ' URL 请求状态的详细信息。
    Dim urlRequestStatus As RequestStatus = e.Status
    ' HTTP 响应代码。
    Dim responseCode As Integer = e.ResponseCode
End Sub

请求已销毁

当请求被销毁且无法再使用时，将触发 RequestDestroyed 事件。 要访问已销毁请求的详细信息，请使用以下代码：

network.RequestDestroyed += (s, e) => 
{
    UrlRequest urlRequest = e.UrlRequest;
};

AddHandler network.RequestDestroyed, Sub(s, e)
    Dim urlRequest As UrlRequest = e.UrlRequest
End Sub

收到的响应字节

当通过网络收到HTTP响应体的一部分时，将触发 ResponseBytesReceived 事件。 它允许访问 HTTP 响应主体的字节：

network.ResponseBytesReceived += (s, e) => 
{
    byte[] data = e.Data;
};

AddHandler network.ResponseBytesReceived, Sub(s, e)
    Dim data() As Byte = e.Data
End Sub

PAC 脚本错误

当 PAC 脚本中出现错误时，将触发 PacScriptErrorOccurred 事件。 它允许获取错误的详细信息：

network.PacScriptErrorOccurred += (s, e) =>
{
    string errorText = e.ErrorText;
    uint lineNumber = e.LineNumber;
};

AddHandler network.PacScriptErrorOccurred, Sub(s, e)
    Dim errorText As String = e.ErrorText
    Dim lineNumber As UInteger = e.LineNumber
End Sub

连接状态

Chromium 会在内部跟踪互联网连接状态。 当互联网连接中断后又恢复时，Chromium 会检测到这一点，并以编程方式重新加载当前加载的网页。 使用此 API，您可以在网络连接状态发生变化时收到通知：

profile.Network.ConnectionTypeChanged += (s, e) =>
{
    ConnectionType connectionType = e.ConnectionType;
};

AddHandler profile.Network.ConnectionTypeChanged, Sub(s, e)
    Dim connectionType As ConnectionType = e.ConnectionType
End Sub