Base Types

Assembly

Library

Summary

Description

WebRequest is an abstract
class that models
the request side of transactions used for accessing data from the
Internet.

Classes that derive from WebRequest are required to override the following members
of the WebRequest class in a
protocol-specific manner:

System.Net.WebRequest.Method
-- Gets or sets the protocol method to use in the current instance.

System.Net.WebRequest.RequestUri --
Gets the Uri of the resource associated with the current instance.

System.Net.WebRequest.Headers
-- Gets or sets the collection of header name/value pairs associated with the
request.

System.Net.WebRequest.ContentLength -- Gets or sets the content length of
the request data being sent.

System.Net.WebRequest.ContentType -- Gets or sets the content type of the
request data being sent.

System.Net.WebRequest.Credentials -- Gets or sets the credentials used
for authenticating the client using the current instance.

System.Net.WebRequest.PreAuthenticate -- Gets or
sets a value that indicates whether to send authentication information with a
request for resources.

System.Net.WebRequest.GetRequestStream -- Returns a Stream for writing data to a
resource.

System.Net.WebRequest.BeginGetRequestStream(System.AsyncCallback,System.Object) -- Begins
an asynchronous request for a stream in which to write data to be sent in the
current request.

System.Net.WebRequest.EndGetRequestStream(System.IAsyncResult) -- Returns
a Stream for writing data to the
resource accessed by the current instance.

System.Net.WebRequest.GetResponse -- Returns a response to a request.

System.Net.WebRequest.BeginGetResponse(System.AsyncCallback,System.Object) -- Begins
an asynchronous request for a resource.

System.Net.WebRequest.EndGetResponse(System.IAsyncResult) -- Returns a WebResponse that
contains a response to a specified pending request.

In addition, derived classes are required to
support the IWebRequestCreate interface.

[Note: An application
that uses the request/response model can request data be
sent from the Internet in a protocol-agnostic manner, in which the application works with
instances of the WebRequest class while classes that derive from WebRequest and
implement
specific protocols perform the details of
the request.

Requests are sent from an application to a particular Uniform Resource Identifier (URI), such as
a Web page on a server. Using the URI, the System.Net.WebRequest.Create(System.Uri,System.Boolean) method creates an instance of a type
derived from WebRequest to handle the request. The type is selected from the
set of registered types. Types can be registered to handle a specific
protocol, such as HTTP or FTP, or to handle a request to a specific server or
path on a server. [Note: For information on registering types, see System.Net.WebRequest.RegisterPrefix(System.String,System.Net.IWebRequestCreate).]

Return Value

Exceptions

Description

The state parameter can be any object that the
caller wishes to have available for the duration of the asynchronous operation.
This object is available via the System.IAsyncResult.AsyncState property of the object returned by this
method.

[Behaviors: This method starts an asynchronous operation to obtain a stream
used to write data to be sent in the current request. To get the request
stream, call the System.Net.WebRequest.EndGetRequestStream(System.IAsyncResult) method and specify the IAsyncResult object
returned by this method.

If the callback parameter is not
null
, the
method referenced by callback is invoked when the asynchronous
operation completes. The IAsyncResult object returned by this method is passed as the argument
to the method referenced by callback.

[Overrides: This method must be overridden by classes that inherit from
WebRequest to provide this
functionality. ]

[Usage: Use this method to
start an asynchronous request for a stream used to send data to a resource. The
callback delegate
can call
the System.Net.WebRequest.EndGetRequestStream(System.IAsyncResult) method to
obtain the request stream. ]

Return Value

Exceptions

Description

The state parameter can be any object that the caller wishes to have
available for the duration of the asynchronous operation. This object is
available via the System.IAsyncResult.AsyncState property of the object returned by this
method.

[Behaviors: This method starts an asynchronous operation to send the current request and
receive the response from the server that processed the
request. To get the response, call the System.Net.WebRequest.EndGetResponse(System.IAsyncResult) method and specify the IAsyncResult object
returned by this method.

If the callback parameter is not null
, the method
referenced by callback is invoked when the asynchronous operation
completes. The IAsyncResult object returned by this method is passed as the argument
to the method referenced by callback.

[Overrides: This method must be overridden by
classes that inherit from WebRequest to provide this functionality.
]

[Usage: The System.Net.WebRequest.BeginGetResponse(System.AsyncCallback,System.Object) method starts an asynchronous request for
a response. The callback delegate
can call the System.Net.WebRequest.EndGetResponse(System.IAsyncResult) method to return the WebResponse received from the resource.]

The caller does not have permission to connect to the requested URI or a URI that the request is redirected to.

Description

[Note: This method
returns a new instance of a class that derived from
WebRequest . The Type of this new instance
is determined at run time by the scheme of the URI in
requestUriString. For example,
when a URI beginning with http:// is passed in
requestUriString, a HttpWebRequest instance is returned.

Classes that derive from WebRequest that are
created to handle other requests are registered
with the System.Net.WebRequest.RegisterPrefix(System.String,System.Net.IWebRequestCreate)
method.

Exceptions

The caller does not have permission to connect to the requested URI or a URI that the request is redirected to.

Description

[Note: When this method is
invoked, only the scheme portion of requestUri is checked against the
list of URIs registered for the current instance. Conversely, when System.Net.WebRequest.Create(System.Uri,System.Boolean)
is invoked, the entire URI is checked against the
list of registered URIs.
]

Example

This example demonstrates the use of the System.Net.WebRequest.Create(System.Uri,System.Boolean) and System.Net.WebRequest.CreateDefault(System.Uri) methods.

Description

[Overrides: This method is required to be
overridden by classes that inherit from WebRequest.]

[Usage: Use this method to initiate a request to send
data to a resource and obtain a Stream instance for sending data to
that resource.

The System.Net.WebRequest.GetRequestStream method provides synchronous access to the Stream. For
asynchronous access, use the System.Net.WebRequest.BeginGetRequestStream(System.AsyncCallback,System.Object) and System.Net.WebRequest.EndGetRequestStream(System.IAsyncResult) methods.

Exceptions

Description

[Behaviors: This method returns an instance of a type
derived from WebResponse that is registered for the System.Net.WebRequest.RequestUri property of the current instance. This new
instance is required to contain a response from the resource to the current request.

If the timeout period for the request expires, or an
error occurs while processing the request, this method is required to throw a
WebException exception.

[Overrides: This
method must be overridden by classes that inherit from WebRequest to provide this
functionality. ]

[Usage: Use this method for synchronous access to a resource.
For asynchronous access, use the System.Net.WebRequest.BeginGetResponse(System.AsyncCallback,System.Object) and System.Net.WebRequest.EndGetResponse(System.IAsyncResult) methods.]

Return Value

Exceptions

Description

HttpWebRequest is registered
to service requests for HTTP and HTTPS schemes. Attempts to register a different
type for these schemes will
fail.

[Note: This method registers types that derive from WebRequest
to service requests. These derived types are
typically registered to handle a specific protocol, such HTTP or FTP, but can be
registered to handle a request to a specific server or path on a server.
Therefore, prefix
can be either a scheme or a complete
URI.

The WebRequest class calls the System.Net.IWebRequestCreate.Create(System.Uri)
method to create additional instances of the same type as
creator.

Description

[Overrides: This property is required to be
overridden by classes that inherit from WebRequest. The System.Net.WebRequest.ConnectionGroupName property
typically associates a group of requests that share a set of credentials with a
connection to an Internet resource to avoid potential security failures.
]

[Usage: ]

Use this property to get or set the name of the connection group for the current instance.

Exceptions

Description

[Behaviors: If System.Net.WebRequest.PreAuthenticate is true
, the current instance sends authentication
credentials without waiting to be challenged by the server specified by the
System.Net.WebRequest.RequestUri
property of the current instance. When
this property is false
, the
current instance waits for
a challenge from the server before sending credentials.]

[Overrides: This property must be overridden by
classes that inherit from WebRequest to provide this functionality. ]

[Usage: Use this
property to ensure that authentication information is sent with every
request. Setting this property to true
allows clients to improve
server efficiency by avoiding extra round trips caused by authentication challenges.]

Exceptions

Description

The System.Net.WebRequest.Proxy property identifies the network proxy
that the request uses to access resources. The request is made through the
proxy server rather than directly to the server hosting the resource.

[Behaviors: If the System.Net.WebRequest.Proxy
property of the current instance has not been set, the value of this property is
required to be null
.

Property Value

Exceptions

Description

This property is read-only.

[Behaviors: System.Net.WebRequest.RequestUri is required to
contain the URI passed to
the System.Net.WebRequest.Create(System.Uri,System.Boolean)
methods. If the protocol implemented
by a derived class supports redirection, the derived class is required
to provide a property to contain the URI that actually services the request.]

Exceptions

Description

[Behaviors: Classes that
derive from WebRequest are required to indicate a timeout by throwing a WebException with
the System.Net.WebException.Status field set to System.Net.WebExceptionStatus.Timeout if a request times out.]

[Overrides: This property
must be overridden by classes that inherit from WebRequest to
provide this functionality. ]

[Usage: Use this property to set the timeout period for requests for resources.

The System.Net.WebRequest.Timeout property affects only synchronous
requests made with the System.Net.WebRequest.GetResponse method. To time out asynchronous
requests, use the System.Net.WebRequest.Abort method.