网络
本指南展示了如何使用与网络相关的功能,例如代理、网络事件、身份验证、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