WebClient Class
[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]
Provides common methods for sending data to and receiving data from a resource identified by a URI.
Namespace: System.Net4
Assembly: System (in System.dll)
The WebClient type exposes the following members.
| Name | Description | |
|---|---|---|
|
AllowReadStreamBuffering6 | Obsolete. |
|
AllowWriteStreamBuffering7 | Obsolete. |
|
BaseAddress8 | Gets or sets the base URI for requests made by a WebClient. |
|
CachePolicy9 | Gets or sets the application's cache policy for any resources obtained by this WebClient instance using WebRequest10 objects. |
|
CanRaiseEvents11 | Gets a value indicating whether the component can raise an event. (Inherited from Component3.) |
|
Container12 | Gets the IContainer13 that contains the Component3. (Inherited from Component3.) |
|
Credentials14 | Gets or sets the network credentials that are sent to the host and used to authenticate the request. |
|
DesignMode15 | Gets a value that indicates whether the Component3 is currently in design mode. (Inherited from Component3.) |
|
Encoding16 | Gets and sets the Encoding17 used to upload and download strings. |
|
Events18 | Gets the list of event handlers that are attached to this Component3. (Inherited from Component3.) |
|
Headers19 | Gets or sets a collection of header name/value pairs associated with the request. |
|
IsBusy20 | Gets whether a Web request is in progress. |
|
Proxy21 | Gets or sets the proxy used by this WebClient object. |
|
QueryString22 | Gets or sets a collection of query name/value pairs associated with the request. |
|
ResponseHeaders23 | Gets a collection of header name/value pairs associated with the response. |
|
Site24 | Gets or sets the ISite25 of the Component3. (Inherited from Component3.) |
|
UseDefaultCredentials26 | Gets or sets a Boolean27 value that controls whether the DefaultCredentials28 are sent with requests. |
| Name | Description | |
|---|---|---|
|
CancelAsync29 | Cancels a pending asynchronous operation. |
|
CreateObjRef30 | Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. (Inherited from MarshalByRefObject2.) |
|
Dispose()31 | Releases all resources used by the Component3. (Inherited from Component3.) |
|
Dispose(Boolean)32 | Releases the unmanaged resources used by the Component3 and optionally releases the managed resources. (Inherited from Component3.) |
|
DownloadData(String)33 | Downloads the resource with the specified URI as a Byte34 array. |
|
DownloadData(Uri)35 | Downloads the resource with the specified URI as a Byte34 array. |
|
DownloadDataAsync(Uri)36 | Downloads the specified resource as a Byte34 array. This method does not block the calling thread. |
|
DownloadDataAsync(Uri, Object)37 | Downloads the specified resource as a Byte34 array. This method does not block the calling thread. |
|
DownloadDataTaskAsync(String)38 | |
|
DownloadDataTaskAsync(Uri)39 | |
|
DownloadFile(String, String)40 | Downloads the resource with the specified URI to a local file. |
|
DownloadFile(Uri, String)41 | Downloads the resource with the specified URI to a local file. |
|
DownloadFileAsync(Uri, String)42 | Downloads, to a local file, the resource with the specified URI. This method does not block the calling thread. |
|
DownloadFileAsync(Uri, String, Object)43 | Downloads, to a local file, the resource with the specified URI. This method does not block the calling thread. |
|
DownloadFileTaskAsync(String, String)44 | |
|
DownloadFileTaskAsync(Uri, String)45 | |
|
DownloadString(String)46 | Downloads the requested resource as a String47. The resource to download is specified as a String47 containing the URI. |
|
DownloadString(Uri)48 | Downloads the requested resource as a String47. The resource to download is specified as a Uri49. |
|
DownloadStringAsync(Uri)50 | Downloads the resource specified as a Uri49. This method does not block the calling thread. |
|
DownloadStringAsync(Uri, Object)51 | Downloads the specified string to the specified resource. This method does not block the calling thread. |
|
DownloadStringTaskAsync(String)52 | |
|
DownloadStringTaskAsync(Uri)53 | |
|
Equals(Object)54 | Determines whether the specified Object1 is equal to the current Object1. (Inherited from Object1.) |
|
Finalize55 | Releases unmanaged resources and performs other cleanup operations before the Component3 is reclaimed by garbage collection. (Inherited from Component3.) |
|
GetHashCode56 | Serves as a hash function for a particular type. (Inherited from Object1.) |
|
GetLifetimeService57 | Retrieves the current lifetime service object that controls the lifetime policy for this instance. (Inherited from MarshalByRefObject2.) |
|
GetService58 | Returns an object that represents a service provided by the Component3 or by its Container59. (Inherited from Component3.) |
|
GetType60 | Gets the Type61 of the current instance. (Inherited from Object1.) |
|
GetWebRequest62 | Returns a WebRequest10 object for the specified resource. |
|
GetWebResponse(WebRequest)63 | Returns the WebResponse64 for the specified WebRequest10. |
|
GetWebResponse(WebRequest, IAsyncResult)65 | Returns the WebResponse64 for the specified WebRequest10 using the specified IAsyncResult66. |
|
InitializeLifetimeService67 | Obtains a lifetime service object to control the lifetime policy for this instance. (Inherited from MarshalByRefObject2.) |
|
MemberwiseClone()68 | Creates a shallow copy of the current Object1. (Inherited from Object1.) |
|
MemberwiseClone(Boolean)69 | Creates a shallow copy of the current MarshalByRefObject2 object. (Inherited from MarshalByRefObject2.) |
|
OnDownloadDataCompleted70 | Raises the DownloadDataCompleted71 event. |
|
OnDownloadFileCompleted72 | Raises the DownloadFileCompleted73 event. |
|
OnDownloadProgressChanged74 | Raises the DownloadProgressChanged75 event. |
|
OnDownloadStringCompleted76 | Raises the DownloadStringCompleted77 event. |
|
OnOpenReadCompleted78 | Raises the OpenReadCompleted79 event. |
|
OnOpenWriteCompleted80 | Raises the OpenWriteCompleted81 event. |
|
OnUploadDataCompleted82 | Raises the UploadDataCompleted83 event. |
|
OnUploadFileCompleted84 | Raises the UploadFileCompleted85 event. |
|
OnUploadProgressChanged86 | Raises the UploadProgressChanged87 event. |
|
OnUploadStringCompleted88 | Raises the UploadStringCompleted89 event. |
|
OnUploadValuesCompleted90 | Raises the UploadValuesCompleted91 event. |
|
OnWriteStreamClosed92 | Obsolete. |
|
OpenRead(String)93 | Opens a readable stream for the data downloaded from a resource with the URI specified as a String47. |
|
OpenRead(Uri)94 | Opens a readable stream for the data downloaded from a resource with the URI specified as a Uri49 |
|
OpenReadAsync(Uri)95 | Opens a readable stream containing the specified resource. This method does not block the calling thread. |
|
OpenReadAsync(Uri, Object)96 | Opens a readable stream containing the specified resource. This method does not block the calling thread. |
|
OpenReadTaskAsync(String)97 | |
|
OpenReadTaskAsync(Uri)98 | |
|
OpenWrite(String)99 | Opens a stream for writing data to the specified resource. |
|
OpenWrite(Uri)100 | Opens a stream for writing data to the specified resource. |
|
OpenWrite(String, String)101 | Opens a stream for writing data to the specified resource, using the specified method. |
|
OpenWrite(Uri, String)102 | Opens a stream for writing data to the specified resource, by using the specified method. |
|
OpenWriteAsync(Uri)103 | Opens a stream for writing data to the specified resource. This method does not block the calling thread. |
|
OpenWriteAsync(Uri, String)104 | Opens a stream for writing data to the specified resource. This method does not block the calling thread. |
|
OpenWriteAsync(Uri, String, Object)105 | Opens a stream for writing data to the specified resource, using the specified method. This method does not block the calling thread. |
|
OpenWriteTaskAsync(String)106 | |
|
OpenWriteTaskAsync(Uri)107 | |
|
OpenWriteTaskAsync(String, String)108 | |
|
OpenWriteTaskAsync(Uri, String)109 | |
|
ToString110 | Returns a String47 containing the name of the Component3, if any. This method should not be overridden. (Inherited from Component3.) |
|
UploadData(String, Byte[])111 | Uploads a data buffer to a resource identified by a URI. |
|
UploadData(Uri, Byte[])112 | Uploads a data buffer to a resource identified by a URI. |
|
UploadData(String, String, Byte[])113 | Uploads a data buffer to the specified resource, using the specified method. |
|
UploadData(Uri, String, Byte[])114 | Uploads a data buffer to the specified resource, using the specified method. |
|
UploadDataAsync(Uri, Byte[])115 | 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[])116 | 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)117 | Uploads a data buffer to a resource identified by a URI, using the specified method and identifying token. |
|
UploadDataTaskAsync(String, Byte[])118 | |
|
UploadDataTaskAsync(Uri, Byte[])119 | |
|
UploadDataTaskAsync(String, String, Byte[])120 | |
|
UploadDataTaskAsync(Uri, String, Byte[])121 | |
|
UploadFile(String, String)122 | Uploads the specified local file to a resource with the specified URI. |
|
UploadFile(Uri, String)123 | Uploads the specified local file to a resource with the specified URI. |
|
UploadFile(String, String, String)124 | Uploads the specified local file to the specified resource, using the specified method. |
|
UploadFile(Uri, String, String)125 | Uploads the specified local file to the specified resource, using the specified method. |
|
UploadFileAsync(Uri, String)126 | 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)127 | 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)128 | Uploads the specified local file to the specified resource, using the POST method. This method does not block the calling thread. |
|
UploadFileTaskAsync(String, String)129 | |
|
UploadFileTaskAsync(Uri, String)130 | |
|
UploadFileTaskAsync(String, String, String)131 | |
|
UploadFileTaskAsync(Uri, String, String)132 | |
|
UploadString(String, String)133 | Uploads the specified string to the specified resource, using the POST method. |
|
UploadString(Uri, String)134 | Uploads the specified string to the specified resource, using the POST method. |
|
UploadString(String, String, String)135 | Uploads the specified string to the specified resource, using the specified method. |
|
UploadString(Uri, String, String)136 | Uploads the specified string to the specified resource, using the specified method. |
|
UploadStringAsync(Uri, String)137 | Uploads the specified string to the specified resource. This method does not block the calling thread. |
|
UploadStringAsync(Uri, String, String)138 | Uploads the specified string to the specified resource. This method does not block the calling thread. |
|
UploadStringAsync(Uri, String, String, Object)139 | Uploads the specified string to the specified resource. This method does not block the calling thread. |
|
UploadStringTaskAsync(String, String)140 | |
|
UploadStringTaskAsync(Uri, String)141 | |
|
UploadStringTaskAsync(String, String, String)142 | |
|
UploadStringTaskAsync(Uri, String, String)143 | |
|
UploadValues(String, NameValueCollection)144 | Uploads the specified name/value collection to the resource identified by the specified URI. |
|
UploadValues(Uri, NameValueCollection)145 | Uploads the specified name/value collection to the resource identified by the specified URI. |
|
UploadValues(String, String, NameValueCollection)146 | Uploads the specified name/value collection to the resource identified by the specified URI, using the specified method. |
|
UploadValues(Uri, String, NameValueCollection)147 | Uploads the specified name/value collection to the resource identified by the specified URI, using the specified method. |
|
UploadValuesAsync(Uri, NameValueCollection)148 | 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)149 | 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)150 | 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. |
|
UploadValuesTaskAsync(String, NameValueCollection)151 | |
|
UploadValuesTaskAsync(Uri, NameValueCollection)152 | |
|
UploadValuesTaskAsync(String, String, NameValueCollection)153 | |
|
UploadValuesTaskAsync(Uri, String, NameValueCollection)154 |
| Name | Description | |
|---|---|---|
|
Disposed155 | Occurs when the component is disposed by a call to the Dispose156 method. (Inherited from Component3.) |
|
DownloadDataCompleted71 | Occurs when an asynchronous data download operation completes. |
|
DownloadFileCompleted73 | Occurs when an asynchronous file download operation completes. |
|
DownloadProgressChanged75 | Occurs when an asynchronous download operation successfully transfers some or all of the data. |
|
DownloadStringCompleted77 | Occurs when an asynchronous resource-download operation completes. |
|
OpenReadCompleted79 | Occurs when an asynchronous operation to open a stream containing a resource completes. |
|
OpenWriteCompleted81 | Occurs when an asynchronous operation to open a stream to write data to a resource completes. |
|
UploadDataCompleted83 | Occurs when an asynchronous data-upload operation completes. |
|
UploadFileCompleted85 | Occurs when an asynchronous file-upload operation completes. |
|
UploadProgressChanged87 | Occurs when an asynchronous upload operation successfully transfers some or all of the data. |
|
UploadStringCompleted89 | Occurs when an asynchronous string-upload operation completes. |
|
UploadValuesCompleted91 | Occurs when an asynchronous upload of a name/value collection completes. |
|
WriteStreamClosed157 | Obsolete. |
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 WebRequest10 class to provide access to resources. WebClient instances can access data with any WebRequest10 descendant registered with the WebRequest.RegisterPrefix158 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 |
|---|---|
|
Retrieves a Stream160 used to send data to the resource. |
|
|
Retrieves a Stream160 used to send data to the resource, without blocking the calling thread. |
|
|
Sends a byte array to the resource and returns a Byte34 array containing any response. |
|
|
Sends a Byte34 array to the resource, without blocking the calling thread. |
|
|
Sends a local file to the resource and returns a Byte34 array containing any response. |
|
|
Sends a local file to the resource, without blocking the calling thread. |
|
|
Sends a NameValueCollection167 to the resource and returns a Byte34 array containing any response. |
|
|
Sends a NameValueCollection167 to the resource and returns a Byte34 array containing any response, without blocking the calling thread. |
|
|
Sends a String47 to the resource, without blocking the calling thread. |
|
|
Sends a String47 to the resource, without blocking the calling thread. |
The following table describes WebClient methods for downloading data from a resource.
|
Method |
Description |
|---|---|
|
Returns the data from a resource as a Stream160. |
|
|
Returns the data from a resource, without blocking the calling thread. |
|
|
Downloads data from a resource and returns a Byte34 array. |
|
|
Downloads data from a resource and returns a Byte34 array, without blocking the calling thread. |
|
|
Downloads data from a resource to a local file. |
|
|
Downloads data from a resource to a local file, without blocking the calling thread. |
|
|
Downloads a String47 from a resource and returns a String47. |
|
|
Downloads a String47 from a resource, without blocking the calling thread. |
You can use the CancelAsync29 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 Headers19 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.
AllowAutoRedirect179 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 (); } }
-
WebPermission180
to access the requested URI or any URI that the request is redirected to. Associated enumeration: Connect.
Windows 8 Release Preview, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 SP2, 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 Requirements181.

Note