Introduction
Installation
Guides
- Engine
- Profile
- Browser
- BrowserView
- Navigation
- Content
- Context menu
- DOM
- JavaScript
- Pop-ups
- Dialogs
- Downloads
- Chrome extensions
- Network
- Cache
- Cookies
- Proxy
- Authentication
- Permissions
- Plugins
- Printing
- Passwords
- User data profiles
- Credit cards
- Media
- Zoom
- Spell checker
- Deployment
- Chromium
Troubleshooting
- Logging
- Common exceptions
- Application does not terminate
- Video does not play
- Cannot sign in to Google account
- User data is not stored
- Color scheme
- Startup failure
- Slow startup on Windows
- Unresponsive .NET Application
- Unexpected Chromium process termination
- Unexpected behavior
- Windows 7/8/8.1 end of support
Migration
Network
This guide shows how to work with the network-related functionality such as proxy, network events, authentication, TLS, client certificate authentication, etc.
The network-related functionality can be accessed through the INetwork
instance that can be obtained using the Profile.Network
property. Using IEngine.Network
property you will get the Network
instance associated with the default Profile
.
Accept language
DotNetBrowser allows configuring the Accept-Language
using the INetwork.AcceptLanguage
property. The input parameter value represents the Accept-Language
HTTP header value.
For example, the “fr, en-gb;q=0.8, en;q=0.7” value would mean: “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"
ServerWhiteList
Since DotNetBrowser 1.9, you can configure HTTP server authorization whitelist that represents a string with comma/semicolon separated list of URLs. This feature allows you to use Integrated Windows authentication (IWA) and Kerberos authentication for the listed domains.
With IWA, Chromium can authenticate the user to a web server or proxy without even prompting the user for a username or password. It does this by using cached credentials which are established when the user initially logs in to the machine that the browser is running on. IWA is supported for Negotiate and NTLM challenges only.
ServerWhiteList
specifies which servers should be whitelisted for integrated authentication. By default, integrated authentication is only enabled when there is an authentication challenge from a proxy or from a server which is in this permitted list. If this list is not set, Chromium engine tries to detect if a server is on the Intranet and responds to IWA requests only for Intranet servers. If a server is detected as Internet, then IWA requests from this server are ignored.
DelegateWhiteList
specifies the servers that Chromium may delegate to. If this list is not set, Chromium does not delegate user credentials even if a server is detected as Intranet.
If you specify multiple server names in the list, separate them with commas. Wildcards (*) are allowed.
Since Chromium 81 integrated authentication is disabled for Incognito mode. In this case, the AuthenticateHandler
handler will be invoked to supply username and password. Since DotNetBrowser 2.23.3 it is possible to override this behavior. For this purpose, it is necessary to add the --ambient-authentication-in-private-modes-enabled
Chromium switch to override the AmbientAuthenticationInPrivateModesEnabled policy.
HTTP server authorization whitelist
See the code sample below:
network.HttpAuthPreferences.ServerWhiteList = "*google.com,*example.com,*baz";
network.HttpAuthPreferences.ServerWhiteList = "*google.com,*example.com,*baz"
HTTP network delegate whitelist
See the code sample below:
network.HttpAuthPreferences.DelegateWhiteList = "*google.com,*example.com,*baz";
network.HttpAuthPreferences.DelegateWhiteList = "*google.com,*example.com,*baz"
TLS
Certificate verification
By default, Chromium verifies all SSL certificates obtained from a web server during the web page loading. DotNetBrowser allows modifying this default behavior and take control over the verification process.
To handle certificate verification, use the VerifyCertificateHandler
handler. Before it is invoked, Chromium verifies SSL certificate and provides the results of the verification to the handler. The handler receives the SSL certificate itself together with the verification results. You can verify the given SSL certificate and notify the engine whether to accept it or not. See the code sample below:
engine.Profiles.Default.Network.VerifyCertificateHandler
= new Handler<VerifyCertificateParameters, VerifyCertificateResponse>(p =>
{
// SSL Certificate to verify.
Certificate certificate = p.Certificate;
// The results of the verification performed by default verifier.
IEnumerable<CertificateVerificationStatus> certificateStatuses =
p.VerifyStatuses;
// The results of default verification should be used.
return VerifyCertificateResponse.Default();
});
engine.Profiles.Default.Network.VerifyCertificateHandler =
New Handler(Of VerifyCertificateParameters, VerifyCertificateResponse)(Function(p)
' SSL Certificate to verify.
Dim certificate As Certificate = p.Certificate
' The results of the verification performed by default verifier.
Dim certificateStatuses As IEnumerable(Of CertificateVerificationStatus) =
p.VerifyStatuses
' The results of default verification should be used.
Return VerifyCertificateResponse.Default()
End Function)
Client certificate authentication
DotNetBrowser supports authentication using HTTPS client certificates. Refer to the Authentication guide for details.
Network events & handlers
The INetwork
API defines a set of events and handlers that follow the life cycle of a web request. You can use these events to observe and analyze traffic. These handlers will allow you to intercept, block, or modify requests.
The event life cycle of successful requests looks as follows:
Before URL request
The SendUrlRequestHandler
handler is invoked when an HTTP request is about to occur. You can use this handler to override the URL and redirect the request to another location. For example:
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)
Before send upload data
The SendUploadDataHandler
handler is invoked before the upload data is sent to a web server. Here you can override the upload data. For example:
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)
This handler will not be called if the request does not have the upload data.
The following upload data types are supported:
byte[]
represents a sequence of bytes;string
- the data of thetext/plain
content type;FormData
- the data of theapplication/x-www-form-urlencoded
content type;MultipartFormData
- the data of themultipart/form-data
content type.
Before start transaction
The StartTransactionHandler
handler is invoked before the network transaction starts. You can add, modify, and delete the HTTP request headers before they are sent to a web server. See the code sample below:
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)
The following headers are currently not provided to the handler:
- Authorization
- Cache-Control
- Connection
- Content-Length
- Host
- If-Modified-Since
- If-None-Match
- If-Range
- Partial-Data
- Pragma
- Proxy-Authorization
- Proxy-Connection
- Transfer-Encoding
Note that we do not guarantee that this list is complete or stable.
Receive headers
The ReceiveHeadersHandler
handler is invoked for HTTP requests when the headers have been received. Here you can add, modify, or remove the HTTP headers received over the network. See the code sample below:
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)
Redirect response code received
The RedirectResponseCodeReceived
event occurs when a redirect response code 3xx
has been received for the request. You can get the details about the redirect such as new URL and response code. See the code sample below:
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
Response started
The ResponseStarted
event occurs when the first byte of the URL response body has been received. For HTTP requests, it means that the status line and the response headers are available. In this event, you can access the corresponding request and the response code. See the code sample below:
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
Request completed
The RequestCompleted
event occurs when the URL request has been successfully completed or failed. You can check whether the request has been started at all, get the details of the request state, and access the response code. See the code sample below:
network.RequestCompleted += (s, e) =>
{
UrlRequest urlRequest = e.UrlRequest;
// The details of the URL request state.
RequestStatus urlRequestStatus = e.Status;
// The HTTP response code.
int responseCode = e.ResponseCode;
};
AddHandler network.RequestCompleted, Sub(s, e)
Dim urlRequest As UrlRequest = e.UrlRequest
' The details of the URL request state.
Dim urlRequestStatus As RequestStatus = e.Status
' The HTTP response code.
Dim responseCode As Integer = e.ResponseCode
End Sub
Request destroyed
The RequestDestroyed
event occurs when the request has been destroyed and it cannot be used anymore. To access the details of the destroyed request, use the following code:
network.RequestDestroyed += (s, e) =>
{
UrlRequest urlRequest = e.UrlRequest;
};
AddHandler network.RequestDestroyed, Sub(s, e)
Dim urlRequest As UrlRequest = e.UrlRequest
End Sub
Response bytes received
The ResponseBytesReceived
event occurs when a part of HTTP response body is received over
the network. It allows accessing the bytes of the HTTP response body:
network.ResponseBytesReceived += (s, e) =>
{
byte[] data = e.Data;
};
AddHandler network.ResponseBytesReceived, Sub(s, e)
Dim data() As Byte = e.Data
End Sub
PAC script error
The PacScriptErrorOccurred
event occurs when there is an error in the PAC script. It allows obtaining the error details:
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
Connection state
Chromium internally tracks the Internet connection status. When the Internet connection is dropped and then restored, Chromium detects this and programmatically reloads the currently loaded web page. You can get notifications when the network connection state is changed using this 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