Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

WebClient Class

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

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

[ComVisibleAttribute(true)]
public class WebClient : Component

The WebClient type exposes the following members.

  NameDescription
Public methodWebClientInitializes a new instance of the WebClient class.
Top

  NameDescription
Public propertyAllowReadStreamBuffering Obsolete. Gets or sets a value that indicates whether to buffer the data read from the Internet resource for a WebClient instance.
Public propertyAllowWriteStreamBuffering Obsolete. Gets or sets a value that indicates whether to buffer the data written to the Internet resource for a WebClient instance.
Public propertyBaseAddressGets or sets the base URI for requests made by a WebClient.
Public propertyCachePolicyGets or sets the application's cache policy for any resources obtained by this WebClient instance using WebRequest objects.
Protected propertyCanRaiseEventsGets a value indicating whether the component can raise an event. (Inherited from Component.)
Public propertyContainerGets the IContainer that contains the Component. (Inherited from Component.)
Public propertyCredentialsGets or sets the network credentials that are sent to the host and used to authenticate the request.
Protected propertyDesignModeGets a value that indicates whether the Component is currently in design mode. (Inherited from Component.)
Public propertyEncodingGets and sets the Encoding used to upload and download strings.
Protected propertyEventsGets the list of event handlers that are attached to this Component. (Inherited from Component.)
Public propertyHeadersGets or sets a collection of header name/value pairs associated with the request.
Public propertyIsBusyGets whether a Web request is in progress.
Public propertyProxyGets or sets the proxy used by this WebClient object.
Public propertyQueryStringGets or sets a collection of query name/value pairs associated with the request.
Public propertyResponseHeadersGets a collection of header name/value pairs associated with the response.
Public propertySiteGets or sets the ISite of the Component. (Inherited from Component.)
Public propertyUseDefaultCredentialsGets or sets a Boolean value that controls whether the DefaultCredentials are sent with requests.
Top

  NameDescription
Public methodCancelAsyncCancels a pending asynchronous operation.
Public methodCreateObjRefCreates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. (Inherited from MarshalByRefObject.)
Public methodDispose()Releases all resources used by the Component. (Inherited from Component.)
Protected methodDispose(Boolean)Releases the unmanaged resources used by the Component and optionally releases the managed resources. (Inherited from Component.)
Public methodDownloadData(String)Downloads the resource as a Byte array from the URI specified.
Public methodDownloadData(Uri)Downloads the resource as a Byte array from the URI specified.
Public methodDownloadDataAsync(Uri)Downloads the resource as a Byte array from the URI specified as an asynchronous operation.
Public methodDownloadDataAsync(Uri, Object)Downloads the resource as a Byte array from the URI specified as an asynchronous operation.
Public methodDownloadDataTaskAsync(String)Downloads the resource as a Byte array from the URI specified as an asynchronous operation using a task object.
Public methodDownloadDataTaskAsync(Uri)Downloads the resource as a Byte array from the URI specified as an asynchronous operation using a task object.
Public methodDownloadFile(String, String)Downloads the resource with the specified URI to a local file.
Public methodDownloadFile(Uri, String)Downloads the resource with the specified URI to a local file.
Public methodDownloadFileAsync(Uri, String)Downloads, to a local file, the resource with the specified URI. This method does not block the calling thread.
Public methodDownloadFileAsync(Uri, String, Object)Downloads, to a local file, the resource with the specified URI. This method does not block the calling thread.
Public methodDownloadFileTaskAsync(String, String)Downloads the specified resource to a local file as an asynchronous operation using a task object.
Public methodDownloadFileTaskAsync(Uri, String)Downloads the specified resource to a local file as an asynchronous operation using a task object.
Public methodDownloadString(String)Downloads the requested resource as a String. The resource to download is specified as a String containing the URI.
Public methodDownloadString(Uri)Downloads the requested resource as a String. The resource to download is specified as a Uri.
Public methodDownloadStringAsync(Uri)Downloads the resource specified as a Uri. This method does not block the calling thread.
Public methodDownloadStringAsync(Uri, Object)Downloads the specified string to the specified resource. This method does not block the calling thread.
Public methodDownloadStringTaskAsync(String)Downloads the resource as a String from the URI specified as an asynchronous operation using a task object.
Public methodDownloadStringTaskAsync(Uri)Downloads the resource as a String from the URI specified as an asynchronous operation using a task object.
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodFinalizeReleases unmanaged resources and performs other cleanup operations before the Component is reclaimed by garbage collection. (Inherited from Component.)
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetLifetimeServiceRetrieves the current lifetime service object that controls the lifetime policy for this instance. (Inherited from MarshalByRefObject.)
Protected methodGetServiceReturns an object that represents a service provided by the Component or by its Container. (Inherited from Component.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodGetWebRequestReturns a WebRequest object for the specified resource.
Protected methodGetWebResponse(WebRequest)Returns the WebResponse for the specified WebRequest.
Protected methodGetWebResponse(WebRequest, IAsyncResult)Returns the WebResponse for the specified WebRequest using the specified IAsyncResult.
Public methodInitializeLifetimeServiceObtains a lifetime service object to control the lifetime policy for this instance. (Inherited from MarshalByRefObject.)
Protected methodMemberwiseClone()Creates a shallow copy of the current Object. (Inherited from Object.)
Protected methodMemberwiseClone(Boolean)Creates a shallow copy of the current MarshalByRefObject object. (Inherited from MarshalByRefObject.)
Protected methodOnDownloadDataCompletedRaises the DownloadDataCompleted event.
Protected methodOnDownloadFileCompletedRaises the DownloadFileCompleted event.
Protected methodOnDownloadProgressChangedRaises the DownloadProgressChanged event.
Protected methodOnDownloadStringCompletedRaises the DownloadStringCompleted event.
Protected methodOnOpenReadCompletedRaises the OpenReadCompleted event.
Protected methodOnOpenWriteCompletedRaises the OpenWriteCompleted event.
Protected methodOnUploadDataCompletedRaises the UploadDataCompleted event.
Protected methodOnUploadFileCompletedRaises the UploadFileCompleted event.
Protected methodOnUploadProgressChangedRaises the UploadProgressChanged event.
Protected methodOnUploadStringCompletedRaises the UploadStringCompleted event.
Protected methodOnUploadValuesCompletedRaises the UploadValuesCompleted event.
Protected methodOnWriteStreamClosed Obsolete. Raises the WriteStreamClosed event.
Public methodOpenRead(String)Opens a readable stream for the data downloaded from a resource with the URI specified as a String.
Public methodOpenRead(Uri)Opens a readable stream for the data downloaded from a resource with the URI specified as a Uri
Public methodOpenReadAsync(Uri)Opens a readable stream containing the specified resource. This method does not block the calling thread.
Public methodOpenReadAsync(Uri, Object)Opens a readable stream containing the specified resource. This method does not block the calling thread.
Public methodOpenReadTaskAsync(String)Opens a readable stream containing the specified resource as an asynchronous operation using a task object.
Public methodOpenReadTaskAsync(Uri)Opens a readable stream containing the specified resource as an asynchronous operation using a task object.
Public methodOpenWrite(String)Opens a stream for writing data to the specified resource.
Public methodOpenWrite(Uri)Opens a stream for writing data to the specified resource.
Public methodOpenWrite(String, String)Opens a stream for writing data to the specified resource, using the specified method.
Public methodOpenWrite(Uri, String)Opens a stream for writing data to the specified resource, by using the specified method.
Public methodOpenWriteAsync(Uri)Opens a stream for writing data to the specified resource. This method does not block the calling thread.
Public methodOpenWriteAsync(Uri, String)Opens a stream for writing data to the specified resource. This method does not block the calling thread.
Public methodOpenWriteAsync(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.
Public methodOpenWriteTaskAsync(String)Opens a stream for writing data to the specified resource as an asynchronous operation using a task object.
Public methodOpenWriteTaskAsync(Uri)Opens a stream for writing data to the specified resource as an asynchronous operation using a task object.
Public methodOpenWriteTaskAsync(String, String)Opens a stream for writing data to the specified resource as an asynchronous operation using a task object.
Public methodOpenWriteTaskAsync(Uri, String)Opens a stream for writing data to the specified resource as an asynchronous operation using a task object.
Public methodToStringReturns a String containing the name of the Component, if any. This method should not be overridden. (Inherited from Component.)
Public methodUploadData(String, Byte[])Uploads a data buffer to a resource identified by a URI.
Public methodUploadData(Uri, Byte[])Uploads a data buffer to a resource identified by a URI.
Public methodUploadData(String, String, Byte[])Uploads a data buffer to the specified resource, using the specified method.
Public methodUploadData(Uri, String, Byte[])Uploads a data buffer to the specified resource, using the specified method.
Public methodUploadDataAsync(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.
Public methodUploadDataAsync(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.
Public methodUploadDataAsync(Uri, String, Byte[], Object)Uploads a data buffer to a resource identified by a URI, using the specified method and identifying token.
Public methodUploadDataTaskAsync(String, Byte[])Uploads a data buffer that contains a Byte array to the URI specified as an asynchronous operation using a task object.
Public methodUploadDataTaskAsync(Uri, Byte[])Uploads a data buffer that contains a Byte array to the URI specified as an asynchronous operation using a task object.
Public methodUploadDataTaskAsync(String, String, Byte[])Uploads a data buffer that contains a Byte array to the URI specified as an asynchronous operation using a task object.
Public methodUploadDataTaskAsync(Uri, String, Byte[])Uploads a data buffer that contains a Byte array to the URI specified as an asynchronous operation using a task object.
Public methodUploadFile(String, String)Uploads the specified local file to a resource with the specified URI.
Public methodUploadFile(Uri, String)Uploads the specified local file to a resource with the specified URI.
Public methodUploadFile(String, String, String)Uploads the specified local file to the specified resource, using the specified method.
Public methodUploadFile(Uri, String, String)Uploads the specified local file to the specified resource, using the specified method.
Public methodUploadFileAsync(Uri, String)Uploads the specified local file to the specified resource, using the POST method. This method does not block the calling thread.
Public methodUploadFileAsync(Uri, String, String)Uploads the specified local file to the specified resource, using the POST method. This method does not block the calling thread.
Public methodUploadFileAsync(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.
Public methodUploadFileTaskAsync(String, String)Uploads the specified local file to a resource as an asynchronous operation using a task object.
Public methodUploadFileTaskAsync(Uri, String)Uploads the specified local file to a resource as an asynchronous operation using a task object.
Public methodUploadFileTaskAsync(String, String, String)Uploads the specified local file to a resource as an asynchronous operation using a task object.
Public methodUploadFileTaskAsync(Uri, String, String)Uploads the specified local file to a resource as an asynchronous operation using a task object.
Public methodUploadString(String, String)Uploads the specified string to the specified resource, using the POST method.
Public methodUploadString(Uri, String)Uploads the specified string to the specified resource, using the POST method.
Public methodUploadString(String, String, String)Uploads the specified string to the specified resource, using the specified method.
Public methodUploadString(Uri, String, String)Uploads the specified string to the specified resource, using the specified method.
Public methodUploadStringAsync(Uri, String)Uploads the specified string to the specified resource. This method does not block the calling thread.
Public methodUploadStringAsync(Uri, String, String)Uploads the specified string to the specified resource. This method does not block the calling thread.
Public methodUploadStringAsync(Uri, String, String, Object)Uploads the specified string to the specified resource. This method does not block the calling thread.
Public methodUploadStringTaskAsync(String, String)Uploads the specified string to the specified resource as an asynchronous operation using a task object.
Public methodUploadStringTaskAsync(Uri, String)Uploads the specified string to the specified resource as an asynchronous operation using a task object.
Public methodUploadStringTaskAsync(String, String, String)Uploads the specified string to the specified resource as an asynchronous operation using a task object.
Public methodUploadStringTaskAsync(Uri, String, String)Uploads the specified string to the specified resource as an asynchronous operation using a task object.
Public methodUploadValues(String, NameValueCollection)Uploads the specified name/value collection to the resource identified by the specified URI.
Public methodUploadValues(Uri, NameValueCollection)Uploads the specified name/value collection to the resource identified by the specified URI.
Public methodUploadValues(String, String, NameValueCollection)Uploads the specified name/value collection to the resource identified by the specified URI, using the specified method.
Public methodUploadValues(Uri, String, NameValueCollection)Uploads the specified name/value collection to the resource identified by the specified URI, using the specified method.
Public methodUploadValuesAsync(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.
Public methodUploadValuesAsync(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.
Public methodUploadValuesAsync(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.
Public methodUploadValuesTaskAsync(String, NameValueCollection)Uploads the specified name/value collection to the resource identified by the specified URI as an asynchronous operation using a task object.
Public methodUploadValuesTaskAsync(Uri, NameValueCollection)Uploads the specified name/value collection to the resource identified by the specified URI as an asynchronous operation using a task object.
Public methodUploadValuesTaskAsync(String, String, NameValueCollection)Uploads the specified name/value collection to the resource identified by the specified URI as an asynchronous operation using a task object.
Public methodUploadValuesTaskAsync(Uri, String, NameValueCollection)Uploads the specified name/value collection to the resource identified by the specified URI as an asynchronous operation using a task object.
Top

  NameDescription
Public eventDisposedOccurs when the component is disposed by a call to the Dispose method. (Inherited from Component.)
Public eventDownloadDataCompletedOccurs when an asynchronous data download operation completes.
Public eventDownloadFileCompletedOccurs when an asynchronous file download operation completes.
Public eventDownloadProgressChangedOccurs when an asynchronous download operation successfully transfers some or all of the data.
Public eventDownloadStringCompletedOccurs when an asynchronous resource-download operation completes.
Public eventOpenReadCompletedOccurs when an asynchronous operation to open a stream containing a resource completes.
Public eventOpenWriteCompletedOccurs when an asynchronous operation to open a stream to write data to a resource completes.
Public eventUploadDataCompletedOccurs when an asynchronous data-upload operation completes.
Public eventUploadFileCompletedOccurs when an asynchronous file-upload operation completes.
Public eventUploadProgressChangedOccurs when an asynchronous upload operation successfully transfers some or all of the data.
Public eventUploadStringCompletedOccurs when an asynchronous string-upload operation completes.
Public eventUploadValuesCompletedOccurs when an asynchronous upload of a name/value collection completes.
Public eventWriteStreamClosed Obsolete. Occurs when an asynchronous operation to write data to a resource using a write stream is closed.
Top

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.

NoteNote

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.

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

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 ();
    }
}

.NET Framework

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

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Supported in: Windows Phone 8.1

Supported in: Windows Phone Silverlight 8.1

Supported in: Windows Phone Silverlight 8

  • WebPermission 

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

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

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

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