3 out of 12 rated this helpful - Rate this topic

WebClient Class

.NET Framework 4

Other Versions

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

Inheritance Hierarchy

System.Object
  System.MarshalByRefObject
    System.ComponentModel.Component
      System.Net.WebClient

Namespace: System.Net
Assembly: System (in System.dll)

Syntax

C++

Copy

[ComVisibleAttribute(true)]
public class WebClient : Component

The WebClient type exposes the following members.

Constructors

	Name	Description
	WebClient	Initializes a new instance of the WebClient class.

Top

Properties

	Name	Description
	BaseAddress	Gets or sets the base URI for requests made by a WebClient.
	CachePolicy	Gets or sets the application's cache policy for any resources obtained by this WebClient instance using WebRequest objects.
	CanRaiseEvents	Gets a value indicating whether the component can raise an event. (Inherited from Component.)
	Container	Gets the IContainer that contains the Component. (Inherited from Component.)
	Credentials	Gets or sets the network credentials that are sent to the host and used to authenticate the request.
	DesignMode	Gets a value that indicates whether the Component is currently in design mode. (Inherited from Component.)
	Encoding	Gets and sets the Encoding used to upload and download strings.
	Events	Gets the list of event handlers that are attached to this Component. (Inherited from Component.)
	Headers	Gets or sets a collection of header name/value pairs associated with the request.
	IsBusy	Gets whether a Web request is in progress.
	Proxy	Gets or sets the proxy used by this WebClient object.
	QueryString	Gets or sets a collection of query name/value pairs associated with the request.
	ResponseHeaders	Gets a collection of header name/value pairs associated with the response.
	Site	Gets or sets the ISite of the Component. (Inherited from Component.)
	UseDefaultCredentials	Gets or sets a Boolean value that controls whether the DefaultCredentials are sent with requests.

Top

Methods

	Name	Description
	CancelAsync	Cancels a pending asynchronous operation.
	CreateObjRef	Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. (Inherited from MarshalByRefObject.)
	Dispose()	Releases all resources used by the Component. (Inherited from Component.)
	Dispose(Boolean)	Releases the unmanaged resources used by the Component and optionally releases the managed resources. (Inherited from Component.)
	DownloadData(String)	Downloads the resource with the specified URI as a Byte array.
	DownloadData(Uri)	Downloads the resource with the specified URI as a Byte array.
	DownloadDataAsync(Uri)	Downloads the specified resource as a Byte array. This method does not block the calling thread.
	DownloadDataAsync(Uri, Object)	Downloads the specified resource as a Byte array. This method does not block the calling thread.
	DownloadFile(String, String)	Downloads the resource with the specified URI to a local file.
	DownloadFile(Uri, String)	Downloads the resource with the specified URI to a local file.
	DownloadFileAsync(Uri, String)	Downloads, to a local file, the resource with the specified URI. This method does not block the calling thread.
	DownloadFileAsync(Uri, String, Object)	Downloads, to a local file, the resource with the specified URI. This method does not block the calling thread.
	DownloadString(String)	Downloads the requested resource as a String. The resource to download is specified as a String containing the URI.
	DownloadString(Uri)	Downloads the requested resource as a String. The resource to download is specified as a Uri.
	DownloadStringAsync(Uri)	Downloads the resource specified as a Uri. This method does not block the calling thread.
	DownloadStringAsync(Uri, Object)	Downloads the specified string to the specified resource. This method does not block the calling thread.
	Equals(Object)	Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
	Finalize	Releases unmanaged resources and performs other cleanup operations before the Component is reclaimed by garbage collection. (Inherited from Component.)
	GetHashCode	Serves as a hash function for a particular type. (Inherited from Object.)
	GetLifetimeService	Retrieves the current lifetime service object that controls the lifetime policy for this instance. (Inherited from MarshalByRefObject.)
	GetService	Returns an object that represents a service provided by the Component or by its Container. (Inherited from Component.)
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	GetWebRequest	Returns a WebRequest object for the specified resource.
	GetWebResponse(WebRequest)	Returns the WebResponse for the specified WebRequest.
	GetWebResponse(WebRequest, IAsyncResult)	Returns the WebResponse for the specified WebRequest using the specified IAsyncResult.
	InitializeLifetimeService	Obtains a lifetime service object to control the lifetime policy for this instance. (Inherited from MarshalByRefObject.)
	MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object.)
	MemberwiseClone(Boolean)	Creates a shallow copy of the current MarshalByRefObject object. (Inherited from MarshalByRefObject.)
	OnDownloadDataCompleted	Raises the DownloadDataCompleted event.
	OnDownloadFileCompleted	Raises the DownloadFileCompleted event.
	OnDownloadProgressChanged	Raises the DownloadProgressChanged event.
	OnDownloadStringCompleted	Raises the DownloadStringCompleted event.
	OnOpenReadCompleted	Raises the OpenReadCompleted event.
	OnOpenWriteCompleted	Raises the OpenWriteCompleted event.
	OnUploadDataCompleted	Raises the UploadDataCompleted event.
	OnUploadFileCompleted	Raises the UploadFileCompleted event.
	OnUploadProgressChanged	Raises the UploadProgressChanged event.
	OnUploadStringCompleted	Raises the UploadStringCompleted event.
	OnUploadValuesCompleted	Raises the UploadValuesCompleted event.
	OpenRead(String)	Opens a readable stream for the data downloaded from a resource with the URI specified as a String.
	OpenRead(Uri)	Opens a readable stream for the data downloaded from a resource with the URI specified as a Uri
	OpenReadAsync(Uri)	Opens a readable stream containing the specified resource. This method does not block the calling thread.
	OpenReadAsync(Uri, Object)	Opens a readable stream containing the specified resource. This method does not block the calling thread.
	OpenWrite(String)	Opens a stream for writing data to the specified resource.
	OpenWrite(Uri)	Opens a stream for writing data to the specified resource.
	OpenWrite(String, String)	Opens a stream for writing data to the specified resource, using the specified method.
	OpenWrite(Uri, String)	Opens a stream for writing data to the specified resource, by using the specified method.
	OpenWriteAsync(Uri)	Opens a stream for writing data to the specified resource. This method does not block the calling thread.
	OpenWriteAsync(Uri, String)	Opens a stream for writing data to the specified resource. This method does not block the calling thread.
	OpenWriteAsync(Uri, String, Object)	Opens a stream for writing data to the specified resource, using the specified method. This method does not block the calling thread.
	ToString	Returns a String containing the name of the Component, if any. This method should not be overridden. (Inherited from Component.)
	UploadData(String, Byte[])	Uploads a data buffer to a resource identified by a URI.
	UploadData(Uri, Byte[])	Uploads a data buffer to a resource identified by a URI.
	UploadData(String, String, Byte[])	Uploads a data buffer to the specified resource, using the specified method.
	UploadData(Uri, String, Byte[])	Uploads a data buffer to the specified resource, using the specified method.
	UploadDataAsync(Uri, Byte[])	Uploads a data buffer to a resource identified by a URI, using the POST method. This method does not block the calling thread.
	UploadDataAsync(Uri, String, Byte[])	Uploads a data buffer to a resource identified by a URI, using the specified method. This method does not block the calling thread.
	UploadDataAsync(Uri, String, Byte[], Object)	Uploads a data buffer to a resource identified by a URI, using the specified method and identifying token.
	UploadFile(String, String)	Uploads the specified local file to a resource with the specified URI.
	UploadFile(Uri, String)	Uploads the specified local file to a resource with the specified URI.
	UploadFile(String, String, String)	Uploads the specified local file to the specified resource, using the specified method.
	UploadFile(Uri, String, String)	Uploads the specified local file to the specified resource, using the specified method.
	UploadFileAsync(Uri, String)	Uploads the specified local file to the specified resource, using the POST method. This method does not block the calling thread.
	UploadFileAsync(Uri, String, String)	Uploads the specified local file to the specified resource, using the POST method. This method does not block the calling thread.
	UploadFileAsync(Uri, String, String, Object)	Uploads the specified local file to the specified resource, using the POST method. This method does not block the calling thread.
	UploadString(String, String)	Uploads the specified string to the specified resource, using the POST method.
	UploadString(Uri, String)	Uploads the specified string to the specified resource, using the POST method.
	UploadString(String, String, String)	Uploads the specified string to the specified resource, using the specified method.
	UploadString(Uri, String, String)	Uploads the specified string to the specified resource, using the specified method.
	UploadStringAsync(Uri, String)	Uploads the specified string to the specified resource. This method does not block the calling thread.
	UploadStringAsync(Uri, String, String)	Uploads the specified string to the specified resource. This method does not block the calling thread.
	UploadStringAsync(Uri, String, String, Object)	Uploads the specified string to the specified resource. This method does not block the calling thread.
	UploadValues(String, NameValueCollection)	Uploads the specified name/value collection to the resource identified by the specified URI.
	UploadValues(Uri, NameValueCollection)	Uploads the specified name/value collection to the resource identified by the specified URI.
	UploadValues(String, String, NameValueCollection)	Uploads the specified name/value collection to the resource identified by the specified URI, using the specified method.
	UploadValues(Uri, String, NameValueCollection)	Uploads the specified name/value collection to the resource identified by the specified URI, using the specified method.
	UploadValuesAsync(Uri, NameValueCollection)	Uploads the data in the specified name/value collection to the resource identified by the specified URI. This method does not block the calling thread.
	UploadValuesAsync(Uri, String, NameValueCollection)	Uploads the data in the specified name/value collection to the resource identified by the specified URI, using the specified method. This method does not block the calling thread.
	UploadValuesAsync(Uri, String, NameValueCollection, Object)	Uploads the data in the specified name/value collection to the resource identified by the specified URI, using the specified method. This method does not block the calling thread, and allows the caller to pass an object to the method that is invoked when the operation completes.

Top

Events

	Name	Description
	Disposed	Occurs when the component is disposed by a call to the Dispose method. (Inherited from Component.)
	DownloadDataCompleted	Occurs when an asynchronous data download operation completes.
	DownloadFileCompleted	Occurs when an asynchronous file download operation completes.
	DownloadProgressChanged	Occurs when an asynchronous download operation successfully transfers some or all of the data.
	DownloadStringCompleted	Occurs when an asynchronous resource-download operation completes.
	OpenReadCompleted	Occurs when an asynchronous operation to open a stream containing a resource completes.
	OpenWriteCompleted	Occurs when an asynchronous operation to open a stream to write data to a resource completes.
	UploadDataCompleted	Occurs when an asynchronous data-upload operation completes.
	UploadFileCompleted	Occurs when an asynchronous file-upload operation completes.
	UploadProgressChanged	Occurs when an asynchronous upload operation successfully transfers some or all of the data.
	UploadStringCompleted	Occurs when an asynchronous string-upload operation completes.
	UploadValuesCompleted	Occurs when an asynchronous upload of a name/value collection completes.

Top

Remarks

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 resources. WebClient instances can access data with any WebRequest descendant registered with the WebRequest.RegisterPrefix method.

Note
By default, the .NET Framework supports URIs that begin with http:, https:, ftp:, and file: scheme identifiers.

The following table describes WebClient methods for uploading data to a resource.

Method	Description
OpenWrite	Retrieves a Stream used to send data to the resource.
OpenWriteAsync	Retrieves a Stream used to send data to the resource, without blocking the calling thread.
UploadData	Sends a byte array to the resource and returns a Byte array containing any response.
UploadDataAsync	Sends a Byte array to the resource, without blocking the calling thread.
UploadFile	Sends a local file to the resource and returns a Byte array containing any response.
UploadFileAsync	Sends a local file to the resource, without blocking the calling thread.
UploadValues	Sends a NameValueCollection to the resource and returns a Byte array containing any response.
UploadValuesAsync	Sends a NameValueCollection to the resource and returns a Byte array containing any response, without blocking the calling thread.
UploadString	Sends a String to the resource, without blocking the calling thread.
UploadStringAsync	Sends a String to the resource, without blocking the calling thread.

The following table describes WebClient methods for downloading data from a resource.

Method	Description
OpenRead	Returns the data from a resource as a Stream.
OpenReadAsync	Returns the data from a resource, without blocking the calling thread.
DownloadData	Downloads data from a resource and returns a Byte array.
DownloadDataAsync	Downloads data from a resource and returns a Byte array, without blocking the calling thread.
DownloadFile	Downloads data from a resource to a local file.
DownloadFileAsync	Downloads data from a resource to a local file, without blocking the calling thread.
DownloadString	Downloads a String from a resource and returns a String.
DownloadStringAsync	Downloads a String from a resource, without blocking the calling thread.

You can use the CancelAsync method to cancel asynchronous operations that have not completed.

A WebClient instance does not send optional HTTP headers by default. If your request requires an optional header, you must add the header to the Headers collection. For example, to retain queries in the response, you must add a user-agent header. Also, servers may return 500 (Internal Server Error) if the user agent header is missing.

AllowAutoRedirect is set to true in WebClient instances.

Notes to Inheritors

Derived classes should call the base class implementation of WebClient to ensure the derived class works as expected.

Examples

The following code example takes the URI of a resource, retrieves it, and displays the response.

C++

Copy


using System;
using System.Net;
using System.IO;

public class Test
{
    public static void Main (string[] args)
    {
        if (args == null || args.Length == 0)
        {
            throw new ApplicationException ("Specify the URI of the resource to retrieve.");
        }
        WebClient client = new WebClient ();

        // Add a user agent header in case the 
        // requested URI contains a query.

        client.Headers.Add ("user-agent", "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.2; .NET CLR 1.0.3705;)");

        Stream data = client.OpenRead (args[0]);
        StreamReader reader = new StreamReader (data);
        string s = reader.ReadToEnd ();
        Console.WriteLine (s);
        data.Close ();
        reader.Close ();
    }
}

Version Information

.NET Framework

Supported in: 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library

.NET Framework Security

WebPermission
to access the requested URI or any URI that the request is redirected to. Associated enumeration: Connect.

Platforms

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Reference

System.Net Namespace

WebRequest

WebResponse

HttpWebRequest

HttpWebResponse

Did you find this helpful? Yes No

Not accurate

Not enough depth

Need more code examples

(1500 characters remaining)

Community Content Add

FAQ

Getting a response code is a faff.

See link for information about getting a proper HTTP status code from a request. http://stackoverflow.com/questions/1015020/how-to-read-an-asp-net-internal-server-error-description-with-net

History

4/6/2012
LukePuplett

Example doesn't work for .NET 4

the example works for earlier versions, but not in .NET 4 VS 2010

History

12/7/2011
Elbow McDougal

UploadString does block the calling thread

UploadString in the remarks should have "Sends a String to the resource" and not "Sends a String to the resource, without blocking the calling thread." as it does block the calling thread.

History

9/8/2011
JLWarlow

WebClient (with Proxy configured in IE) is broken in .net 4?

The following code download the yahoo website file with target .net 2.0, 3.0, 3.5 with proxy configured in IE. But it does not work for target .net 4. I'm using VS2010. How could it be broken in .net 4?!

using System;
using System.Net;
using System.IO;
namespace PacProxyUsage
{
/// <summary>
/// Summary description for ProxyTest.
/// </summary>
class ProxyTest
{
  /// <summary>
  /// The main entry point for the application.
  /// </summary>
  [STAThread]
  static void Main(string[] args)
  {

            string DestinationUrl = "http://www.yahoo.com";


            try {
                WebClient wc = new WebClient();

                String s = wc.DownloadString(DestinationUrl);
                Console.WriteLine ( "Request was successful?" + s);
            }catch ( Exception ex ){
                Console.WriteLine ( "Error: {0}", ex.Message );
            }finally{

            }
            Console.ReadLine();
  }
}
}

History

1/28/2011
smart pig