DocumentRequest Class
A request of a document, given to DocumentLoader.LoadAsync.
public sealed class DocumentRequestConstructors
| Name | Description |
|---|---|
| DocumentRequest(string) | Creates a request. |
DocumentRequest(string)
BrowsingContextOptions.csProperties
| Name | Description |
|---|---|
| Body | Gets the body of the request (https://fetch.spec.whatwg.org/#concept-request-body), e.g. the entry list of a submitted form, or null. |
| BodyContentType | Gets the Content-Type of the body of the request (e.g. application/x-www-form-urlencoded), or null when there is no body. |
| BrowsingContext | Gets the browsing context of the request: the browsing context that is navigated for a navigation request (DocumentRequest.Mode is RequestMode.Navigate), or the browsing context of the document that makes the request (its subresources, fetch()...). It is null for a request made by a worker, or by a document that has no browsing context. A loader can use it to attribute the requests to the frames of a page. |
| CookieJar | Gets the cookie store of the browsing context (BrowsingContextOptions.CookieJar), or null. Use DocumentRequest.GetCookieHeader and DocumentRequest.StoreCookies to send and store the cookies of the request. |
| Destination | Gets the destination of the request (https://fetch.spec.whatwg.org/#concept-request-destination): a document of a navigation, the script of a script element, or the style sheet of an @import rule. The default is RequestDestination.Document. |
| FollowRedirects | Gets whether the loader should follow the redirects. When false, the loader returns the redirect responses (e.g. a 302 status with a Location header), and the library follows them as specified (https://fetch.spec.whatwg.org/#http-redirect-fetch, https://html.spec.whatwg.org/multipage/browsing-the-web.html#create-navigation-params-by-fetching): this is the case of all the requests of the library, whose redirect mode and checks (CORS, mixed content, content security policies...) apply to each response. A loader that follows the redirects anyway should set DocumentResource.Url and DocumentResource.RedirectUrls: the library checks these URLs once the response is received. The default is true (a request created by the application). |
| Headers | Gets the headers of the request, in their order (https://fetch.spec.whatwg.org/#concept-request-header-list): the headers set by the script (fetch() and XMLHttpRequest), and the Accept, Content-Type, Content-Length, Origin, Referer, Fetch Metadata (Sec-Fetch-*), client hints (Sec-CH-*, see BrowsingContextOptions.ClientHints), Authorization and cache headers added by the fetch algorithm of the library (and the Ping-From and Ping-To headers of the hyperlink auditing requests, RequestDestination.Ping). The loader adds the headers of the connection (e.g. Host, Cookie). It is empty for a request created by the application, whose headers the loader determines from the other properties (e.g. DocumentRequest.Referrer and DocumentRequest.Destination). |
| IncludeCredentials | Gets whether the cookies of DocumentRequest.CookieJar are sent with the request, and the cookies of the response are stored (https://fetch.spec.whatwg.org/#http-network-or-cache-fetch, includeCredentials). It is false for a cross-origin request of fetch() or XMLHttpRequest without credentials. The default is true. |
| Initiator | Gets the element that initiated the request (e.g. the script element, or the style element of the style sheet that contains the @import rule), or null (e.g. a navigation). |
| Integrity | Gets the integrity metadata of the request (https://fetch.spec.whatwg.org/#concept-request-integrity-metadata), e.g. the integrity() modifier of a CSS url(), or the empty string. The library checks that the body of the response matches it (https://w3c.github.io/webappsec-subresource-integrity/#does-response-match-metadatalist). |
| InterimResponseHandler | Gets the callback that DocumentRequest.ReportInterimResponse calls with the status and the headers of each interim response, or null. The library sets it on the requests it sends. A loader that sends a request to another loader with a new DocumentRequest forwards the interim responses with InterimResponseHandler = request.ReportInterimResponse. |
| IsSpeculative | Gets whether the request is a speculative fetch of the HTML parser (see BrowsingContextOptions.SpeculativeParsing): the element that would fetch the resource is not parsed yet (DocumentRequest.Initiator is null), and the response is ignored. |
| IsSynchronous | Gets whether the request is synchronous (a synchronous XMLHttpRequest): the event loop is blocked until the loader completes, so the loader must not wait for a task of the DomEventLoop. |
| Method | Gets the method of the request (https://fetch.spec.whatwg.org/#concept-request-method): GET, or POST for the submission of a form with the POST method. |
| Mode | Gets the mode of the request (https://fetch.spec.whatwg.org/#concept-request-mode). A loader can send the Origin header of the CORS requests. |
| Origin | Gets the serialized origin of the document that initiated the request (https://fetch.spec.whatwg.org/#concept-request-origin), e.g. https://example.com, or null (the string) when the origin is opaque. It is null when the request is not initiated by a document (e.g. BrowsingContext.Navigate). A loader can use it to decide whether the resource is available to the initiator (e.g. to reject cross-origin requests). |
| RedirectUrls | Gets the URLs of the redirects that led to this request, in order (the URL list of the request without its URL, https://fetch.spec.whatwg.org/#concept-request-url-list), when the request is created for a redirect: a request is cross-site when one of them is cross-site. The default is empty. |
| Referrer | Gets the referrer of the request (https://fetch.spec.whatwg.org/#concept-request-referrer), as determined by DocumentRequest.ReferrerPolicy: the URL of the document that initiated the request, possibly reduced to its origin, or null for no referrer (e.g. BrowsingContext.Navigate). A loader can send it as the Referer header. |
| ReferrerPolicy | Gets the referrer policy of the request (https://w3c.github.io/webappsec-referrer-policy/#referrer-policy), e.g. strict-origin-when-cross-origin: the referrerpolicy attribute of the initiator, the Referrer-Policy header or the <meta name="referrer"> of the document, or the default policy. A loader that follows the redirects should use it to determine the referrer of the next request. |
| SiteForCookies | Gets the "site for cookies" of the document that initiated the request (https://httpwg.org/http-extensions/draft-ietf-httpbis-rfc6265bis.html#name-document-based-requests): the serialized top-level origin when the document and its ancestors are same-site with it, null (the string) when it is opaque (the request is cross-site), or null when the request has no client (e.g. BrowsingContext.Navigate). It determines which SameSite cookies are sent and stored. The site for cookies of a top-level navigation (RequestDestination.Document) is its URL. |
| StreamsResponseBody | Gets whether the body of the response is read as it arrives (e.g. the response of fetch(), whose body is a ReadableStream, or the resource of a media element): the loader should return the response once its headers are received, with the rest of its body in DocumentResource.RemainingContentBytes. A loader that returns the complete body is still supported. |
| TopLevelOrigin | Gets the serialized origin of the top-level document of the document that initiated the request, or null when the request has no client: its site is the partition key of the partitioned cookies (the Partitioned attribute). |
| Url | Gets the absolute URL of the document, serialized as specified by the WHATWG URL Standard. It keeps the fragment of the referenced URL (e.g. https://example.com/icons.svg#home for <use href="icons.svg#home">), which an HTTP request does not send: remove it to look up a resource by URL. |
| UserActivation | Gets whether the navigation is initiated with a user activation (https://fetch.spec.whatwg.org/#request-user-activation): the window of the initiator has transient activation. A loader can send the Sec-Fetch-User header (https://w3c.github.io/webappsec-fetch-metadata/#sec-fetch-user-header). |
Gets the body of the request (https://fetch.spec.whatwg.org/#concept-request-body), e.g. the entry list of a submitted form, or null.
public ReadOnlyMemory<byte>? Body { get; init; }Property value
BodyContentType
BrowsingContextOptions.csBrowsingContext
BrowsingContextOptions.csGets the browsing context of the request: the browsing context that is navigated for a navigation request (DocumentRequest.Mode is RequestMode.Navigate), or the browsing context of the document that makes the request (its subresources, fetch()...). It is null for a request made by a worker, or by a document that has no browsing context. A loader can use it to attribute the requests to the frames of a page.
public BrowsingContext? BrowsingContext { get; init; }Property value
CookieJar
BrowsingContextOptions.csGets the cookie store of the browsing context (BrowsingContextOptions.CookieJar), or null. Use DocumentRequest.GetCookieHeader and DocumentRequest.StoreCookies to send and store the cookies of the request.
public CookieJar? CookieJar { get; init; }Property value
Destination
BrowsingContextOptions.csGets the destination of the request (https://fetch.spec.whatwg.org/#concept-request-destination): a document of a navigation, the script of a script element, or the style sheet of an @import rule. The default is RequestDestination.Document.
public RequestDestination Destination { get; init; }Property value
FollowRedirects
BrowsingContextOptions.csGets whether the loader should follow the redirects. When false, the loader returns the redirect responses (e.g. a 302 status with a Location header), and the library follows them as specified (https://fetch.spec.whatwg.org/#http-redirect-fetch, https://html.spec.whatwg.org/multipage/browsing-the-web.html#create-navigation-params-by-fetching): this is the case of all the requests of the library, whose redirect mode and checks (CORS, mixed content, content security policies...) apply to each response. A loader that follows the redirects anyway should set DocumentResource.Url and DocumentResource.RedirectUrls: the library checks these URLs once the response is received. The default is true (a request created by the application).
public bool FollowRedirects { get; init; }Property value
Headers
BrowsingContextOptions.csGets the headers of the request, in their order (https://fetch.spec.whatwg.org/#concept-request-header-list): the headers set by the script (fetch() and XMLHttpRequest), and the Accept, Content-Type, Content-Length, Origin, Referer, Fetch Metadata (Sec-Fetch-*), client hints (Sec-CH-*, see BrowsingContextOptions.ClientHints), Authorization and cache headers added by the fetch algorithm of the library (and the Ping-From and Ping-To headers of the hyperlink auditing requests, RequestDestination.Ping). The loader adds the headers of the connection (e.g. Host, Cookie). It is empty for a request created by the application, whose headers the loader determines from the other properties (e.g. DocumentRequest.Referrer and DocumentRequest.Destination).
public IReadOnlyList<KeyValuePair<string, string>> Headers { get; init; }Property value
IncludeCredentials
BrowsingContextOptions.csGets whether the cookies of DocumentRequest.CookieJar are sent with the request, and the cookies of the response are stored (https://fetch.spec.whatwg.org/#http-network-or-cache-fetch, includeCredentials). It is false for a cross-origin request of fetch() or XMLHttpRequest without credentials. The default is true.
public bool IncludeCredentials { get; init; }Property value
Initiator
BrowsingContextOptions.csIntegrity
BrowsingContextOptions.csGets the integrity metadata of the request (https://fetch.spec.whatwg.org/#concept-request-integrity-metadata), e.g. the integrity() modifier of a CSS url(), or the empty string. The library checks that the body of the response matches it (https://w3c.github.io/webappsec-subresource-integrity/#does-response-match-metadatalist).
public string Integrity { get; init; }Property value
InterimResponseHandler
BrowsingContextOptions.csGets the callback that DocumentRequest.ReportInterimResponse calls with the status and the headers of each interim response, or null. The library sets it on the requests it sends. A loader that sends a request to another loader with a new DocumentRequest forwards the interim responses with InterimResponseHandler = request.ReportInterimResponse.
public Action<int, IReadOnlyList<KeyValuePair<string, string>>>? InterimResponseHandler { get; init; }IsSpeculative
BrowsingContextOptions.csGets whether the request is a speculative fetch of the HTML parser (see BrowsingContextOptions.SpeculativeParsing): the element that would fetch the resource is not parsed yet (DocumentRequest.Initiator is null), and the response is ignored.
public bool IsSpeculative { get; init; }Property value
IsSynchronous
BrowsingContextOptions.csGets whether the request is synchronous (a synchronous XMLHttpRequest): the event loop is blocked until the loader completes, so the loader must not wait for a task of the DomEventLoop.
public bool IsSynchronous { get; init; }Property value
Gets the mode of the request (https://fetch.spec.whatwg.org/#concept-request-mode). A loader can send the Origin header of the CORS requests.
public RequestMode Mode { get; init; }Property value
Gets the serialized origin of the document that initiated the request (https://fetch.spec.whatwg.org/#concept-request-origin), e.g. https://example.com, or null (the string) when the origin is opaque. It is null when the request is not initiated by a document (e.g. BrowsingContext.Navigate). A loader can use it to decide whether the resource is available to the initiator (e.g. to reject cross-origin requests).
public string? Origin { get; init; }Property value
RedirectUrls
BrowsingContextOptions.csGets the URLs of the redirects that led to this request, in order (the URL list of the request without its URL, https://fetch.spec.whatwg.org/#concept-request-url-list), when the request is created for a redirect: a request is cross-site when one of them is cross-site. The default is empty.
public IReadOnlyList<string> RedirectUrls { get; init; }Property value
Referrer
BrowsingContextOptions.csGets the referrer of the request (https://fetch.spec.whatwg.org/#concept-request-referrer), as determined by DocumentRequest.ReferrerPolicy: the URL of the document that initiated the request, possibly reduced to its origin, or null for no referrer (e.g. BrowsingContext.Navigate). A loader can send it as the Referer header.
public string? Referrer { get; init; }Property value
ReferrerPolicy
BrowsingContextOptions.csGets the referrer policy of the request (https://w3c.github.io/webappsec-referrer-policy/#referrer-policy), e.g. strict-origin-when-cross-origin: the referrerpolicy attribute of the initiator, the Referrer-Policy header or the <meta name="referrer"> of the document, or the default policy. A loader that follows the redirects should use it to determine the referrer of the next request.
public string ReferrerPolicy { get; init; }Property value
SiteForCookies
BrowsingContextOptions.csGets the "site for cookies" of the document that initiated the request (https://httpwg.org/http-extensions/draft-ietf-httpbis-rfc6265bis.html#name-document-based-requests): the serialized top-level origin when the document and its ancestors are same-site with it, null (the string) when it is opaque (the request is cross-site), or null when the request has no client (e.g. BrowsingContext.Navigate). It determines which SameSite cookies are sent and stored. The site for cookies of a top-level navigation (RequestDestination.Document) is its URL.
public string? SiteForCookies { get; init; }Property value
StreamsResponseBody
BrowsingContextOptions.csGets whether the body of the response is read as it arrives (e.g. the response of fetch(), whose body is a ReadableStream, or the resource of a media element): the loader should return the response once its headers are received, with the rest of its body in DocumentResource.RemainingContentBytes. A loader that returns the complete body is still supported.
public bool StreamsResponseBody { get; init; }Property value
TopLevelOrigin
BrowsingContextOptions.csGets the absolute URL of the document, serialized as specified by the WHATWG URL Standard. It keeps the fragment of the referenced URL (e.g. https://example.com/icons.svg#home for <use href="icons.svg#home">), which an HTTP request does not send: remove it to look up a resource by URL.
public string Url { get; }Property value
UserActivation
BrowsingContextOptions.csGets whether the navigation is initiated with a user activation (https://fetch.spec.whatwg.org/#request-user-activation): the window of the initiator has transient activation. A loader can send the Sec-Fetch-User header (https://w3c.github.io/webappsec-fetch-metadata/#sec-fetch-user-header).
public bool UserActivation { get; init; }Property value
Methods
| Name | Description |
|---|---|
| GetCookieHeader(string?, IReadOnlyList<string>?) | Returns the value of the Cookie header of the request (the cookies of DocumentRequest.CookieJar for DocumentRequest.Url, https://httpwg.org/http-extensions/draft-ietf-httpbis-rfc6265bis.html#name-the-cookie-header-field), or null when no cookie is sent (e.g. DocumentRequest.IncludeCredentials is false). The value is an isomorphic string (each character is a byte). |
| ReportInterimResponse(int, IReadOnlyList<KeyValuePair<string, string>>) | Reports an interim response (https://fetch.spec.whatwg.org/#concept-response-status, an informational 1xx status other than 101) received before the final response, e.g. a 100 Continue or a 103 Early Hints response. The loader calls it, from any thread, before it returns the final response of the request. The time of the first interim response is the firstInterimResponseStart of the resource timing entry, and the Link headers of the first 103 response of the navigation of a top-level browsing context preload their resources (https://html.spec.whatwg.org/multipage/semantics.html#early-hints), which the new document uses. An interim response whose header is not valid makes the request a network error. A loader that does not report the interim responses is still supported (HttpClient does not expose them). |
| StoreCookies(IEnumerable<string>, string?, IReadOnlyList<string>?) | Stores the cookies of the Set-Cookie headers of the response of the request in DocumentRequest.CookieJar (https://httpwg.org/http-extensions/draft-ietf-httpbis-rfc6265bis.html#name-the-set-cookie-header-field), unless DocumentRequest.IncludeCredentials is false. |
GetCookieHeader(string?, IReadOnlyList<string>?)
BrowsingContextOptions.csReturns the value of the Cookie header of the request (the cookies of DocumentRequest.CookieJar for DocumentRequest.Url, https://httpwg.org/http-extensions/draft-ietf-httpbis-rfc6265bis.html#name-the-cookie-header-field), or null when no cookie is sent (e.g. DocumentRequest.IncludeCredentials is false). The value is an isomorphic string (each character is a byte).
public string? GetCookieHeader(string? url = null, IReadOnlyList<string>? redirectUrls = null)Parameters
urlstring?- The URL of the request, or of a redirect followed by the loader (null for
DocumentRequest.Url). redirectUrlsIReadOnlyList<string>?- The URLs of the redirects that led to
url(null forDocumentRequest.RedirectUrls).
Returns
ReportInterimResponse(int, IReadOnlyList<KeyValuePair<string, string>>)
BrowsingContextOptions.csReports an interim response (https://fetch.spec.whatwg.org/#concept-response-status, an informational 1xx status other than 101) received before the final response, e.g. a 100 Continue or a 103 Early Hints response. The loader calls it, from any thread, before it returns the final response of the request. The time of the first interim response is the firstInterimResponseStart of the resource timing entry, and the Link headers of the first 103 response of the navigation of a top-level browsing context preload their resources (https://html.spec.whatwg.org/multipage/semantics.html#early-hints), which the new document uses. An interim response whose header is not valid makes the request a network error. A loader that does not report the interim responses is still supported (HttpClient does not expose them).
public void ReportInterimResponse(int statusCode, IReadOnlyList<KeyValuePair<string, string>> headers)Parameters
statusCodeint- The status of the interim response, between 100 and 199 (except 101).
headersIReadOnlyList<KeyValuePair<string, string>>- The headers of the interim response, as byte strings.
Exceptions
ArgumentOutOfRangeExceptionstatusCodeis not the status of an interim response.
StoreCookies(IEnumerable<string>, string?, IReadOnlyList<string>?)
BrowsingContextOptions.csStores the cookies of the Set-Cookie headers of the response of the request in DocumentRequest.CookieJar (https://httpwg.org/http-extensions/draft-ietf-httpbis-rfc6265bis.html#name-the-set-cookie-header-field), unless DocumentRequest.IncludeCredentials is false.
public void StoreCookies(IEnumerable<string> setCookieHeaders, string? url = null, IReadOnlyList<string>? redirectUrls = null)Parameters
setCookieHeadersIEnumerable<string>- The values of the
Set-Cookieheaders (isomorphic strings: each character is a byte). urlstring?- The URL of the response: the URL of the request, or of a redirect followed by the loader (null for
DocumentRequest.Url). redirectUrlsIReadOnlyList<string>?- The URLs of the redirects that led to
url(null forDocumentRequest.RedirectUrls).