Network

This guide shows how to work with the network-related functionality such as proxy, network events, authentication, TLS, client certificate authentication, etc.

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";

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.

HTTP Server Authorization Whitelist

See the code sample below:

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";

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.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();
    });

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: Network Events Flow

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>");
    });

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>");
    });

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 the text/plain content type;
  • FormData - the data of the application/x-www-form-urlencoded content type;
  • MultipartFormData - the data of the multipart/form-data content type.

Before Start Transaction

The StartTransactionHandler handler is invoked before the network transaction starts. It allows you to add or override the HTTP headers before they are sent. 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);
    });

Before Send Headers

The SendHeadersHandler handler is invoked when a URL request is about to occur and the initial HTTP headers are prepared. You can add, modify, and delete the HTTP request headers before they are sent to a web server. See the code sample below:

network.SendHeadersHandler =
    new Handler<SendHeadersParameters, SendHeadersResponse>((parameters) =>
    {
        IEnumerable<IHttpHeader> headers = parameters.Headers;
        List<HttpHeader> newHttpHeaders = headers.Cast<HttpHeader>().ToList();
        newHttpHeaders.Add(new HttpHeader("<header-name>", "<header-value>"));
        return SendHeadersResponse.OverrideHeaders(newHttpHeaders);
    });

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.

Before Send Proxy Headers

The SendProxyHeadersHandler handler is invoked when a URL request is about to occur and the initial HTTP headers have been prepared through the proxy connection. You can add, modify, and delete the HTTP request headers before they are sent to a web server. See the code sample below:

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

Intercept Request

The InterceptRequestHandler handler is invoked when a URL request is about to be sent out. You can use this handler to intercept the request and override the response data as it was sent from a web server. See the code sample below:

network.InterceptRequestHandler =
    new Handler<InterceptRequestParameters, InterceptRequestResponse>(p =>
    {
        UrlRequestJobOptions options = new UrlRequestJobOptions
        {
            Headers = new List<HttpHeader>
            {
                new HttpHeader("Content-Type", "text/html", "charset=utf-8"),
            }
        };
        UrlRequestJob job = network.CreateUrlRequestJob(p.UrlRequest, options);

        Task.Run(() =>
        {
            // The request processing is performed in a background thread
            // in order to avoid freezing the web page.
            job.Write(Encoding.UTF8.GetBytes("My data"));
            job.Complete();
        });
        
        return InterceptRequestResponse.Intercept(job);
    });

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);
    });

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;
};

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;
};

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;
    // Indicates whether request has been started.
    bool started = e.IsStarted;
    // The details of the URL request state.
    RequestStatus urlRequestStatus = e.Status;
    // The HTTP response code.
    int responseCode = e.ResponseCode;
};

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;
};

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;
};

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;
};
Go Top