System.Net.WebClient Class

public sealed class WebClient : MarshalByRefObject

Base Types

Object
  MarshalByRefObject
    WebClient

This type implements IDisposable.

Assembly

System

Library

Networking

Summary

Provides common methods for sending data to and receiving data from a resource identified by a URI.

Description

[Note: The WebClient class provides common methods for sending data to or receiving data from any local, Intranet, or Internet resource identified by a URI.

The WebClient class uses the WebRequest class to provide access to Internet resources. WebClient instances can access data with any class derived from WebRequest that is registered with the System.Net.WebRequest.RegisterPrefix(System.String,System.Net.IWebRequestCreate) method.

By default, the CLI supports URIs with the "http:", "https:", and "file:" schemes.

The WebClient class provides the following methods for uploading data to a resource.

• System.Net.WebClient.OpenWrite(System.String) sends a Stream to the server hosting a resource.
• System.Net.WebClient.UploadData(System.String,System.Byte[]) sends a byte array to the server hosting a resource and returns a byte array containing the response from the server, if any.
• System.Net.WebClient.UploadFile(System.String,System.String) sends a local file to the server hosting a resource and returns a byte array containing the response from the server, if any.
• System.Net.WebClient.UploadValues(System.String,System.Collections.Specialized.NameValueCollection) sends a NameValueCollection collection to the server hosting a resource and returns a byte array containing the response from the server, if any.

The WebClient class also provides the following methods for downloading data from a resource.

• System.Net.WebClient.DownloadData(System.String) downloads data from a resource and returns a byte array.
• System.Net.WebClient.DownloadFile(System.String,System.String) downloads data from a resource to a local file.
• System.Net.WebClient.OpenRead(System.String) returns the data from the resource as a Stream.

]

See Also

System.Net Namespace

Members

WebClient Constructors

WebClient Constructor

WebClient Methods

WebClient.DownloadData Method
WebClient.DownloadFile Method
WebClient.OpenRead Method
WebClient.OpenWrite(System.String) Method
WebClient.OpenWrite(System.String, System.String) Method
WebClient.UploadData(System.String, byte[]) Method
WebClient.UploadData(System.String, System.String, byte[]) Method
WebClient.UploadFile(System.String, System.String) Method
WebClient.UploadFile(System.String, System.String, System.String) Method
WebClient.UploadValues(System.String, System.Collections.Specialized.NameValueCollection) Method
WebClient.UploadValues(System.String, System.String, System.Collections.Specialized.NameValueCollection) Method

WebClient Properties

WebClient.BaseAddress Property
WebClient.Credentials Property
WebClient.Headers Property
WebClient.QueryString Property
WebClient.ResponseHeaders Property

Constructs a new instance of the WebClient class.

Description

This constructor creates a new instance of the WebClient class with properties set to null .

See Also

System.Net.WebClient Class, System.Net Namespace

address

A String that specifies the URI from which data will be downloaded.

Return Value

A Byte array containing the data downloaded from the resource specified by address.

Exceptions

Exception Type	Condition
WebException	The absolute URI is not valid. -or- An error occurred while downloading data.

Description

If the System.Net.WebClient.BaseAddress property of the current instance is not System.String.Empty, address is combined with System.Net.WebClient.BaseAddress to form the absolute URI of the requested data. If the System.Net.WebClient.BaseAddress property of the current instance is System.String.Empty, address is required to be the absolute URI of the requested data. If the System.Net.WebClient.QueryString property of the current instance is not System.String.Empty, it is appended to address.

See Also

System.Net.WebClient Class, System.Net Namespace

address

A String that specifies the URI from which data will be downloaded.

fileName

A String that specifies the name of the local file to which data will be written.

Exceptions

Exception Type	Condition
WebException	The absolute URI is not valid. -or- filename is null or System.String.Empty or contains invalid characters, or the specified path to the file does not exist. -or- An error occurred while downloading data.
SecurityException	The caller does not have permission to write to local files.

Description

If the System.Net.WebClient.BaseAddress property of the current instance is not System.String.Empty, address is combined with System.Net.WebClient.BaseAddress to form the absolute URI of the requested data. If the System.Net.WebClient.BaseAddress property of the current instance is System.String.Empty, address is required to be the absolute URI of the requested data. If the System.Net.WebClient.QueryString property of the current instance is not System.String.Empty, it is appended to address.

This method downloads data from the absolute URI to local file, fileName . If fileName already exists, the existing file is overwritten.

See Also

System.Net.WebClient Class, System.Net Namespace

Opens a readable Stream containing the data downloaded from the resource identified by the specified URI.

Parameters

address

A String that specifies the URI from which data will be downloaded.

Return Value

A Stream used to read data from a resource.

Exceptions

Exception Type	Condition
WebException	The absolute URI is not valid. -or- An error occurred while downloading data.

Description

If the System.Net.WebClient.BaseAddress property of the current instance is not System.String.Empty, address is combined with System.Net.WebClient.BaseAddress to form the absolute URI of the requested data. If the System.Net.WebClient.BaseAddress property of the current instance is System.String.Empty, address is required to be the absolute URI of the requested data. If the System.Net.WebClient.QueryString property of the current instance is not System.String.Empty, it is appended to address.

[Note: This method creates a Stream instance used to access the data specified by the absolute URI . The caller of this method is responsible for calling System.IO.Stream.Close to release the resources allocated for the stream.]

See Also

System.Net.WebClient Class, System.Net Namespace

Opens a Stream for writing data to the resource identified by the specified URI.

Parameters

address

A String that specifies the URI to receive the data.

Return Value

A Stream used to write data to the resource.

Exceptions

Exception Type	Condition
WebException	The absolute URI is not valid. -or- An error occurred while opening the stream.

Description

This method is equivalent to System.Net.WebClient.OpenWrite(System.String)(address, "POST").

If the System.Net.WebClient.BaseAddress property of the current instance is not System.String.Empty, address is combined with System.Net.WebClient.BaseAddress to form the absolute URI of the requested data. If the System.Net.WebClient.BaseAddress property of the current instance is System.String.Empty, address is required to be the absolute URI of the requested data. If the System.Net.WebClient.QueryString property of the current instance is not System.String.Empty, it is appended to address.

[Note: The underlying request is made with the POST method.]

See Also

System.Net.WebClient Class, System.Net Namespace

Opens a Stream for writing data to the resource identified by the specified URI using the specified protocol method.

Parameters

address

A String that specifies the URI of the resource to receive the data.

method

A String that specifies the protocol method used to send the data to the resource identified by address .

Return Value

A Stream used to write data to the resource.

Exceptions

Exception Type	Condition
WebException	The absolute URI is not valid. -or- An error occurred while opening the stream.

Description

If the System.Net.WebClient.BaseAddress property of the current instance is not System.String.Empty, address is combined with System.Net.WebClient.BaseAddress to form the absolute URI of the requested data. If the System.Net.WebClient.BaseAddress property of the current instance is System.String.Empty, address is required to be the absolute URI of the requested data. If the System.Net.WebClient.QueryString property of the current instance is not System.String.Empty, it is appended to address.

[Note: This method returns a writable stream that is used to send data to a resource. The underlying request is made with the protocol method specified by method . For more information about protocol methods, see System.Net.WebRequest.Method .

If the method parameter specifies a method that is not recognized by the server, the underlying protocol classes determine what occurs. Typically, a WebException is thrown with the System.Net.WebException.Status property set to indicate the error.

]

See Also

System.Net.WebClient Class, System.Net Namespace

address

A String that specifies the URI of the resource to receive the data.

data

A Byte array containing data to send to the resource.

Return Value

A Byte array containing the body of the response, if any, from the server hosting the resource.

Exceptions

Exception Type	Condition
WebException	The absolute URI is not valid. -or- data is null . -or- An error occurred while opening the stream or uploading the data. -or- There was no response from the server hosting the resource.

Description

This method is equivalent to System.Net.WebClient.UploadData(System.String,System.Byte[]) (address, "POST", data).

If the System.Net.WebClient.BaseAddress property of the current instance is not System.String.Empty, address is combined with System.Net.WebClient.BaseAddress to form the absolute URI of the requested data. If the System.Net.WebClient.BaseAddress property of the current instance is System.String.Empty, address is required to be the absolute URI of the requested data. If the System.Net.WebClient.QueryString property of the current instance is not System.String.Empty, it is appended to address.

[Note: This method sends a data buffer to a resource. The underlying request is made using the POST method.

This method does not encode the contents of data before uploading it to the resource.

]

See Also

System.Net.WebClient Class, System.Net Namespace

address

A String that specifies the URI of the resource to receive the data.

method

A String that specifies the protocol method used to send the data to the resource identified by address .

data

A Byte array containing data to send to the resource.

Return Value

A Byte array containing the body of the response, if any, from the server hosting the resource.

Exceptions

Exception Type	Condition
WebException	The absolute URI is not valid. -or- data is null . -or- An error occurred while opening the stream or uploading the data. -or- There was no response from the server hosting the resource.

Description

If the System.Net.WebClient.BaseAddress property of the current instance is not System.String.Empty, address is combined with System.Net.WebClient.BaseAddress to form the absolute URI of the requested data. If the System.Net.WebClient.BaseAddress property of the current instance is System.String.Empty, address is required to be the absolute URI of the requested data. If the System.Net.WebClient.QueryString property of the current instance is not System.String.Empty, it is appended to address.

[Note: For more information about protocol methods, see System.Net.WebRequest.Method .

This method does not encode the contents of data before uploading it to the resource.

If method specifies a method that is not recognized by the server, the underlying protocol classes determine what occurs. Typically, a WebException is thrown with the System.Net.WebException.Status property set to indicate the error.

]

See Also

System.Net.WebClient Class, System.Net Namespace

address

A String that specifies the URI of the resource to receive the file.

fileName

A String that specifies the file to send to the resource.

Return Value

A Byte array containing the body of the response, if any, from the server hosting the resource.

Exceptions

Exception Type	Condition
WebException	The absolute URI is not valid. -or- filename is null or System.String.Empty or contains invalid characters, or the specified path to the file does not exist. -or- An error occurred while opening the stream or uploading the file. -or- There was no response from the server hosting the resource. -or- The Content-Type header begins with "multipart".
SecurityException	Local file access has not been granted.

Description

This method is equivalent to System.Net.WebClient.UploadFile(System.String,System.String) (address, "POST", filename).

If the System.Net.WebClient.BaseAddress property of the current instance is not System.String.Empty, address is combined with System.Net.WebClient.BaseAddress to form the absolute URI of the requested data. If the System.Net.WebClient.BaseAddress property of the current instance is System.String.Empty, address is required to be the absolute URI of the requested data. If the System.Net.WebClient.QueryString property of the current instance is not System.String.Empty, it is appended to address.

[Note: This method sends a local file to a resource. The underlying request is made using the POST method.]

See Also

System.Net.WebClient Class, System.Net Namespace

address

A String that specifies the URI of the resource to receive the file.

method

A String that specifies the protocol method used to send the data to the resource identified by address .

fileName

A String that specifies the file to send to the resource.

Return Value

A Byte array containing the body of the response, if any, from the server hosting the resource.

Exceptions

Exception Type	Condition
WebException	The absolute URI is not valid. -or- filename is null or System.String.Empty or contains invalid characters, or the specified path to the file does not exist. -or- An error occurred while opening the stream or uploading the file. -or- There was no response from the server hosting the resource. -or- The Content-Type header begins with "multipart".
SecurityException	The caller does not have the required permissions.

Description

If the System.Net.WebClient.BaseAddress property of the current instance is not System.String.Empty, address is combined with System.Net.WebClient.BaseAddress to form the absolute URI of the requested data. If the System.Net.WebClient.BaseAddress property of the current instance is System.String.Empty, address is required to be the absolute URI of the requested data. If the System.Net.WebClient.QueryString property of the current instance is not System.String.Empty, it is appended to address.

[Note: For more information about protocol methods, see System.Net.WebRequest.Method .

If method specifies a protocol method that is not recognized by the server, the underlying protocol classes determine what occurs. Typically, a WebException is thrown with the System.Net.WebException.Status property set to indicate the error.

]

See Also

System.Net.WebClient Class, System.Net Namespace

address

A String that specifies the URI of the resource to receive the collection data .

data

The NameValueCollection to send to the resource identified by address .

Return Value

A Byte array containing the body of the response, if any, from the server hosting the resource.

Exceptions

Exception Type	Condition
WebException	The absolute URI is not valid. -or- data is null . -or- An error occurred while opening the stream or uploading the data. -or- There was no response from the server hosting the resource. -or- The Content-Type header is not null , and is not "application/x-www-form-urlencoded".

Description

This method is equivalent to System.Net.WebClient.UploadValues(System.String,System.Collections.Specialized.NameValueCollection) (address, "POST", data).

If the Content-Type header is null , this method sets it to "application/x-www-form-urlencoded".

If the System.Net.WebClient.BaseAddress property of the current instance is not System.String.Empty, address is combined with System.Net.WebClient.BaseAddress to form the absolute URI of the requested data. If the System.Net.WebClient.BaseAddress property of the current instance is System.String.Empty, address is required to be the absolute URI of the requested data. If the System.Net.WebClient.QueryString property of the current instance is not System.String.Empty, it is appended to address.

[Note: The underlying request is made using the POST method. ]

See Also

System.Net.WebClient Class, System.Net Namespace

address

A String that specifies the URI of the resource to receive the collection data .

method

A String that specifies the protocol method used to send data to the resource.

data

The NameValueCollection to send to the resource identified by address .

Return Value

A Byte array containing the body of the response, if any, from the server hosting the resource.

Exceptions

Exception Type	Condition
WebException	The absolute URI is not valid. -or- data is null . -or- An error occurred while opening the stream or uploading the data. -or- There was no response from the server hosting the resource. -or- The Content-Type header is not null , and is not "application/x-www-form-urlencoded".

Description

If the Content-Type header is null , this method sets it to "application/x-www-form-urlencoded".

If the System.Net.WebClient.BaseAddress property of the current instance is not System.String.Empty, address is combined with System.Net.WebClient.BaseAddress to form the absolute URI of the requested data. If the System.Net.WebClient.BaseAddress property of the current instance is System.String.Empty, address is required to be the absolute URI of the requested data. If the System.Net.WebClient.QueryString property of the current instance is not System.String.Empty, it is appended to address.

[Note: If method specifies a protocol method that is not recognized by the server, the underlying protocol classes determine what occurs. Typically, a WebException is thrown with the System.Net.WebException.Status property set to indicate the error.]

See Also

System.Net.WebClient Class, System.Net Namespace

Gets or sets the base URI for requests made by a WebClient .

Property Value

A String containing the base URI for requests made by a WebClient or, System.String.Empty, if no value was set or null was specified for a set operation.

Exceptions

Exception Type	Condition
ArgumentException	The value specified for a set operation is not null or System.String.Empty, and is not a URI in a format recognized by the Uri class.

Description

[Note: The System.Net.WebClient.BaseAddress property contains a base URI that is combined with the relative address specified when calling an upload or download method.]

See Also

System.Net.WebClient Class, System.Net Namespace

A ICredentials containing the authentication credentials for the request. The default is null .

Description

The System.Net.WebClient.Credentials property contains the authentication credentials required to access the Internet resource.

See Also

System.Net.WebClient Class, System.Net Namespace

A WebHeaderCollection containing header name/value pairs associated with the request or, if this property has not been set or was set to null , a new instance of the WebHeaderCollection class.

Description

[Note: This property stores the header information that the current instance sends with a request. This is an unrestricted collection of headers; setting headers that are protected in WebRequest descendants like HttpWebRequest is allowed.]

See Also

System.Net.WebClient Class, System.Net Namespace

A NameValueCollection that contains query name/value pairs associated with the request or, if this property has not been set or was set to null , a new instance of the NameValueCollection class.

Description

The System.Net.WebClient.QueryString property contains a NameValueCollection instance containing name/value pairs that are appended to the URI as a query string. The contents of the System.Net.WebClient.QueryString property are preceded by a question mark (?), and each name/value pair is separated by an ampersand (&).

See Also

System.Net.WebClient Class, System.Net Namespace

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

Description

This property is read-only.

The System.Net.WebClient.ResponseHeaders property contains a WebHeaderCollection instance containing header information the WebClient receives from the Internet resource.

See Also

System.Net.WebClient Class, System.Net Namespace