System.Net.WebRequest Class

public abstract class WebRequest : MarshalByRefObject

Base Types

Object
  MarshalByRefObject
    WebRequest

Assembly

System

Library

Networking

Summary

Makes a request to a Uniform Resource Identifier (URI).

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 may 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).]

The WebRequest class throws a WebException exception when an error occurs while accessing a resource.

Use the System.Net.WebRequest.Create(System.Uri,System.Boolean) method to initialize a new instance of a class that derives from WebRequest . Do not use the WebRequest constructor.

]

Example

The following example demonstrates using System.Net.WebRequest.Create(System.Uri,System.Boolean) to create an instance of HttpWebRequest .

using System;
using System.Net;

public class WebRequestExample {

  public static void Main() {

    // Initialize the WebRequest.
    WebRequest myRequest =
      WebRequest.Create("http://www.contoso.com");

    // Print the type of the request.
    Console.WriteLine(myRequest);
  }
}

The output is

System.Net.HttpWebRequest

See Also

System.Net Namespace

Members

WebRequest Constructors

WebRequest Constructor

WebRequest Methods

WebRequest.Abort Method
WebRequest.BeginGetRequestStream Method
WebRequest.BeginGetResponse Method
WebRequest.Create(System.String) Method
WebRequest.Create(System.Uri) Method
WebRequest.CreateDefault Method
WebRequest.EndGetRequestStream Method
WebRequest.EndGetResponse Method
WebRequest.GetRequestStream Method
WebRequest.GetResponse Method
WebRequest.RegisterPrefix Method

WebRequest Properties

WebRequest.ConnectionGroupName Property
WebRequest.ContentLength Property
WebRequest.ContentType Property
WebRequest.Credentials Property
WebRequest.Headers Property
WebRequest.Method Property
WebRequest.PreAuthenticate Property
WebRequest.Proxy Property
WebRequest.RequestUri Property
WebRequest.Timeout Property

Constructs a new instance of the WebRequest class.

Description

This constructor is called only by classes that derive from WebRequest.

[Note: Use the System.Net.WebRequest.Create(System.Uri,System.Boolean) method to initialize a new instance of a class that derives from WebRequest . Do not use this constructor.]

See Also

System.Net.WebRequest Class, System.Net Namespace

[Behaviors: As described above.]

[Default: The WebRequest class is abstract and does not provide an implementation for this method. This method throws NotSupportedException.]

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

[Usage: Use this method to cancel an asynchronous operation started with the System.Net.WebRequest.BeginGetResponse(System.AsyncCallback,System.Object) method.]

See Also

System.Net.WebRequest Class, System.Net Namespace

callback

A AsyncCallback delegate to be called when the stream is available. Can be null .

state

A Object containing state information for the asynchronous request.

Return Value

A IAsyncResult object that contains information about the asynchronous operation.

Exceptions

Exception Type	Condition
NotSupportedException	This method is not overridden in the derived class.

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.

]

[Default: The WebRequest class is abstract and does not provide an implementation for this method. This method throws NotSupportedException.]

[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. ]

See Also

System.Net.WebRequest Class, System.Net Namespace

callback

A AsyncCallback delegate to be called when the response from the server is available.

state

A Object containing state information for the asynchronous request.

Return Value

A IAsyncResult object that contains information about the asynchronous operation.

Exceptions

Exception Type	Condition
NotSupportedException	This method is not overridden in the derived class.

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.

]

[Default: The WebRequest class is abstract and does not provide an implementation for this method. This method throws NotSupportedException.]

[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.]

See Also

System.Net.WebRequest Class, System.Net Namespace

Constructs a new instance of a class derived from WebRequest. The new instance is of the type registered for the scheme of the specified URI.

Parameters

requestUriString

A String that contains a URI.

Return Value

A new instance of a class that derived from WebRequest and is registered to handle the scheme of requestUriString.

Exceptions

Exception Type	Condition
ArgumentNullException	requestUriString is null .
NotSupportedException	The request scheme specified in requestUri is not registered.
UriFormatException	The URI specified in requestUriString is not a valid URI.
SecurityException	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.

]

See Also

System.Net.WebRequest Class, System.Net Namespace

Constructs a new instance of a class derived from WebRequest.

Parameters

requestUri

A Uri containing the URI of the requested resource.

Return Value

A new instance of a class derived from WebRequest that is registered to handle the closest registered match for requestUri.

Exceptions

Exception Type	Condition
ArgumentNullException	requestUri is null .
NotSupportedException	The request scheme specified in requestUri is not registered.
SecurityException	The caller does not have permission to connect to the requested URI or a URI that the request is redirected to.

Description

To determine the closest match, this method checks the registered URIs for the longest URI prefix that matches requestUri.

[Note: For an example that demonstrates this method, see System.Net.WebRequest.CreateDefault(System.Uri).

]

See Also

System.Net.WebRequest Class, System.Net Namespace

Constructs a new instance of a class derived from WebRequest. The new instance is of the type registered for the scheme of the specified URI.

Parameters

requestUri

A Uri containing the URI of the requested resource.

Return Value

A new instance of the type derived from WebRequest that is registered for the scheme of the specified Uri .

Exceptions

Exception Type	Condition
ArgumentNullException	requestUri is null .
NotSupportedException	The request scheme specified in requestUri is not registered.
SecurityException	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.

using System;
using System.Net;

public class ContosoTextRequest : WebRequest, IWebRequestCreate
{
   public new WebRequest Create(Uri uri)
   {
      return new ContosoTextRequest();
   }
}

public class CreateDefaultExample
{
   public static void Main()
   {
      ContosoTextRequest contoso = new ContosoTextRequest();
      Uri contosoUri = new Uri("http://www.contoso.com/text");
      WebRequest.RegisterPrefix("http://www.contoso.com/text", contoso);

      WebRequest httpContoso = WebRequest.CreateDefault(contosoUri);
      Console.WriteLine("CreateDefault --> {0}", httpContoso);

      WebRequest textContoso = WebRequest.Create(contosoUri);
      Console.WriteLine("Create --> {0}", textContoso);
   }
}

The output is

CreateDefault --> System.Net.HttpWebRequest

Create --> ContosoTextRequest

See Also

System.Net.WebRequest Class, System.Net Namespace

Returns a Stream for writing data to the resource identified by the System.Net.WebRequest.RequestUri property of the current instance.

Parameters

asyncResult

A IAsyncResult object that references a request for a Stream started with System.Net.WebRequest.BeginGetRequestStream(System.AsyncCallback,System.Object) .

Return Value

A Stream to write data to.

Exceptions

Exception Type	Condition
NotSupportedException	This method is not overridden in the derived class.
ArgumentException	asyncResult was not returned by a call to System.Net.WebRequest.BeginGetRequestStream(System.AsyncCallback,System.Object).
ArgumentNullException	asyncResult is a null reference.
InvalidOperationException	This method was called previously using asyncResult. -or- No stream is available.
WebException	An error occurred while processing the request.

Description

This method completes an asynchronous request for a stream that was started by the System.Net.WebRequest.BeginGetRequestStream(System.AsyncCallback,System.Object) method.

[Behaviors: As described above. ]

[Default: The WebRequest class is abstract and does not provide an implementation for this method. This method throws NotSupportedException.]

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

[Usage: Use this method to complete an asynchronous request for a stream that was started with the System.Net.WebRequest.BeginGetRequestStream(System.AsyncCallback,System.Object) method.

]

See Also

System.Net.WebRequest Class, System.Net Namespace

Returns a WebResponse that contains a response to a specified pending request.

Parameters

asyncResult

A IAsyncResult object that references a pending request that was started with System.Net.WebRequest.BeginGetResponse(System.AsyncCallback,System.Object).

Return Value

A WebResponse that contains a response to the request referenced by asyncResult.

Exceptions

Exception Type	Condition
NotSupportedException	This method is not overridden in the derived class.
ArgumentException	asyncResult was not returned by a call to System.Net.WebRequest.BeginGetResponse(System.AsyncCallback,System.Object).
ArgumentNullException	asyncResult is a null reference.
InvalidOperationException	The System.Net.WebRequest.ContentLength property of the current instance is greater than zero but no data has been written to the request stream. -or- This method was called previously using asyncResult.
WebException	An error occurred while processing the request.

Description

[Behaviors: As described above.]

[Default: The WebRequest class is abstract and does not provide an implementation for this method. This method throws NotSupportedException.]

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

[Usage: Use this method to complete an asynchronous request for an Internet resource that was started with the System.Net.WebRequest.BeginGetResponse(System.AsyncCallback,System.Object) method. ]

See Also

System.Net.WebRequest Class, System.Net Namespace

Returns a Stream for writing data to a resource.

Return Value

A Stream for writing data to a resource.

Exceptions

Exception Type	Condition
NotSupportedException	This method is not overridden in the derived class.

Description

[Behaviors: As described above.]

[Default: The WebRequest class is abstract and does not provide an implementation for this method. This method throws NotSupportedException.]

[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.

]

See Also

System.Net.WebRequest Class, System.Net Namespace

A WebResponse containing the response to the request.

Exceptions

Exception Type	Condition
NotSupportedException	This method is not overridden in the derived class.
WebException	The request timed out. -or- An error occurred while processing the request.

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.

]

[Default: The WebRequest class is abstract and does not provide an implementation for this method. This method throws NotSupportedException.]

[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.]

See Also

System.Net.WebRequest Class, System.Net Namespace

Registers a type derived from WebRequest, and associates the type with the specified URI.

Parameters

prefix

A String containing the URI that the derived type services. Can specify a scheme or a complete URI.

creator

An instance of a type that implements the IWebRequestCreate interface.

Return Value

true if registration is successful; false , if prefix is already registered.

Exceptions

Exception Type	Condition
ArgumentNullException	prefix is null or creator is null .

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.

]

Example

The following example demonstrates how to register a new scheme.

using System;
using System.Net;

public class ftpWebRequest : WebRequest {
   //implement ftp-specific protocol methods and properties
}

public class ftpCreator : IWebRequestCreate 
{
   public WebRequest Create(Uri uri) 
   {
      return new ftpWebRequest(); 
   }
}

public class RegisterPrefixExample
{

   public static void Main() 
   {
 
      ftpCreator creator = new ftpCreator();
      WebRequest.RegisterPrefix("ftp://", creator);
      WebRequest wr = WebRequest.Create("ftp://testFile");
      Console.WriteLine(wr);
   }
}
   

The output is

ftpWebRequest

See Also

System.Net.WebRequest Class, System.Net Namespace

A String that contains the name of the connection group for the current instance.

Exceptions

Exception Type	Condition
NotSupportedException	This property is not implemented in the derived class.

Description

This property associates specific requests within an application with a ServicePoint .

[Behaviors: As described above.]

[Default: This property throws NotSupportedException.]

[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.

See Also

System.Net.WebRequest Class, System.Net Namespace

A Int64 containing the number of bytes of request data being sent.

Exceptions

Exception Type	Condition
NotSupportedException	This property is not implemented in the derived class.
InvalidOperationException	Data has already been written to the request stream.
ArgumentOutOfRangeException	This property is being set to a value less than zero.

Description

[Behaviors: This property is required to throw a InvalidOperationException exception if data has already been written to the request stream, and a ArgumentOutOfRangeException exception if the property is being set to a value less than zero.]

[Default: This property throws NotSupportedException.]

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

[Usage: Use this property to get the number of bytes sent to the resource.]

See Also

System.Net.WebRequest Class, System.Net Namespace

A String that represents the content type of the request data.

Exceptions

Exception Type	Condition
NotSupportedException	This property is not implemented in the derived class.

Description

The System.Net.WebRequest.ContentType property contains the media type of the request.

[Note: This is typically the MIME encoding of the content.]

[Behaviors: As described above.]

[Default: This property throws NotSupportedException.]

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

[Usage: Use this property to get the media type of request.]

See Also

System.Net.WebRequest Class, System.Net Namespace

A ICredentials object containing the authentication credentials associated with the request. The default is null .

Exceptions

Exception Type	Condition
NotSupportedException	This property is not implemented in the derived class.

Description

[Behaviors: As described above.]

[Default: This property throws NotSupportedException.]

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

[Usage: Use this property to store or access the user, password, and domain information of the current instance.]

See Also

System.Net.WebRequest Class, System.Net Namespace

A WebHeaderCollection containing the header name/value pairs associated with the current instance.

Exceptions

Exception Type	Condition
NotSupportedException	This property is not implemented in the derived class.

Description

This property contains a WebHeaderCollection instance containing the header information to send to resources.

[Behaviors: As described above.]

[Default: This property throws a NotSupportedException exception.]

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

[Usage: Use this property to determine the header information of a request.]

See Also

System.Net.WebRequest Class, System.Net Namespace

A String containing the protocol method to use in the current instance.

Exceptions

Exception Type	Condition
NotSupportedException	This property is not implemented in the derived class.

Description

[Behaviors: The default value of this property is required to be a protocol method that does not require protocol-specific properties to be set. For the HTTP protocol, this value is GET.]

[Default: This property throws NotSupportedException.]

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

[Usage: Use this property to set the protocol-specific method that will be used to make a request.]

See Also

System.Net.WebRequest Class, System.Net Namespace

Gets or sets a Boolean value that determines whether to send authentication information with the current request instead of waiting for an authentication challenge from the requested resource.

Property Value

true if authentication information will be sent with the current request without waiting for an authentication challenge from the requested resource; otherwise, false .

Exceptions

Exception Type	Condition
NotSupportedException	This property is not implemented in the derived class.

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.]

[Default: This property throws NotSupportedException.]

[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.]

See Also

System.Net.WebRequest Class, System.Net Namespace

A IWebProxy to use to access resources.

Exceptions

Exception Type	Condition
NotSupportedException	This property is not implemented in the derived class.

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 .

If the property is being set to null , it is required to throw a ArgumentNullException exception.

]

[Default: This property throws NotSupportedException.]

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

[Usage: Use this method to obtain a IWebProxy instance that represents the proxy server used by the current instance.]

See Also

System.Net.WebRequest Class, System.Net Namespace

Gets the Uri of the resource associated with the current instance.

Property Value

A Uri containing the URI of the resource associated with the current instance

Exceptions

Exception Type	Condition
NotSupportedException	This property is not implemented in the derived class.

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.]

[Default: This property throws a NotSupportedException exception.]

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

]

[Usage: Use this property to determine the URI that the request was addressed to. For information about the URI that actually serviced the request, see System.Net.WebResponse.ResponseUri . ]

See Also

System.Net.WebRequest Class, System.Net Namespace

A Int32 containing the length of time, in milliseconds, before the current request will time out, or System.Threading.Timeout.Infinite to indicate that the request does not time out.

Exceptions

Exception Type	Condition
NotSupportedException	This property is not implemented in the derived class.

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.]

[Default: This property throws a NotSupportedException exception.]

[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.

]

See Also

System.Net.WebRequest Class, System.Net Namespace